OAuth/OIDC in your tenant

Tenant management

Open OAuth Management in the tenant sidebar. Clients registers applications with a stable client ID, display name, client type, redirect URIs, enabled status, assigned scopes, the restrictScopes setting, and a consent choice. Scopes defines the access names available within the tenant. Access Token Management configures token format, lifetime, claim mapping, issuance policy, client assignment, and confidential client secrets. ID Token Management configures ID token signing, lifetime, and the claims in ID tokens and UserInfo responses. Key Management generates and rotates JWT signing keys. Metadata Management edits endpoint paths and custom discovery fields.

BTL administrators use the same controls under BTL Admin, OAuth Management for BTL's own organization. These pages always apply to BTL and do not offer a tenant selector. BTL access and tenant access are authorized separately.

New clients start disabled. A blank client is also restricted to its assigned exclusive scopes; the presets for applications that sign users in turn that restriction off, so they can use common scopes such as openid. Client type records whether an application can protect credentials. A confidential client needs a generated secret before it can authenticate to the token endpoint. A confidential client that hosts an API can also be made a resource server, which lets it introspect access tokens issued to any client in the tenant. The saved client name appears on the consent page. Consent can be requested every time, remembered for approved scopes, or skipped for a trusted client. Users still sign in when consent is skipped. A public client cannot prove its identity, so skipping consent for one lets another application that uses its client ID receive an answer without the user being asked; the client editor warns about this. When you create a client, Start from can fill in the usual settings for a web application, single-page application, native or desktop application, or machine-to-machine service; every setting stays editable before you save. Flow policy turns each grant, response type and response mode on or off independently, and a client can select only the choices Flow policy allows. A client keeps choices that Flow policy later turns off, but they are not used until Flow policy allows them again. Flow policy also sets the browser session and authorization code lifetimes within supported ranges.

Saving a client revokes the access and refresh tokens issued to it, its pending authorization codes and its remembered consent when the change affects what was granted: its type, flows, PKCE or consent setting, scopes, redirect URIs or token managers, or turning it off. A new name, a resource server change, or turning a client on revokes nothing. The client editor warns before a save that revokes.

In User Management, an administrator with the credential permission can set a tenant user's password. Share it privately. Setting a new password signs out that tenant user and revokes their existing OAuth tokens and pending codes. Tenant users do not use BTL administrator credentials.

Read the Scopes guide for configuration steps, access rules, and discovery behavior. Open Clients or open Scopes to manage a tenant you are authorized to access.

Token managers and defaults

Every client uses one access token manager and one ID token manager. In each management page, one enabled manager is marked Default. When you create a client, its manager selects start on the defaults, and you can choose another manager before saving. Choosing a manager other than the default, or changing a client's manager later, needs the assign permission for that kind of manager. Changing the default affects clients created afterwards; existing clients keep their manager. The default cannot be disabled or deleted until another manager becomes the default.

Each manager lists the standard claims for its token, such as sub, aud, and exp, filled in with their protocol values. You can set your own value as text, an attribute, or a JavaScript expression, and omit optional claims. aud also accepts a list, and an ID token's audience must still include the client ID. The issuer is always the tenant URL. In ID tokens, nonce, at_hash, c_hash, and azp are set by the protocol and cannot be changed, because they protect client applications against replay and token substitution. So are iat, auth_time, and amr, which tell the application when and how the user signed in. In access tokens, client_id always names the client that requested the token, a custom scope may only leave granted scopes out, and an earlier exp also ends the token sooner for introspection and UserInfo. Required claims can be changed but not removed. Values are checked when a token is issued, and a value outside its allowed range stops issuance rather than producing a broken token.

Applications recognize a user by the issuer and sub together, so each sub value belongs to the first user or client that receives it and is never given to anyone else, even after that user is deleted. A setting that would give a value to someone else stops issuance with server_error, and the tenant's Audit and Logs record subject_in_use. A fixed text, or an attribute that can move between accounts such as the email address, therefore works for one user only. The sub row also offers the user ID with a fixed prefix or suffix, which stays different for every user.

Changing a claim changes what a token says, not how this service treats it. Expiry, revocation, granted scopes, introspection, and UserInfo always use the service's stored records.

OpenID Connect

Every tenant includes the built-in openid, profile, email, and offline_access scopes. Their names are fixed and they cannot be deleted, but their description and common or exclusive access can change. offline_access asks for a refresh token, so the consent page lists it, and consent remembered without it does not cover it. A client granted openid receives an ID token signed by its ID token manager's key and published in the tenant's JWKS. New tenants sign ID tokens with RS256, the algorithm every OpenID Connect application must accept. An ID token manager can use any active ES256 or RS256 key, and discovery lists the algorithms that enabled managers use. Profile claims appear only when their scope is granted, and each claim can go to the ID token, the UserInfo response, or both. A request with openid needs a response type that returns an ID token or a code, so token alone is refused.

The UserInfo endpoint, /oidc/userinfo by default, accepts an access token granted openid in the Authorization: Bearer header or a form body. Tokens in the query string are refused. Its sub is always the sub an ID token for the same sign-in carries, including after a refresh that returns no new ID token and for an access token returned by the authorization endpoint. Claims that belong only in a signed token, such as aud and exp, are left out. Each UserInfo read, and each refusal once the token is known, is recorded in the tenant's protocol Audit.

Tenant users confirm their email address when they register or from their Security page. With the email scope, the default ID token manager also sends email_verified, which is true only once the user has confirmed their current address. Every ID token issued for a signed-in user includes auth_time. The amr claim lists how the user signed in, for example pwd for a password, otp for a one-time or recovery code, hwk or swk for a passkey, email for an email sign-in link, and mfa when two different kinds of factor were proved. Sign-in methods in tokens explains every value. When the method is not known, amr is left out.

Authorization requests accept nonce, prompt (none, login, consent, or select_account), max_age, login_hint, which only fills in the email field, and id_token_hint. max_age and prompt=login are met by a sign-in during the request, however long the user then spends on the consent page, and max_age=0 always asks the user to sign in. select_account shows the account the browser is signed in to, with a choice to use another. An id_token_hint must be an ID token this tenant signed for the client; its expiry does not matter. If someone else is signed in, prompt=none returns login_required; without it the user is asked to sign in, and the application receives login_required if a different user does. With prompt=none, a login_hint email for another account returns account_selection_required. Request objects, the registration parameter, the claims parameter and WebFinger discovery are not supported. Subject identifiers are public: the same user has the same sub for every client unless a manager sets its own value.

Protocol availability

The token endpoint supports client credentials, authorization code redemption, and refresh when enabled by tenant and client policy. A refresh token is issued only when the granted scopes include offline_access and both Flow policy and the client allow the refresh token grant. Each access token manager sets a refresh token reuse grace from 0 to 60 seconds, 0 by default: within it, a client that lost a refresh response may present the same refresh token again and receive new tokens, recorded in Audit as a grace use; after it, or with 0, any reuse ends the whole sign-in. Each refresh returns a new refresh token, and the whole family ends at its access token manager's absolute lifetime, however often it is used. The authorization endpoint signs in tenant users, asks for consent according to the client setting, and returns a code, tokens, or both.

Implicit and hybrid response types are an ordinary tenant choice, off by default. They work only after a Tenant Admin allows the implicit grant and those response types in Flow policy and on a client. Their tokens are returned in the fragment or by form post, never in the query string. Current OAuth security guidance (RFC 9700) advises against them because the tokens pass through the browser, so Flow policy and the client editor show a warning while one is selected. An access token returned together with a code is revoked with the code's other tokens if the code is redeemed twice.

Both /.well-known/openid-configuration and /.well-known/oauth-authorization-server describe the selected tenant's issuer, common scopes, endpoint paths, and available public signing keys. Administrators can move endpoint paths within the tenant URL, but cannot change the issuer or well-known metadata URLs. Metadata Management can also publish informational fields, service_documentation, op_policy_uri, op_tos_uri, ui_locales_supported and claims_locales_supported, and the tenant's own fields whose names start with x_. Fields that describe protocol behavior come only from the service, so discovery never advertises something the tenant does not do.

Discovery documents and the JWKS may be cached by clients for up to five minutes. A newly generated key can take that long to reach every client, and a disabled key can keep verifying at clients that cached it for that long, so generate a key a few minutes before a manager starts signing with it.

Access tokens can be signed JWTs or opaque reference tokens. Every access token names <issuer>/resource as its audience unless its access token manager sets its own aud. Resource indicators (RFC 8707) are not supported, so a client cannot ask for a token meant for one particular API. Confidential clients can introspect and revoke their own tokens. Public clients can revoke their own tokens by sending their client_id, but cannot introspect. A confidential client made a resource server can also introspect access tokens issued to other clients in the tenant, which is how an API validates opaque tokens; refresh tokens stay private to the client that holds them. No client can revoke another client's token: such a request is refused with unauthorized_client, while an unknown or already invalid token still gets an empty success answer, so the response never confirms whether a value is a token. Introspection reports token_type Bearer for an access token and none for a refresh token. An endpoint URL in metadata is not a promise that every grant is available. Unimplemented protocol endpoints report their status rather than issuing credentials.

Browser and native applications

A browser application registered as a public client can redeem its code and revoke its tokens from its own page. The token and revocation endpoints let a browser read the answer to a public client's request when it comes from the origin of one of that client's redirect URIs, without cookies or other credentials. Responses to confidential clients, and introspection, are never readable from another site's page. The only other site allowed is this website itself, for the SCIM console in Docs and the request console on Lab pages, which send the credentials you type from your own browser.

A native application uses the system browser and a loopback redirect URI, such as http://127.0.0.1/callback. A loopback URI matches any port in the request, so the application can listen on whichever port is free (RFC 8252); the code must then be redeemed with the same port. Every other redirect URI must match exactly. HTTPS addresses an application has claimed work like any other HTTPS redirect URI. Private-use schemes such as com.example.app:/callback are not supported. A registered query string is kept exactly as registered, with the response added after it, so it cannot use the names the response adds, such as code or state.

Token endpoint answers

Refusals use the RFC 6749 error codes, each with a fixed error_description. Parameters a grant does not use, such as a scope sent with a code, are ignored. The client credentials grant cannot request openid, since there is no user, and is refused with invalid_scope. Two answers are not RFC 6749 refusals: a request over the tenant's rate limit receives temporarily_unavailable with HTTP 429 and Retry-After, and a problem on the server, such as a client without an enabled token manager, receives server_error with a reference_id that the tenant administrator can search for in Logs. When a grant has no scopes, the response leaves scope out.