Web clients and API clients in Access

Access has two kinds of clients, and they are not interchangeable. Pick by what the caller does.

1. 1

   Open Access admin → Web clients and add a client

   Give it a Name (only shown to admins) and a Client ID. Let the console generate the ID unless the app needs a fixed one.

2. 2

   Choose the authentication method

   Client secret or Private key JWT for apps with a backend that can keep a secret. Public for single-page and mobile apps, which can't. See the table below.

3. 3

   Set the grant type to Authorization code

   Leave Implicit and Resource owner password credentials off. Add Device code only for devices without a browser or keyboard.

4. 4

   Choose the access token format

   JWT if your APIs validate tokens themselves. Opaque if they call Access to introspect them.

5. 5

   Add the redirect URIs

   Redirect URL is required for the Authorization code grant. Add other environments under Additional redirect URLs. Access compares them exactly, so include the path.

6. 6

   Set the lifetimes

   Access grant validity (how long the code lives, e.g. 30 seconds) and Access token validity (e.g. 900 seconds) are both required. Turn on Issue refresh token only if the app needs to stay signed in without a browser round trip.

7. 7

   Assign scopes

   Put openid and the scopes the app always needs under Default scopes. Put scopes the app sometimes asks for under Additional scopes. See Scopes and claims.

8. 8

   Choose the identity provider

   Select the Identity provider that signs the users in: an Identity Orchestration journey, the Identity Broker, or another provider set up in Access. This decides which sign-in the user sees.

9. 9

   Complete the OpenID Connect settings

   Because openid is among the scopes, Access asks for the relying party settings: ID token validity, Post Logout Redirect URL, Front-Channel Logout URL, and Delete access/refresh tokens on logout (turn it on).

10. 10

    Save and hand over the values

    Give the app team the client ID, the secret or how to register its key, and the discovery URL https://{tenant-host}/oauth/.well-known/openid-configuration.

Use PKCE with the S256 method for every authorization code client, public or not. It costs nothing and stops stolen codes from being redeemed.

• Short access tokens limit the damage of a leaked token. Refresh tokens keep the user signed in meanwhile.
• Keep Revoke all active refresh tokens when an old refresh token is used on. A replayed refresh token then revokes the whole chain.
• The Access single sign-on session has its own lifetime, separate from the tokens. See How sign-in works.

A backend, a pipeline or an Identity Orchestration flow that calls the service APIs uses a web client with the Client credentials grant. Two settings decide what its token can do:

1. 1

   Add a web client

   Access admin → Web clients. Authentication method Client secret or Private key JWT. Grant type Client credentials only.

2. 2

   Set Access token validity

   It is required even though there is no user.

3. 3

   Add the audiences

   Add each service the client calls to Default audiences. Each API page lists the audience it expects.

4. 4

   Add the scopes

   Add the scopes the client always needs to Default scopes. Use the scope builder to pick the scopes for the operations you call. Grant the least you need.

5. 5

   Check the length

   Join the Default scopes with spaces and count: keep the string within 1024 characters.

6. 6

   Request a token and test

   Call the token endpoint, then one read operation of each service.

curl -s https://{tenant-host}/oauth/v1/token \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

# Service APIs live under the tenant host
curl -s https://{tenant-host}/identity-store/api/v1/... \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Additional scopes are issued only when the token request names them with scope= (space-separated). A request that names scopes gets only those, so one client can hold more scopes than fit in one token.

To see what a client really gets, decode a fresh token's payload and read aud and scope. Never paste a live token into a website.

Access's own configuration API, at https://{tenant-host}/oauth/api/v1/configuration, manages web clients, API clients, scopes, identity providers, SAML service providers, web hooks and assurance levels. Use it to keep Access configuration in code. It takes an API client, not a web client.

1. 1

   Add an API client

   Access admin → API clients. Give it a name and a client ID.

2. 2

   Choose how it authenticates

   Client secret (HTTP Basic) or Private key JWT. With Private key JWT, register the public key as a PEM (-----BEGIN PUBLIC KEY-----), not as a JWK.

3. 3

   Allow only the APIs it needs

   Each Access API is allowed separately, as an onegini_api_* scope. The configuration API is onegini_api_config. Events and end-user APIs are separate permissions.

4. 4

   Call the API directly

   There is no token request. Send the client's credentials on every call: Basic, or a freshly signed JWT as a bearer token.

curl -s https://{tenant-host}/oauth/api/v1/configuration/web-clients \
  -u "$API_CLIENT_ID:$API_CLIENT_SECRET"

• Creating a web client through the API needs access_token_expires_in, and with the Authorization code grant also access_grant_expires_in, although the spec doesn't mark them required.
• A scope PATCH replaces the whole scope: send every field. A web client PATCH keeps the fields you leave out.
• A hashed client secret must be in PHC form ($bcrypt$...), not the usual $2b$ form.
• Reads by ID can show the old version for about two minutes after a change. Tokens reflect the change at once.

All operations and more pitfalls: Access configuration API.