Keycloak SCIM Authentication and Permissions

This article covers Keycloak's built-in SCIM API (26.7 preview, 26.8 supported). It is not about older third-party Keycloak SCIM extensions.

A SCIM connector does not log in like a person. Instead, it authenticates as an application using a client ID and client secret. Keycloak returns an OAuth access token, and the connector sends that token with each SCIM request. Keycloak then verifies the token, checks that the token was issued for this SCIM API (the audience), and checks whether the client's service account has permission to perform the requested operation.

This guide builds that setup step by step on Keycloak 26.7.3. It uses two example clients (scim-reader and scim-provisioner) so you can see exactly how read-only and provisioning permissions differ. Keycloak does not require two clients — one confidential client with the right roles is enough. Enable the server feature and realm SCIM switch first; the steps below assume realm golinuxcloud already exposes /realms/golinuxcloud/scim/v2.

Quick answer

To call Keycloak's SCIM API, create a confidential client with Service account roles enabled and obtain an access token with the client credentials grant. The token must contain the realm's SCIM base URL in its aud claim. Give the service account view-users for read-only access, or manage-users when the connector must create, update, or delete users and groups.

Client ID + client secret
        |
        v
OAuth client_credentials
        |
        v
   Access token
        |
        v
SCIM URL in aud? ----no----> 401
        |
       yes
        v
Required realm-management role? ----no----> 403
        |
       yes
        v
   SCIM request allowed

How Keycloak SCIM authentication works

Keycloak SCIM uses OAuth 2.0 bearer tokens (RFC 6750). There is no separate SCIM username or password and no API key header defined by Keycloak itself. Only confidential clients can access the SCIM endpoints.

Three things decide whether the SCIM request succeeds:

1. Client authentication — the client ID and secret authenticate the SCIM application to Keycloak's token endpoint.
2. Token audience — the resulting access token must identify the SCIM API as an intended recipient (aud includes the realm SCIM base URL).
3. Authorization — the service account's realm-management roles (and on 26.8+, the intersection with dedicated-scope role mappings) determine what the caller can do.

Authentication (is the token valid and intended for this SCIM API?) is separate from authorization (is this service account allowed to perform the operation?).

Think of the HTTP status codes this way:

• 401 Unauthorized — Keycloak cannot accept this token for the SCIM API (missing bearer token, invalid JWT, or wrong audience).
• 403 Forbidden — the token is accepted, but the caller is not allowed to perform this operation (missing role, or a protected administrative user or group).

Symptom-first fixes live on Fix Keycloak SCIM 401 and 403.

SCIM provisions accounts; it does not replace OIDC or SAML login — see LDAP vs SAML vs OIDC vs SCIM. For vocabulary around service provider versus identity provider, see IdP vs service provider.

Lab layout

This article uses a dedicated Keycloak process on port 18082 so it does not touch another lab on 8080.

Export the SCIM base URL once in your shell. Every curl example appends /Users, /Groups, or /ServiceProviderConfig to it:

SCIM_BASE='http://127.0.0.1:18082/realms/golinuxcloud/scim/v2'

Create a confidential SCIM client

A SCIM connector is a server-side application, not a person signing in through a browser. In Keycloak, create it as a confidential client by turning Client authentication on. That lets the application authenticate with its own client credentials. Enable Service account roles so those credentials represent a non-human Keycloak service account.

Public clients are for applications that cannot safely keep a client secret, such as browser or mobile apps. Keycloak does not support them for SCIM API calls.

Open http://127.0.0.1:18082/admin/, sign in as the bootstrap admin, and select realm golinuxcloud. Create the read example client first:

1. Open Clients and click Create client.
2. Set Client ID to scim-reader and click Next.
3. On Capability config, switch Client authentication to On.
4. Under Authentication flow, clear Standard flow and enable Service account roles only.
5. Click Next, leave login URLs empty, and click Save.

Repeat the wizard for scim-provisioner if you want a separate provision example. One client is enough for production when you assign the roles the connector needs.

When Service account roles is enabled, Keycloak creates an internal user for that client. For scim-reader, the username is service-account-scim-reader. Roles on the Service account roles tab belong to this non-human identity, not to an employee account.

The Capability config section should show client authentication on and only service account roles enabled:

After Save, open Credentials on each client. Copy the generated secret from behind the eye icon into your connector vault — not into screenshots or tickets:

Treat the client secret like a password. Anyone who obtains it can authenticate as this service account and receive whatever permissions its access token allows.

Request a SCIM access token with client credentials

Keycloak issues tokens through the client credentials grant. The client_credentials grant returns an access token for the service account. The connector requests another access token when the current one expires; there is normally no user-style refresh-token workflow here.

Copy the generated secret from the Credentials tab, then export it in your shell:

READER_SECRET='paste-generated-secret-here'

Request a token for the read client:

curl -sS -X POST 'http://127.0.0.1:18082/realms/golinuxcloud/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=scim-reader' \
  -d "client_secret=$READER_SECRET"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "profile email"
}

expires_in is the lifetime in seconds for this realm and client. Request a new token after role or mapper changes; existing JWTs keep their old claims.

Store only the access token when you script SCIM calls:

READER_TOKEN=$(curl -sS -X POST 'http://127.0.0.1:18082/realms/golinuxcloud/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=scim-reader' \
  -d "client_secret=$READER_SECRET" | jq -r '.access_token')

The assignment prints nothing. Use the same pattern with scim-provisioner and its secret when you test writes.

Add the SCIM audience to the Keycloak access token

aud is short for audience. It tells the receiving API which service the token was intended for. A token can be correctly signed by Keycloak and still be rejected by SCIM if the SCIM base URL is not one of its audiences.

A valid client-credentials token is not automatically valid for SCIM. Keycloak checks that the JWT aud claim includes the exact SCIM base URL for the realm — scheme, host, port, and /realms/<realm>/scim/v2 path. Without that audience, SCIM returns 401 with Invalid token audience even when view-users is assigned. That is authentication, not a missing role.

Add an Audience protocol mapper on each client's dedicated scope:

1. Open Clients → scim-reader → Client scopes.
2. Click scim-reader-dedicated in the assigned list.
3. Click Configure a new mapper → Audience (or open the existing scim-audience mapper).
4. Set Name to scim-audience.
5. Leave Included Client Audience empty. Set Included Custom Audience to http://127.0.0.1:18082/realms/golinuxcloud/scim/v2.
6. Enable Add to access token and click Save.

Repeat on scim-provisioner-dedicated for the provisioner client.

Behind a reverse proxy, configure the audience with the externally visible SCIM base URL expected by Keycloak, rather than blindly copying an internal container hostname. The audience comparison is URL-sensitive, so 127.0.0.1, localhost, different ports, and different schemes are not interchangeable.

You can decode the token to verify that the mapper actually added the SCIM audience. The jq pipeline below handles base64url padding that a plain base64 -d pipe often misses:

curl -sS -X POST 'http://127.0.0.1:18082/realms/golinuxcloud/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=scim-reader' \
  -d "client_secret=$READER_SECRET" \
  | jq -r '.access_token | split(".")[1] | gsub("-";"+") | gsub("_";"/") | . + "==" | @base64d | fromjson | {azp, aud}'

{
  "azp": "scim-reader",
  "aud": [
    "http://127.0.0.1:18082/realms/golinuxcloud/scim/v2",
    "realm-management",
    "account"
  ]
}

The SCIM URL appears in aud alongside built-in audiences. azp identifies the client that requested the token.

Which Keycloak roles are required for SCIM?

SCIM defines API operations, but it does not introduce a new Keycloak role such as scim-admin. Keycloak authorizes SCIM requests using existing administrative roles on the built-in realm-management client. For example, view-users allows reading user resources, while manage-users permits create, update, and delete operations on users and groups.

On the tested Keycloak 26.7.3 setup, assign these permissions under Clients → <client> → Service account roles, not under the client's own Roles tab. Keycloak 26.8+ additionally requires the corresponding role scope mappings described below.

Read-only access with view-users

For a read-only connector — one that periodically reads users and group membership from Keycloak but cannot create, modify, or delete them:

1. Open Clients → scim-reader → Service account roles.
2. Click Assign role → Filter by clients → realm-management.
3. Check view-users and click Assign.

In this Keycloak 26.7.3 lab, assigning view-users also brought the query permissions needed for discovery. If you configure narrower permissions manually, remember that user searches require query-users, group searches require query-groups, and discovery accepts either one.

Provisioning access with manage-users

For connectors that create, update, patch, or delete users and groups, assign manage-users on the provisioner client:

manage-users covers write operations for both users and groups in this setup. You do not need a separate group-management role for standard SCIM provisioning.

If Fine-Grained Admin Permissions are enabled, these broad roles can be restricted further so the SCIM client can access only selected users or groups.

Keycloak 26.8 and later: dedicated scope and Full Scope Allowed

On Keycloak 26.8+, do not enable Full Scope Allowed on the SCIM client. Set Full Scope Allowed to Off on the dedicated scope (scim-reader-dedicated, and so on). Assign the same realm-management roles under Clients → <client> → Client scopes → <client>-dedicated → Scope → Assign role, and on Service account roles. The access token receives the intersection of those two role lists.

1. Open Clients → scim-reader → Client scopes → scim-reader-dedicated.
2. Open the Scope tab and confirm Full scope allowed is Off.
3. Click Assign role → Client roles → filter to realm-management → assign view-users (or manage-users on a provisioner client).
4. Assign the same role on Service account roles as in the sections above.

If a role appears only on Service account roles but not on the dedicated scope mappings, the token omits it when Full Scope Allowed is off. On 26.7.3 in this lab, service-account roles alone were enough; on 26.8+, configure both places before you test tokens.

Keycloak SCIM role matrix

These are the roles Keycloak checks for each SCIM operation. The Observed result column reflects what I saw on Keycloak 26.7.3 with SCIM enabled on realm golinuxcloud.

query-users and view-users are not the same. query-users permits searching and listing users; view-users permits returning complete user resources. In my 26.7.3 test, a token with only query-users could report totalResults while returning no entries in Resources. Most read-only SCIM connectors should use view-users rather than assembling only query permissions.

view-realm alone did not unlock SCIM discovery in this lab.

With scim-reader and view-users, reads succeed but POST /Users returns 403 until you assign manage-users on a provisioner client and request a new token.

Verify the configuration

First test a discovery endpoint with the reader token:

curl -sS -w '\nHTTP %{http_code}\n' -H "Authorization: Bearer $READER_TOKEN" \
  -H 'Accept: application/scim+json' "$SCIM_BASE/ServiceProviderConfig" | tail -3

... "authenticationSchemes":[{"type":"oauthbearertoken","name":"OAuth Bearer Token"...
HTTP 200

HTTP 200 on ServiceProviderConfig confirms bearer authentication, audience, and at least query-level permission.

List users to confirm read access to resource bodies:

curl -sS -H "Authorization: Bearer $READER_TOKEN" -H 'Accept: application/scim+json' \
  "$SCIM_BASE/Users?count=10" | jq '{totalResults, Resources: [.Resources[]?.userName]}'

{
  "totalResults": 1,
  "Resources": [
    "ada"
  ]
}

User ada appears in the list. Service account users created for clients do not show up as ordinary SCIM users.

Optional: separate read-only and provisioning clients

Keycloak requires only one SCIM client, but you may deliberately separate read-only and provisioning integrations:

• scim-reader + view-users: reads users and groups without write permission.
• scim-provisioner + manage-users: creates, modifies, and deletes users and groups.

Separate credentials reduce the permissions exposed if the read-only connector's secret is compromised. Do not assign realm-admin or manage-realm to SCIM service accounts unless you intend to grant broad admin API access through the same token.

SCIM tokens vs Admin REST API tokens

Both APIs live on the same Keycloak realm, but they are not interchangeable. SCIM relies on the same administrative permission model as the Admin REST API, but SCIM adds its own endpoint and audience requirements.

A token that works against /admin/realms/.../users is not automatically accepted by SCIM. Configure SCIM audience and roles on the connector client, then test against /scim/v2 endpoints.

Troubleshooting 401 and 403

Step-by-step reproductions and curl transcripts for each status code are in the companion troubleshooting article for SCIM 401 and 403 responses.

Summary

Keycloak SCIM authentication is OAuth bearer tokens from confidential service-account clients. The client credentials grant supplies the JWT; an Audience mapper adds the realm SCIM base URL to aud; realm-management roles on the service account decide whether discovery, read, or write succeeds. On Keycloak 26.8+, keep Full Scope Allowed off and assign the same roles on the dedicated scope and the service account so the token receives their intersection.

In this lab, scim-reader with view-users could list and read user ada but could not create users. scim-provisioner with manage-users could create accounts once the same audience mapper was in place. The access token lifetime here was five minutes (expires_in: 300), and role changes required a fresh token.

When you configure a real SCIM connector, enable SCIM on the realm first, then configure the audience and only the roles the connector actually needs before you point Entra or another system at the SCIM URL. If a request still returns 401 or 403 after you assign the expected role, check token and audience problems before changing roles.

References

• Keycloak Server Administration Guide — SCIM
• Keycloak 26.8.0 release announcement — SCIM API supported
• RFC 7644 — SCIM Protocol
• RFC 6750 — OAuth 2.0 Bearer Token Usage