OIDC lab with Keycloak and curl

⏱ ~20 min

Use Keycloak (RHBK) realm cv to obtain a JWT and call the NeuroFace CV / Computer Vision API protected by RHCL AuthPolicy. This module is optional but recommended if you want machine-to-machine access to /api/ppe/status and /v1/predict.

Register for the workshop

If you have not already, open the registration portal and enter your email:

https://workshop-registration.apps.cluster.example.com

You receive a workshop user (userN) and redirect to this lab guide with ?USER_NAME=userN. This is the same registration step described in Welcome.

Step 1 — Log in to Keycloak (realm cv)

Keycloak exposes two consoles. Use the one that matches what you need:

Console URL Use case

Admin Console (realm cv)

keycloak.apps.cluster.example.com/admin/cv/console/

Create / manage OIDC clients, view users and roles

Account Console

keycloak.apps.cluster.example.com/realms/cv/account/

View your profile, sessions, and authorized applications

  1. Open the Admin Console for realm cv: https://keycloak.apps.cluster.example.com/admin/cv/console/

  2. Sign in as guest (register first) / Welcome123!

  3. You should see the Clients section in the left sidebar

Do not use https://sso.apps.cluster.example.com/ — that alias redirects to the master admin console where workshop users do not exist. Always use https://keycloak.apps.cluster.example.com/ for both admin and account consoles.

For API access only (no UI needed), skip to Step 3 and use client_credentials with curl.

Step 1b — OIDC self-service via Developer Hub (recommended)

Instead of creating clients manually in the Keycloak Admin Console, use the bundled scaffolder templates in Developer Hub. They call Keycloak’s Admin REST API through the /keycloak proxy using the backstage-provisioner service account.

Create a client

  1. Open https://developer-hub.apps.cluster.example.com/

  2. Log in with guest (register first) / Welcome123! (Keycloak realm backstage)

  3. Create → OIDC credentials self-service (Keycloak cv)

  4. Target API: Computer Vision OpenAPI (neuroface-cv-openapi)

  5. Client label: a short name such as team-a or guest (register first) (lowercase letters, numbers, hyphens only)

  6. Grant type: Client credentials (M2M)

  7. Plan tier: Free (100 req/h) or Gold (500 req/h) — the template embeds this as JWT claim plan for Kuadrant rate limits on /v1/predict

  8. Requester / Owner: your workshop user and group

  9. Run the template — the task result page shows Client ID and Client Secret once (copy them immediately)

The generated client ID follows the pattern client-neuroface-cv-openapi-<label>.

The template sets webOrigins: [""] on new clients so Swagger UI’s OAuth2 *Authorize dialog can fetch tokens from Keycloak directly in the browser. It also adds a plan protocol mapper so tokens include the selected rate-limit tier (free = 100 req/h, gold = 500 req/h on /v1/predict).

Revoke a client

When you no longer need a self-service client:

  1. Create → Revoke OIDC client (Keycloak cv)

  2. Select the same Target API and Client label used at creation

  3. Confirm deletion on the task result page

You can still create clients manually in the Admin Console (Step 2) or use the pre-provisioned client-cv-guest (register first) client from Vault.

Step 2 — Create your own OIDC client in Admin Console (optional)

Workshop users have roles view-clients and manage-clients on the realm-management client, so you can create your own clients in realm cv.

  1. In the Admin Console (realm cv), go to Clients → Create client

  2. Client ID: my-cv-client-guest (register first)

  3. Client authentication: On (confidential)

  4. Valid redirect URI: https://developer-hub.apps.cluster.example.com/*

  5. Save → Credentials tab → copy the Client secret

A pre-provisioned client client-cv-guest (register first) already exists. Its secret is synced from Vault via External Secrets Operator into namespace keycloak-system as Secret keycloak-client-cv-guest (register first). You can use it directly in Step 3 without creating anything.

Step 3 — Get a token with curl (client_credentials)

Use the pre-provisioned client or your own from Step 2.

hub-login guest (register first)
export CLIENT_ID="client-cv-guest (register first)"
export CLIENT_SECRET=$(oc get secret keycloak-client-cv-guest (register first) -n keycloak-system \
  -o jsonpath='{.data.clientSecret}' 2>/dev/null | base64 -d)
TOKEN=$(curl -sk -X POST "https://keycloak.apps.cluster.example.com/realms/cv/protocol/openid-connect/token" \
  -d "grant_type=client_credentials&client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('access_token',''))")
echo "Token length: ${#TOKEN}"

The OIDC issuer for RHCL policies is https://sso.apps.cluster.example.com/realms/cv. Token requests use the same RHBK instance via https://keycloak.apps.cluster.example.com/. If Token length: 0, verify: oc get secret keycloak-client-cv-guest (register first) -n keycloak-system. The secret is synced from Vault path secret/hub/keycloak/realms/cv/userN.

Step 4 — Call the CV API with Bearer token

The gateway routes /api/ppe/status to the spoke OVMS health endpoint (OIDC-protected).

curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://neuroface-cv.apps.cluster.example.com/api/ppe/status" | python3 -m json.tool
Expected output (example)
{
  "status": "ok"
}

Step 5 — Try Swagger UI in Developer Hub

  1. Open https://developer-hub.apps.cluster.example.com/

  2. Log in with guest (register first) / Welcome123! (Keycloak realm backstage)

  3. Catalog → System IAM / OIDC Realms → API Computer Vision OpenAPI

  4. Open the Definition tab (embedded Swagger UI)

  5. Click Authorize (lock icon)

  6. Under OAuth2ClientCredentials, enter:

    • client_id: from Step 1b (self-service) or Step 2/3 (e.g. client-cv-guest (register first) or client-neuroface-cv-openapi-<label>)

    • client_secret: the matching secret from the scaffolder result page, Vault-synced secret, or Admin Console Credentials tab

  7. Click Authorize, then Close

  8. Expand /api/ppe/status (or /v1/predict) → Try it out → Execute

Swagger UI uses the OpenAPI OAuth2 client_credentials flow — it POSTs directly to https://keycloak.apps.cluster.example.com/realms/cv/protocol/openid-connect/token and sends the returned Bearer token on API calls. You do not paste a token manually.

If Execute fails with a CORS error, confirm the OIDC client has webOrigins set (self-service clients include *). The gateway also injects CORS headers and handles OPTIONS preflight for browser requests.

You can verify the same endpoint with curl using the token from Step 3 before trying Swagger UI.

Step 6 — AI Gateway with APIKEY (contrast with OIDC)

The NeuroFace CV route (neuroface-cv) accepts OIDC Bearer tokens only. The AI Gateway (Kuadrant, legacy) HTTPRoute ai-maas (hostname ai-gateway.apps.cluster.example.com) is dual auth — it accepts a Kuadrant APIKEY (below) or a realm-maas OIDC Bearer token (see Module 05) on the same endpoint.

# Request API key: Developer Hub → Catalog → workshop-kuadrant-apis → MaaS LLM (ai-gateway) → Kuadrant tab
curl -sk -H "Authorization: APIKEY <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama-scout-17b","messages":[{"role":"user","content":"Hello"}]}' \
  "https://ai-gateway.apps.cluster.example.com/v1/chat/completions" | head -c 400
echo

What you learned

  • RHBK realms (cv, neuroface, maas) issue JWTs for RHCL OIDCPolicy

  • client_credentials grant works for machine-to-machine API access

  • Developer Hub scaffolder templates create and revoke OIDC clients in realm cv (self-service), with selectable plan tiers (free/gold) embedded as JWT claim plan

  • Workshop users can also create OIDC clients via the Keycloak Admin Console

  • Developer Hub IAM catalog exposes OpenAPI specs with Swagger Try it out (OAuth2 client_credentials)

  • HTTPRoute ai-maas (hostname ai-gateway.apps.cluster.example.com) accepts Kuadrant APIKEY or realm-maas OIDC on the same endpoint (dual auth)

Next

Continue with Module 05 — MaaS API key and curl inference.