Skip to main content

Client Scopes API

A Client Scope defines a custom OpenID Connect scope and the claims it grants — see Scopes and Claims for how scopes and claims work together, and Custom Fields for the User and Group side of one common use case: exposing a custom field's value as a claim. This page covers creating a Client Scope through the Management API; use the Client Scope Evaluation tool described in Management of Applications to check the result against a real client.

Creating a Client Scope​

curl -X POST "https://{your-id-server}/api/rest/v1/namespace/{nsIdOrCode}/clientscope" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support_ticket_id",
    "description": "Adds the users support ticket id as a claim",
    "mappers": [
      {
        "type": "USER_CUSTOM_FIELD",
        "name": "Support ticket id claim",
        "claimName": "support_ticket_id",
        "claimType": "STRING",
        "userCustomFieldPath": "supportTicketId",
        "addedToIdToken": true,
        "addedToUserinfo": true
      }
    ]
  }'

Requires access to the namespace and the CLIENT_SCOPE_CREATE permission. name must be unique within the namespace, and is the value clients request in the OIDC scope parameter.

Each entry in mappers produces one claim. type determines which of the other mapper fields apply:

Mapper typeProduces a claim from
USER_CUSTOM_FIELDA custom field value, addressed by userCustomFieldPath (for example myObject.exampleField for a nested value)
HARDCODED_CLAIMA fixed value, given directly in claimValue, typed according to claimType (STRING, LONG, DOUBLE, BOOLEAN, or JSON)
AUDIENCEAdds customAudience to the token's audiences, alongside any audiences it already has
ACRAdds a fixed acrValue; acrValueOverridden controls whether it replaces an ACR value the authentication flow already set

addedToIdToken, addedToAccessToken, addedToIntrospection, and addedToUserinfo each control one place the resulting claim can show up — set whichever ones your client needs to read it from.

Reading, updating, and deleting a Client Scope​

curl "https://{your-id-server}/api/rest/v1/namespace/{nsIdOrCode}/clientscope/{clientScopeId}" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

PUT replaces the whole Client Scope (including all of its mappers at once); PATCH updates part of it. Both require CLIENT_SCOPE_MODIFY; deleting with DELETE requires CLIENT_SCOPE_REMOVE.

Last updated on