How sign-in works

Your app never signs users in itself. It sends them to Access, the tenant's OpenID Connect (OIDC) and OAuth 2.0 provider. Access decides how the user authenticates, runs that authentication, and gives your app tokens.

Because the app only speaks OIDC, you can change the whole sign-in experience in IO or Access without touching the app.

Use the authorization code grant with PKCE for every app that signs users in: web apps, single-page apps and mobile apps. PKCE stops a stolen authorization code from being used. Public clients (no secret) must use it; confidential clients should.

1. 1

   Create a code verifier

   Generate a random code_verifier and derive code_challenge = BASE64URL(SHA-256(verifier)). Use the S256 method, not plain.

2. 2

   Send the user to Access

   Redirect the browser to the authorization endpoint with response_type=code, your client_id, a registered redirect_uri, scope (include openid), a random state, a nonce and the code_challenge.

3. 3

   Access authenticates the user

   If the user already has an Access session, this step is silent. Otherwise Access runs the sign-in, often by handing the user to an IO journey (see the next section).

4. 4

   Access redirects back with a code

   The browser returns to your redirect_uri with code and your state. Check that state matches what you sent.

5. 5

   Exchange the code for tokens

   Your app posts the code and the code_verifier to the token endpoint, from its backend when it has one. The code is short-lived (30 seconds by default) and works once.

6. 6

   Validate the ID token

   Check the signature against the JWKS, iss, aud (your client ID), exp and nonce. Then start your app's own session.

GET https://{tenant-host}/oauth/v1/authorize
  ?response_type=code
  &client_id={client-id}
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20profile%20email
  &state={random}
  &nonce={random}
  &code_challenge={challenge}
  &code_challenge_method=S256

curl -s https://{tenant-host}/oauth/v1/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=$CODE_VERIFIER
# A public client leaves out -u and sends -d client_id=$CLIENT_ID instead.

Read the endpoints from the discovery document instead of hard-coding them. These are the paths Access uses:

Access does not have to draw the sign-in pages itself. When the identity provider behind a web client is an IO journey, Access hands the user over to the journey and waits for the result. The app does not notice: it still talks only to Access.

1. 1

   Access starts the journey

   Access redirects the browser to the journey with a short-lived signed context_token. It carries the transaction, the requesting client, and the request context (scopes, acr_values, login_hint, locale). It expires after about 60 seconds, so the journey must read it right away.

2. 2

   The journey runs

   It starts with the Start (Access) node, which checks the token. Then it shows its pages and calls the platform services: password, passkey, OTP, consent.

3. 3

   The journey hands the user back

   The End Success (Access) node reports the authenticated user to Access from the backend, with the authentication methods used and the assurance level reached.

4. 4

   Access finishes the OIDC flow

   Access sets its session and redirects the browser to the app's redirect_uri with the authorization code.

Which journey runs depends on the web client's Identity provider setting and on the assurance level the app asks for with acr_values (or the client's Default ACRs). An app that needs a stronger sign-in, for example before a payment, asks for a higher level. If the current session doesn't meet it, Access sends the user through a step-up.

To build the journey itself, start with Getting started with Identity Orchestration.

There are two sessions. Keep them apart in your head.

Set the Access session lifetime in the Access admin console, under the system settings for sessions:

• Inactivity timeout: each interaction extends the session by this amount.
• Maximum session length: after this, the user signs in again, whatever their activity.
• Changes apply to new sessions and to sessions updated after you save. Existing idle sessions keep their old limits.

On the web client you can also limit parallel sessions. Allow simultaneous sessions off means a new sign-in cleans up the user's older sessions. With it on, Maximum simultaneous sessions (2 to 25) invalidates the oldest session when the limit is passed.

• Validate JWTs locally: verify the signature with the keys from /oauth/v1/keys, then check iss, aud and exp. Access rotates its signing keys, so look keys up by kid; don't pin one key.
• Opaque access tokens can't be read by the API. The API asks Access through token introspection.
• Refresh tokens are issued only with the authorization code grant and only when Issue refresh token is on. Each refresh returns a new refresh token and invalidates the old one.
• Replay protection: with Revoke all active refresh tokens when an old refresh token is used on, reusing an old refresh token revokes the whole chain and the user must sign in again. Keep it on.

What ends up inside the tokens depends on scopes and claims mapping. See Scopes and claims.

Clearing your app's cookie is not enough: the Access session would sign the user straight back in. Send the browser to the end session endpoint.

GET https://{tenant-host}/oauth/v1/logout
  ?id_token_hint={id-token}
  &post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out
  &state={random}

1. 1

   Access ends its session

   This signs the user out of every app that shares the Access session.

2. 2

   Front-channel logout

   Access returns a page with one hidden iframe per app in the session that has a Front-Channel Logout URL. Each app clears its own session there.

3. 3

   Redirect

   The browser goes to post_logout_redirect_uri. It must be the client's Post Logout Redirect URL or one of its Additional Post Logout Redirect URLs. Without one in the request, Access uses the default, or stays on its logged-out page if none is set.

• Turn on Delete access/refresh tokens on logout for the web client, especially for public clients using PKCE. Otherwise tokens stay valid until they expire.
• To drop one token without ending the session, call POST /oauth/v1/revoke with token and token_type_hint.
• Users who signed in through an external identity provider are signed out there only if single logout is set up for that provider in the Identity Broker.

For journey-side problems, see Troubleshooting Identity Orchestration.