Client settings

See every setting an administrator can set on a OneiD client, what each one controls and the rules OneiD applies to it.

View as Markdown

Every application that signs users in or calls the token endpoint is registered in OneiD as a client. An administrator creates and changes clients in the admin console or through the Admin API. There is no dynamic client registration. This page lists every client setting, so that developers know what to ask for and administrators know what each setting does.

Settings

Setting Values Default What it controls
Client ID Text Set by the administrator The identifier your application sends as client_id. It appears as aud in ID tokens and client_id in access tokens.
Display name Text Set by the administrator A readable name for the application. In client credentials access tokens it is the name claim.
Client type public or confidential Set by the administrator public for browser, mobile and desktop applications, which cannot keep a secret. confidential for server-side applications and services, which hold a client secret.
Grant types authorization_code, refresh_token, client_credentials Set by the administrator Which grants the client may use. client_credentials is for confidential clients only.
PKCE required On or off On Whether the client must send a PKCE code challenge. Always on for public clients. An administrator can turn it off for a confidential client; keep it on.
Redirect URIs List of URIs None Where OneiD may send the authorisation response. See redirect URI rules.
Post-logout redirect URIs List of URIs None Where OneiD may send the browser after sign-out. Must match exactly; the redirect URI rules apply.
Allowed scopes Identity scopes and API scopes Set by the administrator The scopes the client may request. A request for any other scope gets invalid_scope.
Allowed CORS origins List of origins None Browser origins that may call the token, userinfo and revocation endpoints cross-origin. See CORS origins.
Consent required On or off Set by the administrator Whether users see a consent page for this client. See consent.
Access token lifetime Duration 1 hour How long access tokens for this client are valid.
ID token lifetime Duration 20 minutes How long ID tokens for this client are valid.
Refresh token lifetime Duration 14 days How long a refresh token chain lasts. Refreshes do not extend it.
Enabled Enabled or disabled Set by the administrator A disabled client cannot sign users in or get tokens.
Client secret One secret, optional expiry Confidential clients only How a confidential client authenticates. See client secret.

The authorization code lifetime (5 minutes) is fixed and cannot be changed per client.

Notes

Client type and PKCE

  • A public client has no secret. PKCE with S256 is always required.
  • A confidential client has one client secret. PKCE is required by default. Keep it on: it protects the authorization code even for server-side applications.

Grant types

  • authorization_code: user sign-in. The client needs the redirect URIs your application uses.
  • refresh_token: lets the client exchange refresh tokens. The client also has to request offline_access to receive one, so offline_access must be among its allowed scopes.
  • client_credentials: a service acting for itself, with no user. Confidential clients only.

Redirect URI rules

  • OneiD compares redirect URIs exactly. There are no wildcards.
  • https is required, except http on loopback addresses: localhost, 127.0.0.1 and [::1].
  • Private-use schemes in reverse-domain form, such as com.example.app:/callback, are allowed for public clients only.
  • A redirect URI must not contain a fragment (#...).

Allowed scopes

  • Identity scopes: openid, profile, email, phone, roles, offline_access. There is no address scope.
  • API scopes are created by an administrator, for example orders.read. None exist by default.
  • The privileged scopes admin_api, admin_api_readonly and admin_console_webhooks are for OneiD’s own administration. Only a full administrator (role All) can allow them for a client, and they are removed at sign-in for users without an administrator role. Do not use them in applications.

CORS origins

  • Enter each origin as scheme://host[:port], without a path, for example https://app.example.com.
  • Origins take effect only on an enabled client. Changes take effect within about 15 seconds.
  • Introspection never allows cross-origin requests. Discovery and JWKS answer any origin without registration.
  • CORS requests never carry OneiD cookies.
  • Consent required (explicit): users see a consent page for the scopes the client requests. If the user ticks “remember”, OneiD keeps the decision and does not ask again for the same set of scopes. Users can untick optional scopes. A refusal returns access_denied.
  • Consent not required (implicit): typical for first-party applications. No consent page is shown, unless the request carries prompt=consent.

Enabled and disabled

When a client is disabled:

  • the authorize and logout endpoints answer unauthorized_client,
  • the token, introspection and revocation endpoints answer invalid_client,
  • OneiD revokes the client’s tokens.

Client secret

  • A confidential client has exactly one client secret.
  • When OneiD generates the secret, the value is shown once. Copy it into your application’s secret store straight away; it cannot be displayed again.
  • An administrator can supply a secret instead. It must be at least 32 characters long.
  • A secret can have an optional expiry. After it, the token endpoint answers invalid_client with “The client secret has expired.”
  • Replacing a secret takes effect immediately: the old secret stops working at once. Plan the change: have the new value ready to deploy to your application when the administrator replaces it.
  • Disabling the secret disables the client and revokes its tokens.
  • Your application sends the secret with client_secret_basic (recommended) or client_secret_post. Never put a secret in a browser, mobile or desktop application.

Note private_key_jwt and mutual TLS client authentication are not available. There is no setting for a client public key or certificate.

Endpoint permissions

OneiD derives each client’s endpoint permissions from its grant types and client type. Administrators do not set them.

Endpoint Allowed when
Token Always
Revocation Always
Authorize The client has the authorization_code grant
End session (logout) The client has the authorization_code grant
Introspection The client is confidential

Learn more