Keycloak Service Accounts: Client Credentials Flow for Machine-to-Machine Auth

In this article we will enable a Keycloak service account and request machine-to-machine access tokens with the client_credentials grant on Keycloak 26.7.3. The lab client billing-sync authenticates as itself—no human login—and calls the orders-api resource server with a JWT that carries order-reader.

Service accounts still need the same role and scope discipline as human users. A confidential client with Client authentication enabled gets a built-in service user, but that user receives no roles until you assign them, and client scope mappings still filter what appears in the token. The walkthrough covers enablement, role assignment, and a token request you can replay with curl.

User login vs service account

Interactive OIDC flows authenticate a human. Machine-to-machine (M2M) flows authenticate the client application itself.

  Human login (authorization code / password grant)
  ─────────────────────────────────────────────────
  ┌────────┐   user credentials    ┌──────────┐   user session   ┌─────────────┐
  │ Person │ ────────────────────► │ Keycloak │ ───────────────► │ Access token│
  └────────┘                       └──────────┘   sub = user id  │ sub = user  │
                                                                   └─────────────┘

  Service account (client_credentials grant)
  ──────────────────────────────────────────
  ┌──────────────┐  client_id + secret   ┌──────────┐  no user session  ┌─────────────┐
  │ billing-sync │ ─────────────────────► │ Keycloak │ ────────────────► │ Access token│
  │ (cron job)   │                       └──────────┘                   │ sub = SA user│
  └──────────────┘                                                       │ azp = client │
                                                                         └─────────────┘

The access token still has a sub claim, but it points at the client's built-in service account user (service-account-billing-sync), not a person who typed a password.

What this service account lab creates

You need the golinuxcloud realm and client orders-api with role order-reader from earlier lessons.

At the end of this lab you will have:

• Confidential client billing-sync with Client authentication on and Service accounts roles enabled
• Service account user service-account-billing-sync with realm role employee and client role orders-api / order-reader
• Role scope mappings on the roles client scope that expose only employee and order-reader in the token
• A successful client_credentials token request and a failed attempt with a wrong secret
• Decoded JWT showing realm_access, resource_access.orders-api, and aud: orders-api
• A simulated orders-api authorization check that accepts the token

  billing-sync (M2M client)                orders-api (resource server)
  ├── Client secret in vault               ├── Expects aud = orders-api
  ├── Service account user                 ├── Checks resource_access.orders-api.roles
  └── client_credentials ──► JWT ─────────►└── Allows order-reader

Enable the service account

A service account is not a separate product feature you install—it is a confidential OIDC client with service accounts turned on.

Create client billing-sync:

1. Switch to realm golinuxcloud.
2. Open Clients → Create client.
3. Set Client ID to billing-sync and save.
4. On Settings (or Capability config in newer layouts), enable:
   • Client authentication — makes the client confidential
   • Service accounts roles — creates the built-in service account user and allows client_credentials
5. Turn off browser-oriented flows you do not need for M2M (Standard flow, Direct access grants).
6. Set Full scope allowed to Off so role intersection behavior is visible in the lab.

Copy the client secret from the Credentials tab. The lab secret is shown inline in curl examples below—rotate it if this realm is shared.

Both toggles matter together:

• Client authentication off → public client → client_credentials blocked with unauthorized_client
• Service accounts roles off → confidential client exists but cannot obtain a service-account token

Built-in service account user

When you enable Service accounts roles, Keycloak creates a dedicated user in the same realm:

• Username pattern: service-account-<clientId> (lab: service-account-billing-sync)
• Enabled by default, not meant for password login
• Appears under Clients → billing-sync → Service account roles (not in the normal Users list unless you search for it)

Open Service account roles to assign realm and client roles the same way you would for a human user. The token's sub claim is this user's UUID; preferred_username is service-account-billing-sync.

Do not create a fake human user with a long-lived password for cron jobs or microservice calls—use the service account path this section enables.

Assign service account roles

Role assignment on the service account user is necessary but not sufficient for the token. Admin Console shows what the identity holds; the JWT shows what client scopes expose.

On Clients → billing-sync → Service account roles, assign:

1. Realm role employee
2. Client role orders-api / order-reader

The service account now holds both roles in effective mappings. Request a token next and you will see why assignment alone is not enough when Full scope allowed is off.

Role intersection (assigned ∩ scope mappings)

This is the step most M2M tutorials skip—and the main reason teams report "role assigned but not in token."

Token roles are the intersection of:

• Roles assigned to the service account user (directly or via composites/groups)
• Roles exposed through the client's linked client scopes (role scope mappings on scopes such as roles)

  Service account holds          roles scope exposes          Token contains
  ─────────────────────          ───────────────────          ──────────────
  employee                    ∩  employee                 =  employee
  developer (composite)          (employee only mapped)
  order-reader on orders-api  ∩  order-reader             =  order-reader
  uma_authorization              (not mapped)             =  (omitted)

With Full scope allowed off on billing-sync, a freshly assigned role does not appear in the JWT until you add a matching entry under Client scopes → roles → Scope (role scope mappings).

Add mappings on the shared roles scope:

1. Open Client scopes → roles → Scope tab.
2. Under Realm Roles, assign employee.
3. Under Client Roles, select client orders-api and assign order-reader.

To prove intersection, assign composite realm role developer to the service account but do not add developer to the roles scope mappings. Admin Console lists developer; the access token still shows only employee because developer is outside the scope.

See Keycloak realm roles vs client roles for composite inheritance and Keycloak client scopes explained for how scopes link to clients.

Request an access token

The OIDC token endpoint issues M2M tokens when grant_type=client_credentials and the client authenticates with its secret.

Request a token for billing-sync with curl:

curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials' -d 'client_id=billing-sync' -d 'client_secret=GFxbhTZNFYm9U0gK2DXA5Gee5geZQu21gdKSyGWeIU9faVurpWpUcJfSYILJdKu7GUm7OtwUxQwzVR36WdAg6H'

Sample response (access token trimmed):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJUMk9SQ0dkbnd0Wl96UWpsYXY2WUc1S2h2a29KMndCdnFzWFlyc0FlcEhRIn0...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "profile email"
}

There is no refresh_token field—expected for client_credentials, covered in the next section. Decode the access token payload to read role claims:

curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials' -d 'client_id=billing-sync' -d 'client_secret=GFxbhTZNFYm9U0gK2DXA5Gee5geZQu21gdKSyGWeIU9faVurpWpUcJfSYILJdKu7GUm7OtwUxQwzVR36WdAg6H' | python3 -c "import sys,json,base64; t=json.load(sys.stdin)['access_token']; p=t.split('.')[1]; p+='='*(-len(p)%4); c=json.loads(base64.urlsafe_b64decode(p)); print(json.dumps({k:c.get(k) for k in ('realm_access','resource_access','azp','aud','preferred_username')}, indent=2))"

Sample decoded payload:

{
  "realm_access": {
    "roles": [
      "employee"
    ]
  },
  "resource_access": {
    "orders-api": {
      "roles": [
        "order-reader"
      ]
    }
  },
  "azp": "billing-sync",
  "aud": "orders-api",
  "preferred_username": "service-account-billing-sync"
}

azp is the client that requested the token (billing-sync). aud tells resource servers which API the token targets—orders-api in this lab.

Before role scope mappings

If you request a token immediately after assigning roles but before adding scope mappings (with Full scope allowed off), decode the access token the same way—the payload shows empty role buckets even though Service account roles lists employee and order-reader:

{
  "realm_access": null,
  "resource_access": null,
  "azp": "billing-sync",
  "preferred_username": "service-account-billing-sync"
}

Roles are assigned in Admin Console; the scope layer has not released them into the JWT yet.

Why there is normally no refresh token

client_credentials is a one-shot grant for non-interactive clients. Keycloak returns an access token and does not create a user session tied to a person sitting at a browser.

When the access token expires (expires_in, commonly 300 seconds in dev), the job requests a new token with the same client_credentials call. Missing refresh_token is not a failure—it is the default design.

Long-lived delegated access for automated jobs that must act on behalf of a user belongs to offline tokens and refreshable sessions, not service accounts.

Client authentication options

The lab uses a client secret in the token POST body—the fastest path for learning. Production M2M should prefer stronger authenticators when your platform supports them.

A shared secret in source control is a common source of invalid_client after rotation. Store secrets in a vault, rotate on leak, and prefer asymmetric client authentication for production microservices.

Call a protected API

This section is not a full API development guide—it shows what orders-api would check on the JWT your job already obtained.

Store the access token in a shell variable and export it so the Python check in the next step can read it:

export M2M_TOKEN=$(curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials' -d 'client_id=billing-sync' -d 'client_secret=GFxbhTZNFYm9U0gK2DXA5Gee5geZQu21gdKSyGWeIU9faVurpWpUcJfSYILJdKu7GUm7OtwUxQwzVR36WdAg6H' | python3 -c 'import sys,json; print(json.load(sys.stdin)["access_token"])')

Simulate orders-api authorization—the resource server validates audience and client roles before running business logic:

python3 -c "import base64,json,os; t=os.environ['M2M_TOKEN'].split('.')[1]; t+='='*(-len(t)%4); c=json.loads(base64.urlsafe_b64decode(t)); roles=c.get('resource_access',{}).get('orders-api',{}).get('roles',[]); aud=c.get('aud'); print('API auth OK' if aud=='orders-api' and 'order-reader' in roles else 'API auth FAIL: aud=%s roles=%s' % (aud, roles))"

Sample output when the token matches lab expectations:

API auth OK

A real API would also validate issuer, signature, and exp with a JWT library or OAuth resource-server middleware. If the API rejects the token despite correct roles, check aud—add an audience mapper in Keycloak protocol mappers when the resource server expects a specific audience claim.

Service account vs offline token

Service accounts and offline tokens solve different problems.

Use a service account when no human is present. Use offline access when a user delegated rights and you need refresh without re-login. Session lifecycle details live in the planned sessions lesson referenced from Create and manage Keycloak users.

Service account vs fake human user

Avoid creating a batch-user human account with a static password for machine jobs.

Keycloak models M2M correctly with service accounts—use them instead of weakening human account policies.

Common problems

Wrong-secret example for comparison:

curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials' -d 'client_id=billing-sync' -d 'client_secret=wrong-secret'

{"error":"unauthorized_client","error_description":"Invalid client or Invalid client credentials"}

Summary

Keycloak service accounts let confidential clients authenticate as themselves with the client_credentials grant—no human login and normally no refresh token. The lab client billing-sync obtained a JWT whose sub is service-account-billing-sync, whose azp is billing-sync, and whose resource_access.orders-api.roles includes order-reader for the downstream API.

The intersection rule is the troubleshooting key: roles on the service account user must also be exposed through client scope role mappings when Full scope allowed is off. Assignment alone left realm_access and resource_access null; adding employee and order-reader to the roles scope mappings released them into the token.

For production, replace long-lived shared secrets with signed JWT or mTLS client authentication, keep M2M clients off browser login flows, and validate aud at the resource server. Tighten token shape next with audience or custom claim mappers, or narrow default scopes on the M2M client.

References

• Keycloak Server Administration Guide — Service accounts
• OpenID Connect Core — Client Authentication
• RFC 6749 — Client Credentials Grant
• Keycloak documentation — Client scopes and role scope mappings