Configure service account clients

What you’ll accomplish

You’ll configure a Keycloak client using the OAuth 2.0 Client Credentials Grant so that automated processes — CI/CD pipelines, backend services, and scripts — can obtain tokens and access SSO-protected applications without a user session.

Prerequisites

• UDS Core deployed
• UDS CLI installed
• A UDS Package CR for the workload that needs machine-to-machine access
• The clientId of the target SSO-protected application (used as the token audience)

Before you begin

Service account tokens (Client Credentials Grant) are designed for machine-to-machine authentication where there is no interactive user. Key characteristics:

• Tokens have a service-account- username prefix and include a client_id claim
• The aud (audience) claim is not set by default — you must add an audience mapper to allow the token to access a specific SSO-protected application
• serviceAccountsEnabled: true requires standardFlowEnabled: false and is incompatible with publicClient: true

Steps

1. Add a service account client to the Package CR

   Configure an SSO client with serviceAccountsEnabled: true and an audience mapper pointing to the target Authservice client:

   package.yaml

   apiVersion: uds.dev/v1alpha1
   kind: Package
   metadata:
     name: my-automation
     namespace: argo
   spec:
     sso:
       - name: httpbin-api-client
         clientId: httpbin-api-client
         standardFlowEnabled: false
         serviceAccountsEnabled: true
         protocolMappers:
           - name: audience
             protocol: "openid-connect"
             protocolMapper: "oidc-audience-mapper"
             config:
               # Set to the clientId of the Authservice-protected application
               included.client.audience: "uds-core-httpbin"
               access.token.claim: "true"
               introspection.token.claim: "true"
               id.token.claim: "false"
               lightweight.claim: "false"
               userinfo.token.claim: "false"

   Note

   The included.client.audience value must match the clientId of the target application’s Authservice client — not the clientId of this service account client. This is what allows the token to be accepted by Authservice when accessing the target application.

2. Apply the Package CR

   uds zarf tools kubectl apply -f package.yaml

   The UDS Operator creates the Keycloak client and stores the client secret in a Kubernetes secret in the application namespace.

3. Retrieve the client secret

   The client secret is stored in a Kubernetes secret named sso-client-<client-id>:

   # Linux
   uds zarf tools kubectl get secret -n <namespace> sso-client-<client-id> -o jsonpath='{.data.secret}' | base64 -d
   # macOS
   uds zarf tools kubectl get secret -n <namespace> sso-client-<client-id> -o jsonpath='{.data.secret}' | base64 -D

   Tip

   You can also reference the secret directly in your application’s deployment using secretKeyRef to avoid storing the secret value in your configuration.

4. (Optional) Configure multiple audiences

   If a service account token needs access to multiple Authservice-protected applications, add separate audience mappers for each target.

   Note

   This example uses included.custom.audience rather than included.client.audience from Step 1. Use included.client.audience when you want to reference an existing Keycloak client by its clientId — Keycloak validates that the client exists. Use included.custom.audience when you need to set an arbitrary audience string that may not match a Keycloak client ID exactly. For multiple audiences, included.custom.audience is generally more flexible.

   package.yaml

   spec:
     sso:
       - name: multi-target-client
         clientId: multi-target-client
         standardFlowEnabled: false
         serviceAccountsEnabled: true
         defaultClientScopes:
           - openid
         protocolMappers:
           - name: audience-app-1
             protocol: "openid-connect"
             protocolMapper: "oidc-audience-mapper"
             config:
               included.custom.audience: "uds-core-app-1"
               access.token.claim: "true"
               introspection.token.claim: "true"
               id.token.claim: "true"
               lightweight.claim: "true"
               userinfo.token.claim: "true"
           - name: audience-app-2
             protocol: "openid-connect"
             protocolMapper: "oidc-audience-mapper"
             config:
               included.custom.audience: "uds-core-app-2"
               access.token.claim: "true"
               introspection.token.claim: "true"
               id.token.claim: "true"
               lightweight.claim: "true"
               userinfo.token.claim: "true"

   Danger

   Adding multiple audiences extends the trust boundary for the token — a compromised token can now access multiple applications. Use multiple audiences only when the applications share the same trust requirements and are operated by the same team.

   Note

   Multiple client types can coexist in the same Package CR. A single Package can define an Authservice client, a device flow client, and one or more service account clients as separate entries in the sso array.

Verification

Confirm the service account client is configured correctly:

1. Log in to the Keycloak admin UI (uds realm)
2. Go to Clients and find your client ID
3. Verify Service accounts roles is On and Standard flow is Off

Test token retrieval:

# Replace <domain>, <client-id>, and <client-secret> with your values
curl -s -X POST \
  "https://sso.<domain>/realms/uds/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=<client-id>" \
  -d "client_secret=<client-secret>" \
  | jq .

A successful response includes an access_token. Verify the aud claim includes the expected audience:

# Extract and decode the access token payload
# Linux
echo "<access_token>" | cut -d. -f2 | base64 -d 2>/dev/null | jq .aud
# macOS
echo "<access_token>" | cut -d. -f2 | base64 -D 2>/dev/null | jq .aud

Alternatively, paste the token into jwt.io for a visual breakdown.

Troubleshooting

Problem: 401 when accessing an Authservice-protected application

Symptoms: Token is obtained successfully but the application returns 401.

Solution: Verify the audience mapper is pointing to the correct target. The included.client.audience value must match the clientId of the target application’s Authservice SSO client — not this service account client’s own clientId.

Check the decoded token’s aud claim, or paste it into jwt.io to inspect it visually:

# Decode the access token payload (replace TOKEN with the actual token value)
# Linux
echo "TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .aud
# macOS
echo "TOKEN" | cut -d. -f2 | base64 -D 2>/dev/null | jq .aud

Problem: serviceAccountsEnabled: true rejected by the operator

Symptoms: Package CR fails to apply with a validation error.

Solution: Ensure standardFlowEnabled is set to false and publicClient is not set to true. Both are incompatible with service accounts:

sso:
  - name: my-service-client
    clientId: my-service-client
    standardFlowEnabled: false   # Required
    serviceAccountsEnabled: true
    # publicClient: true         # Do not set — incompatible with service accounts

Problem: Client secret is not found in the namespace

Symptoms: The expected Kubernetes secret does not exist after applying the Package CR.

Solution: Check the UDS Operator logs for errors during client creation:

uds zarf tools kubectl logs -n pepr-system -l app=pepr-uds-core-watcher --tail=50 | grep <client-id>

Related Documentation

• OAuth 2.0 Client Credentials Grant — specification for the service account flow
• Package CR reference — full SSO client and protocolMappers field specification

Next steps

These guides and concepts may be useful to explore next:

Configure OAuth 2.0 device flow Enable device authorization for CLI tools and headless apps.

Protect non-OIDC apps with SSO Add SSO protection to applications that have no native OIDC support.