How OneiD works

OneiD is an OAuth 2.0 authorization server and OpenID Connect provider with an admin console. Your applications send users to OneiD to sign in, and receive tokens that say who the user is and what the application may do. This page explains the parts you work with and how a sign-in moves between them.

Your OneiD address

Every OneiD deployment has one address, for example https://YOUR_ONEID. All endpoints live under it, and the discovery document at https://YOUR_ONEID/.well-known/openid-configuration lists them.

The address also identifies OneiD in tokens. This value is called the issuer, and it ends with a slash: https://YOUR_ONEID/. The iss claim in every token carries the same value. If your library compares issuers exactly, use the value from the discovery document, including the slash.

One deployment has one issuer, one database and one source of users. There are no tenants or organisations inside a deployment. Each customer gets its own deployment, either hosted by OneiD or run in the customer’s own environment.

Applications are clients

Every application that signs users in or calls an API with OneiD tokens is registered as a client. An administrator registers clients in the admin console or through the Admin API. Developers cannot register clients themselves, and there is no dynamic client registration.

A client is one of two types:

A public client cannot keep a secret, because its code runs on the user’s device. A confidential client runs on a server you control and proves its identity with its client secret. For confidential clients an administrator can turn PKCE off. Keep it on.

Users and sign-in sources

Each deployment takes its users from one sign-in source:

• OneiD accounts. Administrators create users in the admin console. Users sign in with a password and, if enabled, an authenticator-app code.
• LDAP or Active Directory. Users sign in with their directory user name and password. OneiD checks the password against the directory and does not store it.
• An OpenID Connect provider, such as Okta. OneiD sends users to that provider to sign in.

Your application does not need to know which source is in use. It always talks to OneiD in the same way. The idp claim tells you where the user signed in. See Where users come from.

Scopes

A scope names something the application asks for. The application lists scopes in the scope parameter when it sends the user to sign in.

An administrator can also create API scopes, such as orders.read. None exist by default. API scopes appear in the access token’s scope claim and add no other claims.

A client may only request the scopes it is allowed. Any other scope returns invalid_scope. See Scopes, claims and roles.

Tokens

OneiD issues three kinds of token to applications.

ID tokens and access tokens are signed JWTs. Applications and APIs check the signature with the public keys OneiD publishes at /.well-known/jwks. Refresh tokens and authorisation codes are opaque. Do not try to read them.

An administrator can change the access, ID and refresh token lifetimes for each client. See Tokens.

Sessions and single sign-on

When a user signs in, OneiD keeps a browser session for 8 hours, extended while the user is active. While that session lasts, other applications that send the user to OneiD get a sign-in without a password prompt. This is single sign-on.

Your application keeps its own session too. OneiD does not tell other applications when a user signs out of one of them. See Sessions, prompt and max_age and Sign-out.

The admin console

Administrators manage OneiD in the admin console. They can:

• register applications, manage client secrets and choose allowed scopes
• create users, assign roles, unlock accounts, reset MFA and passwords
• manage roles, role claims and API scopes
• list sessions and revoke tokens
• read the audit log
• rotate signing keys
• import and export clients

As a developer you usually do not use the console yourself. You send your administrator the values described in Register an application.

How a sign-in works

This is the authorization code flow with PKCE, which every application that signs users in uses.

1. The user opens your application and chooses Sign in.
2. Your application creates a random code_verifier, a state and a nonce,
   and redirects the browser to https://YOUR_ONEID/connect/authorize
   with client_id, redirect_uri, scope, state, nonce and the code_challenge.
3. OneiD checks the client and the redirect URI.
4. If the user has no OneiD session, OneiD shows its sign-in page.
   The user signs in (and enters an authenticator code if MFA applies).
5. If the client asks for consent, OneiD shows the consent page.
6. OneiD redirects the browser back to your redirect_uri
   with a one-time code, your state and iss.
7. Your application checks state and iss, then sends the code and
   the code_verifier to https://YOUR_ONEID/connect/token.
8. OneiD returns an ID token, an access token and,
   if requested and allowed, a refresh token.
9. Your application validates the ID token, starts its own session
   and calls your API with the access token.
10. Your API validates the access token and checks its scope.

The details, with every request, are in Authorization code flow with PKCE.

Glossary

Learn more

• Your first sign-in
• Choose a flow
• Register an application
• Endpoints