Choose a flow

Answer two questions to find the OAuth 2.0 grant and client type your application needs with OneiD.

View as Markdown

OneiD supports two ways for an application to get tokens: the authorization code flow with PKCE when a user signs in, and client credentials when a service calls an API on its own behalf. Refresh tokens keep a user sign-in going without asking the user again. Answer the questions below to find the right one.

Question 1: Is a user present?

Yes, a person signs in. Use the authorization code flow with PKCE. The application sends the user’s browser to OneiD, the user signs in there, and the application receives a code that it exchanges for tokens. Your application never sees the user’s password.

No, a program calls an API on its own behalf. Use client credentials. A background job, a scheduled task or one service calling another authenticates with its client ID and secret and receives an access token. There is no user, so there is no ID token and no refresh token.

Question 2: Where does your code run?

The answer decides the client type and whether the application can hold a secret.

In the browser

A single-page application (React, Angular, Vue or plain JavaScript) runs entirely on the user’s device. Anyone can read its code, so it cannot keep a secret.

  • Client type: public
  • Grant: authorization code with PKCE
  • Your administrator also registers your application’s origin as an allowed CORS origin, because the browser calls the token endpoint directly.

See Browser applications and CORS.

On a server

A server-side web application (Node.js, ASP.NET Core, Go, Python, Java) handles the sign-in on the server. The browser only carries redirects; the server talks to the token endpoint and can keep a secret.

  • Client type: confidential
  • Grant: authorization code with PKCE, plus the client secret at the token endpoint

PKCE is required for confidential clients by default. Keep it on.

On a phone or a desktop

A mobile or desktop application is installed on the user’s device. Like a browser application, it cannot keep a secret: anyone can extract one from the installed app.

  • Client type: public
  • Grant: authorization code with PKCE, using the system browser and a private-use URI scheme or a loopback redirect

See Mobile and desktop applications.

On a machine, without a user

A service, daemon or scheduled job runs on infrastructure you control.

  • Client type: confidential
  • Grant: client credentials

Public clients cannot use client credentials. See Client credentials for services.

An API that receives tokens

An API does not sign anyone in. It receives access tokens from the applications above and validates them. Most APIs do not need their own client. See Protect an API.

Question 3: Must the user stay signed in?

Access tokens last 1 hour by default. If your application calls an API for longer than that without bringing the user back to OneiD, ask for a refresh token:

  • request the offline_access scope, and
  • ask your administrator to give the client the refresh token grant.

OneiD rotates refresh tokens: every refresh returns a new refresh token, and you must store it. A chain of refreshes ends when the original refresh token’s lifetime runs out, 14 days by default. The user then signs in again. See Refresh tokens.

Client credentials do not use refresh tokens. A service requests a new access token when the old one is about to expire.

Summary

Application Client type Grant Start with
Single-page application public Authorization code with PKCE JavaScript, React, Angular
Server-side web application confidential Authorization code with PKCE and client secret Node.js, .NET, Go, Python, Java
Mobile or desktop application public Authorization code with PKCE Mobile and desktop applications
Service, daemon or job confidential Client credentials curl, Client credentials for services
API Usually none Validates access tokens Node.js, .NET, Go, Python, Java

Add offline_access and the refresh token grant to any user-facing row when the user must stay signed in beyond the access token’s lifetime.

Flows OneiD does not support

Not supported OneiD does not support the implicit flow, the hybrid flow, the resource owner password credentials (ROPC) grant, the device authorization flow, token exchange or CIBA.

What to use instead:

You were going to use Use instead
Implicit flow (response_type=token or id_token) Authorization code with PKCE as a public client. Only response_type=code is accepted.
Hybrid flow (code id_token) Authorization code with PKCE.
Password grant, where your application collects the user’s password Authorization code with PKCE, so the user signs in on OneiD’s page. For a program without a user, client credentials.
Device flow, for a device without a usable browser OneiD has no replacement for this. If the device has a system browser, use authorization code with PKCE as a native application.
private_key_jwt or mTLS client authentication A client secret, sent with client_secret_basic.

Learn more