Configuring OAuth 2.0 grants
This page shows how to set up iya-sts for each OAuth 2.0 grant type it
supports: the application to register, the settings to turn on, and the
request a client then sends. Each recipe is given twice, once as steps in the
admin console (/admin) and once as calls to the Management API
(/admin-api).
The values come from this repository’s own test jobs in
tests/protocol/, and each recipe names the job it is taken from. Those jobs
run against a service in both development and product mode, so the values are
known to work in both. Change the identifiers, URLs and secrets to your own.
What each grant is, and every setting in full, is on OAuth 2.0 and OpenID Connect. This page covers only what to fill in. The OpenID Connect flows (implicit, hybrid, logout, session management and so on) are on Configuring OpenID Connect flows.
- Configuring OAuth 2.0 grants
- Before you start
- Which grants are available
- Authorization code, with PKCE
- Client credentials
- Resource indicators (RFC 8707)
- Refresh token
- Password (development only)
- Device authorization (RFC 8628)
- JWT bearer (RFC 7523)
- SAML 2.0 bearer (RFC 7522)
- Token exchange (RFC 8693)
- CIBA
- Pre-authorized code (OpenID4VCI)
- Client authentication methods
- Client secrets
- Related
Before you start
A token for the Management API
Every /admin-api call below needs an access token with the admin:write
scope. Management API → Getting a token
shows how to get one. The examples here assume these variables and this helper
function:
BASE=https://localhost:8081 # add /realm/<id> to work in a trust realm
TOKEN=... # from management-api.md#getting-a-token
api() { # api <path under /admin-api> '<json body>'
curl -sk -X POST "$BASE/admin-api/$1" \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d "$2"
}
Four operations do almost all of the work
| What | Console | API |
|---|---|---|
| Register an application | Directory → Applications → New application › (/admin/applications/new), then Create the application |
POST /admin-api/applications/create with {identifier, name?, protocols, fields, lifetimeDays?} |
| Change one of its fields | the application’s page (/admin/applications?application=<id>), Configuration tab, the protocol’s sub-tab (for example OAuth 2.0 / OpenID Connect), then **Save |
POST /admin-api/applications/set with {application, attribute, value}, for a single-valued attribute (an empty value clears it) |
| Add or remove one value of a list | the same sub-tab: + adds a box, the bin deletes one, then **Save |
POST /admin-api/applications/add and /remove, with the same three members |
| Change a setting | Protocols → OAuth 2.0 / OIDC (/admin/oauth2), Global settings tab, then the group’s **Save |
POST /admin-api/config/set with {key, value}, /config/set-many with {"<key>": value, …}, /config/reset with {key} |
applications/set on a list attribute is refused (STS-REG-0008): use
add and remove for those.
Settings are per trust realm. A console page saves to the
realm it is shown in, and /realm/<id>/admin-api/config/... saves to that
realm. To give a new realm its settings from the start, use
POST /admin-api/realms/create with an overrides object. The OAuth 2.1 job
(sts_oauth21.js) does this:
api realms/create '{"id":"r1","domain":"r1.example.net","name":"r1",
"overrides":{"oauth2.oauth21":true,"oauth2.consentRequired":false}}'
The new-application form. Under What it is called you type the
Identifier and, if you like, a Name. Under Protocol families it is
declared for you tick the families. Under Its fields the form shows a
grid of attributes, by their attribute names, for the families ticked. The
simplified view shows the fields most clients need, among them
oauthRedirectUri, oauthTokenEndpointAuthMethod,
oauthGrantType, oauthResponseType, oauthAllowedScope, oauthAudience
and oauthClientSecret. Show every field (advanced view) shows the rest.
The registry writes oauthConfidential from the authentication method, so
the form does not offer that attribute.
A list holds one box per value, with + to add one. A list with a fixed set
of values, such as oauthGrantType, is a row of checkboxes; a long URN is
shown by its last two parts (grant-type:device_code), with the whole value
in its tooltip. A TRUE/FALSE attribute is a choice of true, false
or the default.
Three things are filled in for you:
- The identifier is the client_id unless you give
oauthClientIdyourself (#393). The simplified view does not ask for it again. The same goes for a SAMLsamlEntityIdand the other families’ identifiers. - The auth method follows the credential. If the create names no
oauthTokenEndpointAuthMethod, a client secret makes itclient_secret_basic, anoauthJwksoroauthJwksUrimakes itprivate_key_jwt, and no credential makes itnone, a public client. - The confidential flag follows the method.
none, or no method on an application created by hand, is recorded asoauthConfidentialFALSE. Any other method is TRUE. A create may send that same value. A value that disagrees is refused (STS-REG-0363). The method is what an operator edits, and the registry writes the flag. - The first secret’s lifetime is the Lifetime (days) box beside
Generate Secret, or
lifetimeDayson the API create. See Client secrets.
oauthScope is not a permission. It records the scopes a client has asked
for, so an add to it is refused (STS-REG-0361). The scopes a client may be
issued are oauthAllowedScope.
What development and product mode change
The same registration behaves differently in the two modes (global.mode):
- Development mode makes things up. An unknown
client_idand its redirect URI are accepted and recorded, a wrong client credential is logged rather than refused (outside RFC 9700, OAuth 2.1 and FAPI mode), and any scope is issued. Registering first is still the right habit, and every recipe here does it. - Product mode implies RFC 9700 mode. It refuses an
unregistered client, matches redirect URIs exactly, requires PKCE with
S256from a public client, refuses the implicit and password grants, and rotates refresh tokens. A client that declared a confidential method must authenticate with it. - Product mode holds a client to its protocol families. An application
declared for OAuth 2.0 alone is refused an ID Token (
STS-XACML-0084). Declare OpenID Connect as well for any client that asks foropenid. - Scopes in product mode come from
oauthAllowedScope. A scope that is not listed there is refused withinvalid_scope. If the list is empty, product mode issues only the standard set:openid profile email address phone offline_accessandbound_key(whileoauth2.keyBindingis on), plus the realm’s OpenID4VCI scopes. This service’s own protected scopes must be listed in both modes; see This service’s own scopes. oauthGrantTyperestricts the client, in both modes. The token endpoint refuses any grant the list does not name withunauthorized_client, whether the list came from a dynamic registration (RFC 7591grant_types) or an administrator. A client whose list omitsrefresh_tokenis issued no refresh token. An empty list restricts nothing in development mode; in product mode it allowsauthorization_codeandrefresh_tokenalone, unlessoauth2.allowUndeclaredGrantsis on, so aclient_credentialsor token exchange client must list its grant. The console offers one checkbox per grant this service implements, and a console or API write of any other value is refused. What a client has actually used is recorded separately, inoauthGrantTypeObserved, shown read-only besideoauthGrantTypeon the application’s OAuth 2.0 / OpenID Connect sub-tab.- Consent is on by default (
oauth2.consentRequired). A person approves each client on/oauth2/consentthe first time, and a public client every time in product mode (oauth2.consentAlwaysForPublicClients). Test realms often turn it off with"oauth2.consentRequired": false. In production, leave it on.
Which grants are available
Grant (grant_type) |
Available | Recipe |
|---|---|---|
authorization_code |
always; PKCE is required of public clients in RFC 9700 and OAuth 2.1 mode, and of every client in product mode | below |
client_credentials |
always; refused for a public client in product mode | below |
refresh_token |
always; in product mode a chain of refreshes ends 30 days after its first token (oauth2.refreshTokenMaxChainS) |
below |
password |
development mode only, and not while oauth2.rfc9700 is on |
below |
urn:ietf:params:oauth:grant-type:device_code |
while oauth2.deviceAuthorization is on (off by default) |
below |
urn:ietf:params:oauth:grant-type:jwt-bearer |
while oauth2.jwtBearerGrant is on (on by default) |
below |
urn:ietf:params:oauth:grant-type:saml2-bearer |
while oauth2.saml2BearerGrant is on (on by default) |
below |
urn:ietf:params:oauth:grant-type:token-exchange |
always | below |
urn:openid:params:grant-type:ciba |
while oauth2.ciba is on (off by default) |
below |
urn:ietf:params:oauth:grant-type:pre-authorized_code |
always | below |
implicit (response_type=token) |
not in RFC 9700 mode, and so not in product mode | Configuring OpenID Connect flows |
The live list for a realm is grant_types_supported in
/.well-known/openid-configuration. A grant that is not listed there is
refused with unsupported_grant_type.
Authorization code, with PKCE
A person signs in through a browser and the client exchanges the code it
receives for tokens. The code is valid for oauth2.authorizationCodeTtlS
(300 s by default, and never longer). It is presented once: its first token
request spends it, whatever that request’s outcome, and a second presentation
is refused and revokes what the first one bought. oauth2.codeReplayIdempotent
relaxes that rule. It is off by default; leave it off.
A public client (a browser or native app)
Taken from oauth2_sts_endpoints.js.
Console:
- Directory → Applications → New application ›.
- Under What it is called, set Identifier to
sts-endpoint-test-client-native(the name is optional). It is also the client_id. - Under Protocol families it is declared for, tick OAuth 2.0 and OpenID Connect.
- Under Its fields, in the OAuth 2.0 / OpenID Connect group:
oauthRedirectUri:com.example.oauth2stsendpoints:/callback.oauthTokenEndpointAuthMethod: ticknone, and nothing else. The registry recordsoauthConfidentialFALSE because the method isnone.oauthGrantType: tickauthorization_codeandrefresh_token.oauthResponseType: tickcode.oauthAllowedScope:openid,profileandemail, one box each (+ adds a box).
- Click Create the application.
API:
api applications/create '{
"identifier": "sts-endpoint-test-client-native",
"name": "sts-endpoint-test-client-native",
"protocols": ["oauth2", "oidc"],
"fields": {
"oauthRedirectUri": ["com.example.oauth2stsendpoints:/callback"],
"oauthResponseType": ["code"],
"oauthGrantType": ["authorization_code", "refresh_token"],
"oauthAllowedScope": ["openid", "profile", "email"],
"oauthTokenEndpointAuthMethod": "none"
}}'
The registry writes oauthConfidential FALSE from none. Sending
"oauthConfidential": "FALSE" states the same value. A different value is
refused (STS-REG-0363).
A confidential client (a web server)
Taken from sts_token_revocation.js.
Console: create the application as for the public client above, with
Identifier rv-a and oauthRedirectUri https://rp.revoke.example.test/cb.
Beside oauthClientSecret, click Generate Secret, and copy the value
before you create the application. Leave Lifetime (days) empty for the
realm’s default. Then:
oauthTokenEndpointAuthMethod: tickclient_secret_basic, and nothing else.oauthAllowedScope:openid.
An application that already exists gets a secret on its Credentials tab, under Client secrets. See Client secrets.
API:
SECRET=$(openssl rand -base64 32)
api applications/create '{
"identifier": "rv-a", "name": "rv-a", "kind": "oauth2-client",
"protocols": ["oauth2", "oidc"],
"fields": {
"oauthClientId": ["rv-a"],
"oauthRedirectUri": ["https://rp.revoke.example.test/cb"],
"oauthGrantType": ["authorization_code", "refresh_token"],
"oauthAllowedScope": ["openid"],
"oauthTokenEndpointAuthMethod": "client_secret_basic",
"oauthClientSecret": "'"$SECRET"'"
}}'
POST /admin-api/applications/generate-secret with {} returns a random
secret and stores nothing, if you would rather have the service choose one.
Pass it in fields.oauthClientSecret.
The requests
GET /oauth2/authorize?response_type=code&client_id=rv-a
&redirect_uri=https://rp.revoke.example.test/cb&scope=openid&state=<random>
&code_challenge=<BASE64URL(SHA256(verifier))>&code_challenge_method=S256
POST /oauth2/token
Authorization: Basic base64(rv-a:<secret>) # a public client sends client_id=… instead
grant_type=authorization_code&code=<code>
&redirect_uri=https://rp.revoke.example.test/cb&code_verifier=<verifier>
redirect_uri on the token request must be exactly the one on the
authorization request. OAuth 2.1 mode (oauth2.oauth21)
lets a public client that used PKCE leave it out. RFC 9700 mode alone does
not.
Settings (console: Protocols → OAuth 2.0 / OIDC, Global settings tab):
| Setting | Default | Why you would change it |
|---|---|---|
oauth2.rfc9700 |
false |
Turns on RFC 9700 mode in development. Product mode implies it. |
oauth2.oauth21 |
false |
Turns on OAuth 2.1 mode, which implies RFC 9700 mode. |
oauth2.consentRequired |
true |
Asks the person to approve each client. |
oauth2.authorizationCodeTtlS |
300 |
Sets how long a code is valid: 30 to 300 seconds. |
Client credentials
A service gets a token for itself. No person is involved, and no refresh
token or ID Token is issued. The token’s sub is the client_id; in RFC 9700
mode, and so in product, it is urn:sts:client:<client_id>.
Taken from sts_scope_policy.js, which suffixes each identifier with its
realm’s name.
Console:
- Create the application: Identifier
sp-listed, tick OAuth 2.0, and click Generate Secret besideoauthClientSecret. No redirect URI is needed. - In the same grid:
oauthTokenEndpointAuthMethod: tickclient_secret_post, and nothing else.oauthGrantType: tickclient_credentials.oauthAllowedScope: each scope it may be issued, heresp:custom.
API:
api applications/create '{
"identifier": "sp-listed", "name": "sp-listed", "kind": "oauth2-client",
"protocols": ["oauth2"],
"fields": {
"oauthClientId": ["sp-listed"],
"oauthClientSecret": "'"$SECRET"'",
"oauthGrantType": ["client_credentials"],
"oauthTokenEndpointAuthMethod": "client_secret_post",
"oauthAllowedScope": ["sp:custom"]
}}'
Request:
POST /oauth2/token
grant_type=client_credentials&client_id=sp-listed&client_secret=<secret>&scope=sp:custom
[&resource=https://api.example.com]
In product mode, a scope not listed in oauthAllowedScope is refused with
invalid_scope, and a public client (auth method none) is refused this
grant with unauthorized_client.
The audience. A request that names a resource, authorization_details,
a scope naming another application or a delegated permission, or a scope of
this service’s own resource server (openid and the other OpenID Connect
scopes, the SCIM, Shared Signals, management API and grant management scopes)
gets the audience those name. A request that names none of these gets a token
addressed to the client itself: its oauthAudience values, or its client_id
when it declares none (#550). That is the token to send as an RFC 8693
actor_token.
Permissions on another application come from a role (#551). A delegated
grant (oauthDelegatedPermission) authorizes a permission only on a person’s
behalf, so it does not count here. To let the client use a permission itself,
make it a member of a role whose rolePermission names the permission — an
app role of the resource (<role>@<resource>) or a realm role. Without one the
permission is left off the token, and a request asking for nothing else is
refused with invalid_scope. See
Permissions on another application. The seeded client sts-api-client is a
working example of this grant.
This service’s own scopes
Some scopes are for this service’s own APIs. They are issued only to a client
whose oauthAllowedScope lists them, in both modes, and each API asks
again on every call, so removing a value cuts off a token already issued.
They are:
- the Management API’s
admin:read,admin:writeandadmin:console, and the owner scopesowner:readandowner:write; - SCIM’s two,
scim.scopeReadandscim.scopeWrite(scim:readandscim:writeby default); - Shared Signals’
ssf.readandssf.manage, and the names inssf.authScopeReadandssf.authScopeWrite(by default the same two); account:manage,device:compliance,grant_management_query,grant_management_revoke,vc-api:issueandvc-api:verify.
For Shared Signals, write includes read (#334). A client that declares
ssf.manage may also be issued ssf.read, and a token carrying
ssf.manage may read. ssf:write is not a Shared Signals scope any more.
The job sts_scope_policy.js does this with a client declared for
Shared Signals:
api applications/create '{"identifier":"sp-ssf","name":"sp-ssf","kind":"oauth2-client",
"protocols":["oauth2","ssf"],
"fields":{"oauthClientId":["sp-ssf"],"oauthClientSecret":"'"$SECRET"'",
"oauthGrantType":["client_credentials"],
"oauthTokenEndpointAuthMethod":"client_secret_post"}}'
api applications/add '{"application":"sp-ssf","attribute":"oauthAllowedScope","value":"ssf.read"}'
api applications/add '{"application":"sp-ssf","attribute":"oauthAllowedScope","value":"ssf.manage"}'
POST /oauth2/token
grant_type=client_credentials&client_id=sp-ssf&client_secret=<secret>
&scope=ssf.read ssf.manage
The job then removes ssf.read: the same token still reads, because
ssf.manage includes it. Removing ssf.manage too makes the Shared Signals
endpoints answer 403 to that token.
Shared Signals says which operation needs which scope.
Resource indicators (RFC 8707)
A request may name the API its token is for with resource, on every grant.
OAuth 2.0 and OpenID Connect explains how the audience is
chosen. Three rules matter when you configure a client:
- A resource must be a registered target, in every mode (#1140): one of
this service’s own resource servers, or an application registered in the
realm, named by its
oauthAudience, permission base URI,client_idor identifier. Anything else isinvalid_target. To test a client against an API of your own, register an application holding its audience first (kind OAuth 2.0 resource server, withoauthAudience). - An authorization code may name several resources (#607). The code request is refused only when no one of them could be issued a token alone. Each token request then names the one resource its access token is for, and a token request naming none or several of them is refused. Implicit and hybrid responses carry a token from the authorization endpoint, so they keep the stricter rule.
- A client_credentials request may name two resources and no scope. Its
token is then addressed to both. Two resources with a scope tied to neither
is
invalid_target.tests/rfc9068_access_tokens.jschecks both.
Refresh token
A refresh token is issued with the authorization code grant (and with the
device, CIBA and token exchange grants). Request offline_access if it should
outlive the sign-on session. Without that scope the refresh token is
online, and it stops working when the session ends.
Request (from sts_token_revocation.js):
POST /oauth2/token
Authorization: Basic base64(rv-a:<secret>)
grant_type=refresh_token&refresh_token=<token>[&scope=openid]
A scope on the request narrows the new access token. The refresh token that
comes back still carries the whole grant.
Settings. The lifetimes are on Protocols → OAuth 2.0 / OIDC, the
Token lifetimes tab (button Save lifetimes; API:
POST /admin-api/token-lifetimes/set). The other settings are on the
Global settings tab.
| Setting | Default | What it does |
|---|---|---|
oauth2.refreshTokenTtlS |
86400 |
The refresh token’s absolute lifetime. |
oauth2.refreshTokenMaxChainS |
0 (2592000 in product) |
The absolute limit on a chain of refreshes, counted from its first refresh token. Past it the person signs in again. 0 is no limit. |
oauth2.refreshIdleSeconds |
86400 |
How long an unused refresh token stays valid, in RFC 9700 mode only. |
oauth2.revokeRefreshOnLogout |
true |
Signing out ends the person’s refresh tokens. |
oauth2.refreshTokenRotation |
false |
Issues a new refresh token on each use. Rotation is already on in RFC 9700, OAuth 2.1, FAPI and product mode. A replayed refresh token revokes the whole family. |
oauth2.refreshTokenRequireDpop / …RequireMtls |
false |
Requires the refresh token to be sender-constrained. |
oauth2.refreshRequiresConsent |
true |
Requires a consent record for the refresh. |
Per-client overrides. Each application can override the lifetimes, and
oauthMaxAuthAgeS overrides oauth2.maxAuthAgeS (how old an authentication
may be before the authorization endpoint asks again, even when the request
sends no max_age). That setting is not on the Token lifetimes tab. In
the console they are fields of their own names: on the new-application form,
and on the application’s Configuration tab, OAuth 2.0 / OpenID Connect
sub-tab, under Show every field (advanced view). Empty a field to take the
realm’s value again. That does not apply to oauthMaxAuthAgeS,
oauthRefreshTokenTtlS or oauthRefreshIdleSeconds on the admin console, the
user portal or the reports application: those three keep their own bound, the
shorter of it and the realm, and a clear or a 0 is refused. A different number
is written when the save confirms it. Through the API:
api applications/set '{"application":"rv-a","attribute":"oauthRefreshTokenTtlS","value":"3600"}'
The override attributes are oauthAccessTokenTtlS, oauthIdTokenTtlS,
oauthRefreshTokenTtlS, oauthRefreshIdleSeconds, oauthMaxAuthAgeS and
oauthRevokeRefreshOnLogout (TRUE or FALSE).
Password (development only)
The resource owner password credentials grant exists here so that a client’s
handling of it can be tested. It is refused in product mode and whenever
oauth2.rfc9700 is on, so do not build anything on it.
Taken from oauth2_sts_endpoints.js. First add password to the client’s
oauthGrantType. The person must already exist in the directory:
api users/create '{"username":"alice","invent":false,"credential":"password",
"password":"<password>","attributes":{"cn":"alice","givenName":"alice",
"sn":"alice","mail":"alice@suite.example.test"}}'
A realm’s attribute policy may require more of a person; product mode
requires givenName, sn and mail by default.
Request:
POST /oauth2/token
grant_type=password&username=alice&password=<password>&scope=openid
&client_id=<id>&client_secret=<secret>
In development mode any password is accepted except the reserved value
invalid, which is refused with invalid_grant.
Device authorization (RFC 8628)
A device with no browser shows the person a code, and the person approves it on another device.
Settings (Protocols → OAuth 2.0 / OIDC, Global settings tab; the values are from sts_device_key_binding.js):
api config/set '{"key":"oauth2.deviceAuthorization","value":true}'
api config/set '{"key":"oauth2.deviceCodeIntervalS","value":1}' # default 5
oauth2.deviceCodeLifetimeS (default 600) sets how long a code is valid. While
oauth2.deviceAuthorization is off, /oauth2/device_authorization answers
404.
Client. The test registers its client dynamically (with
oauth2.openRegistration set to true), so the grant is part of the
client’s registration:
POST /oauth2/register
{"redirect_uris":["https://rp.keybinding.example/cb"],
"token_endpoint_auth_method":"client_secret_post",
"grant_types":["authorization_code","refresh_token",
"urn:ietf:params:oauth:grant-type:device_code"],
"response_types":["code"],"scope":"openid offline_access"}
A dynamically registered client whose grant_types does not include
device_code is refused with unauthorized_client. For a client you register
in the console or through /admin-api, add
urn:ietf:params:oauth:grant-type:device_code to oauthGrantType. The job
sts_admin_client_policies.js covers that path: a public client created
through /admin-api with the grant is issued tokens once the person approves
on /portal/device, and a client whose oauthGrantType leaves the grant out
is refused at /oauth2/device_authorization with unauthorized_client
(STS-OAUTH-0692).
Requests:
POST /oauth2/device_authorization
client_id=<id>&client_secret=<secret>&scope=openid offline_access
→ device_code, user_code (XXXX-XXXX), verification_uri=<BASE>/portal/device,
verification_uri_complete, expires_in, interval
(the person signs in at /portal/device, enters the code, and approves)
POST /oauth2/token
grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=<code>&client_id=<id>&client_secret=<secret>
Poll no faster than interval. Until the person approves, the token request
answers authorization_pending, and polling too fast gets slow_down, which
adds 5 seconds to the interval. After that the answer is the tokens, or
access_denied or expired_token.
JWT bearer (RFC 7523)
A JWT signed by an issuer the service trusts is exchanged for an access
token. Step-by-step instructions are in
JWT assertions → the shortest path. The values below
are from sts_jwt_bearer_grant.js.
- The realm needs a certificate authority. In the console that is
Protocols → PKI (
/admin/pki). Through the API:api pki/build '{"organisation":"Assertion Test","country":"US"}' - Create the application that holds the issuer’s key:
api applications/create '{"identifier":"assert-issuer-1","name":"assert-issuer-1", "protocols":["oauth2","oidc"], "fields":{"oauthClientId":"assert-issuer-1","oauthClientSecret":"'"$SECRET"'", "oauthTokenEndpointAuthMethod":"client_secret_post"}}' - Give it a key. In the console, on the application’s Credentials tab,
under Assertion key pairs → RFC 7523 — a JWT assertion, click Issue a
key pair from this realm’s CA (fields Key algorithm and Days), or
use Upload the certificate for a key you already hold. Through the API:
api pki/issue '{"identifier":"assert-issuer-1"}'The reply contains the
kid(app-…) and the JWS algorithm (RS256). The private key is never in aGET. Collect it once withreveal-secret, which writes an audit row:api applications/reveal-secret '{"application":"assert-issuer-1", "secret":"oauthAssertionPrivateKey"}' - Declare the issuer. This is the trust decision. An assertion from an
undeclared issuer is refused with
invalid_grantin every mode:api applications/add '{"application":"assert-issuer-1", "attribute":"oauthAssertionIssuer","value":"https://issuer.example.test/jwtbearer"}'
Request. It carries no client authentication:
POST /oauth2/token
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<JWS>&scope=openid profile
JWS header {"alg":"RS256","typ":"JWT","kid":"<kid>"}
JWS claims {"iss":"https://issuer.example.test/jwtbearer","sub":"alice",
"aud":"<BASE>/oauth2/token","iat":…,"exp":iat+120,"jti":"<random>"}
Settings (Protocols → OAuth 2.0 / OIDC, Global settings tab):
| Setting | Default | What it does |
|---|---|---|
oauth2.jwtBearerGrant |
true |
Enables the grant. |
oauth2.jwtBearerRequireRegisteredIssuer |
true |
Refuses an issuer nobody declared. |
oauth2.jwtBearerMaxLifetimeS |
300 |
The longest exp − iat accepted. |
oauth2.clientAssertionSkewS |
60 |
Clock skew allowed on assertion times. |
A person can also be an issuer, but only about themselves:
POST /admin-api/pki/issue {"identifier":"alice","target":"person"}, then
iss = sub = alice. Each assertion is accepted once, ever.
SAML 2.0 bearer (RFC 7522)
A signed SAML 2.0 assertion is exchanged for an access token.
Step-by-step instructions are in
SAML assertions → the shortest path. The values below
are from sts_saml2_bearer_grant.js.
- Create the application exactly as in JWT bearer,
step 2 (identifier
saml-assert-issuer-1). - Give it a SAML signing key. In the console that is the Credentials tab,
Assertion key pairs → RFC 7522 — a SAML 2.0 assertion → Issue a key pair
from this realm’s CA. Its private key is collected with
reveal-secretnamingoauthSamlAssertionPrivateKey. Through the API:api pki/issue '{"identifier":"saml-assert-issuer-1","purpose":"saml"}'To trust an identity provider’s existing certificate instead, set
oauthSamlAssertionSigningCertificateto it. - Declare the
<Issuer>, on the SAML attribute.oauthAssertionIssueris the JWT declaration and does not count here:api applications/add '{"application":"saml-assert-issuer-1", "attribute":"oauthSamlAssertionIssuer","value":"https://issuer.example.test/saml2bearer"}'
Request. It carries no client authentication:
POST /oauth2/token
grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer
&assertion=<base64url of the signed XML>&scope=openid profile
The assertion must have:
Issuerequal to the declared value, andNameIDequal to the username;- a bearer
SubjectConfirmationwhoseRecipientis the token endpoint, withNotOnOrAfterabout 120 s ahead; Audienceequal to the token endpoint;- an enveloped RSA-SHA256 signature.
The settings are oauth2.saml2BearerGrant, …RequireRegisteredIssuer and
…MaxLifetimeS, with the same defaults as the JWT settings.
Token exchange (RFC 8693)
A client exchanges a token it holds for a token for another audience. The
exchange is a delegation (the result carries a nested act claim naming
the actor) or an impersonation (it does not), as the issuance policy
chooses — the request may ask with exchange_semantics. Who may do either is
decided by the same controls as WS-Trust and Kerberos: see
Delegation and impersonation for the model.
Taken from sts_delegation_policy.js.
The applications. The job makes every application a confidential client
declared for OAuth 2.0, OpenID Connect and WS-Trust, with its own URL as its
audience. dp-back is the target, dp-mid an intermediary that may delegate
to it, and dp-mid2 one that may also impersonate:
for app in dp-back dp-mid dp-mid2; do
api applications/create '{"identifier":"'$app'","name":"'$app'",
"protocols":["oauth2","oidc","wstrust"],
"fields":{"oauthClientId":["'$app'"],"oauthClientSecret":"'"$SECRET"'",
"oauthTokenEndpointAuthMethod":"client_secret_post",
"oauthGrantType":["client_credentials",
"urn:ietf:params:oauth:grant-type:token-exchange"],
"oauthAllowedScope":["api","openid"],
"oauthAudience":["https://'$app'.example"],
"wstrustAppliesTo":["https://'$app'.example"]}}'
done
The policy:
# a token issued for dp-mid may be handed on to dp-back …
api applications/add '{"application":"dp-mid","attribute":"appAllowedToDelegateTo","value":"dp-back"}'
# … and dp-mid2 may delegate or impersonate, as the request asks
api applications/add '{"application":"dp-mid2","attribute":"appDelegationSemantics","value":"delegation"}'
api applications/add '{"application":"dp-mid2","attribute":"appDelegationSemantics","value":"impersonation"}'
In the console these are on the application’s Configuration tab, the Every protocol sub-tab, under Delegation / Impersonation. A list there opens a search of other applications (or of the realm’s groups) when you work in it, five results a page, each with an Add. Then click Save Every protocol.
More controls can take part:
appAllowedToActOnBehalfOf, on the target, lists the applications (and people) that may act toward it. The job sets it ondp-backfordp-mid2and a person.appDelegationSubjectGroup, on the actor, holds group DNs that limit whose tokens it may exchange.appDefaultDelegationSemantics,appNotDelegatedandappMayActon an application.- The person’s own settings:
POST /admin-api/users/set-not-delegated {"user","value":true},POST /admin-api/users/set-may-act {"user","delegate":"<DN of a person or application>"}andPOST /admin-api/users/set-delegation-semantics {"user","semantics":["delegation"],"default":"delegation"}.
To read the whole policy back, use GET /admin-api/delegation/policy. In the
console, the delegated permissions are on Protocols → Delegation
(/admin/delegation-settings), and each act, with what development would
have refused, is on Monitoring → Delegation (/admin/delegation).
Request:
POST /oauth2/token
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_id=dp-mid&client_secret=<secret>
&subject_token=<token>&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&audience=https://dp-back.example&scope=api
[&exchange_semantics=delegation|impersonation]
[&actor_token=<a token about the actor>
&actor_token_type=urn:ietf:params:oauth:token-type:access_token]
The actor_token must be the client’s own, in both modes (#550). It must
have been issued to the exchanging client: its client_id (or azp) is that
client, and a token carrying neither names the client in aud. Its aud must
also name this authorization server (its issuer or token endpoint) or the
exchanging client (its client_id, identifier or oauthAudience). A client’s
own client_credentials token that asked for nothing else meets both. Anything
else is refused with invalid_request: another client’s token, or a token
minted for some other resource, which that resource could replay as its own
actor.
Modes. Product mode enforces the policy, refusing with invalid_request
or invalid_target. It also verifies both tokens and refuses a scope wider
than the subject token’s. Development mode issues the token anyway and records
on Monitoring → Delegation that it would have been refused. may_act is
enforced in both modes. Whether an exchange also returns a refresh token is set by
oauth2.tokenExchangeRefreshToken (never, when-requested (the default) or
always). The per-client override is oauthTokenExchangeRefreshToken.
An assertion as the subject or actor token
A signed assertion from a declared issuer may be the subject_token or the
actor_token (#114). Taken from sts_token_exchange_assertions.js:
| Assertion | subject_token_type |
The issuer’s application needs |
|---|---|---|
| RFC 7523 JWT | urn:ietf:params:oauth:token-type:jwt |
oauthAssertionIssuer, and a key: pki/issue, or the issuer’s own keys in oauthAssertionJwks |
| RFC 7522 SAML 2.0 | urn:ietf:params:oauth:token-type:saml2 |
oauthSamlAssertionIssuer, and pki/issue with "purpose":"saml" |
| SAML 1.1 | urn:ietf:params:oauth:token-type:saml1 |
the same as SAML 2.0 |
api applications/add '{"application":"txa-jwt-idp","attribute":"oauthAssertionIssuer",
"value":"https://txa-jwt-idp.example"}'
api applications/set '{"application":"txa-jwt-idp","attribute":"oauthAssertionJwks",
"value":"{\"keys\":[<the issuer'"'"'s public JWK>]}"}'
POST /oauth2/token
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_id=txa-client&client_secret=<secret>
&subject_token=<the JWS>&subject_token_type=urn:ietf:params:oauth:token-type:jwt
The assertion is checked as the assertion grant checks it, and spent in the
same one-use history: one used at the grant cannot then be exchanged, nor the
reverse. By default its audience must name this token endpoint or issuer.
oauth2.tokenExchangeAudience set to any-declared-relying-party also
accepts an audience naming an application registered in the realm. That is
token forwarding; read the setting’s warning before turning it on.
A Kerberos ticket as the subject, the actor or the token issued
A Kerberos ticket may be the subject_token or the actor_token, and may be
asked for as requested_token_type (#658). The token types are the
Kerberos Token Profile 1.1’s
six URIs, the ones WS-Trust uses, usually
http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ.
The token is the AP-REQ (or its GSS wrapping), base64url. Taken from
sts_kerberos_tokens.js.
As the subject or the actor, the ticket is for this authorization
server’s own SPN (krb5.servicePrincipal), checked by the Kerberos acceptor
in both modes and good once. oauth2.tokenExchangeKerberosInput (on by
default) turns it off.
- A delegated subject. The exchanging client obtained the ticket by
Kerberos delegation, so it must be a Kerberos service as well as an OAuth
client: an application whose identifier is its
SPN@REALMand which carries the client’soauthClientId. The ticket is either an S4U2Proxy ticket whose PAC’sS4U_DELEGATION_INFOnames the client last, or one bought with a TGT forwarded to a client withkrb5TrustedForDelegation. The services before the client become the issued token’s nestedact, under the client. A ticket that is neither is refused (invalid_request), unless its client is the exchanging client’s own service principal, which is a self exchange. - The actor. The ticket’s client is the exchanging client’s own service principal.
# the front end is a Kerberos service AND the OAuth client that exchanges
api applications/add '{"application":"HTTP/front.example.com@EXAMPLE.COM",
"attribute":"oauthClientId","value":"front"}'
api applications/add '{"application":"HTTP/front.example.com@EXAMPLE.COM",
"attribute":"appAllowedToDelegateTo","value":"HTTP/sts.example.com@EXAMPLE.COM"}'
POST /oauth2/token
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_id=front&client_secret=<secret>
&subject_token=<the S4U2Proxy AP-REQ, base64url>
&subject_token_type=http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1%23GSS_Kerberosv5_AP_REQ
&audience=https://back.example
As the token issued, with oauth2.tokenExchangeKerberosOutput on (it is
off by default):
- the one
audienceorresourcemust be an application that is a Kerberos service; - the answer carries the AP-REQ in
access_token, base64url, withissued_token_typethe URI asked for andtoken_typeN_A(RFC 8693 section 2.2.1).session_keyandsession_key_etypehold the Authenticator’s subkey, which the holder needs to use the token, so the request must arrive over TLS; expires_inis the AP-REQ’s own window (krb5.clockSkew);- there is no refresh token and no ID Token;
- a delegation’s
actchain becomes the ticket’sS4U_DELEGATION_INFO; - a target in another Kerberos realm is reached through the trusts, as in WS-Trust.
Native SSO is a form of token exchange with an ID Token and a device secret.
CIBA
With Client-Initiated Backchannel Authentication, a client asks for a named
person to be authenticated. The person approves on /portal/ciba, and the
client collects the tokens by polling or is notified. Taken from
sts_ciba.js.
Setting (Protocols → OAuth 2.0 / OIDC, Global settings tab):
api config/set '{"key":"oauth2.ciba","value":true}'
The other CIBA settings are oauth2.cibaDefaultExpiryS (120),
oauth2.cibaMaxExpiryS (600), oauth2.cibaIntervalS (5) and
oauth2.cibaMaxPendingPerPerson (5).
Client:
api applications/create '{"identifier":"ciba-poll","name":"ciba-poll",
"protocols":["oauth2","oidc"],
"fields":{"oauthClientId":"ciba-poll","oauthClientSecret":"'"$SECRET"'",
"oauthTokenEndpointAuthMethod":"client_secret_post",
"oauthGrantType":["urn:openid:params:grant-type:ciba"],
"oauthAllowedScope":["openid"],
"oauthBackchannelTokenDeliveryMode":"poll"}}'
A client with no delivery mode is refused with unauthorized_client. For the
other two delivery modes:
- ping or push: also set
oauthBackchannelClientNotificationEndpoint, for example tohttps://client.example.com/ping. - To make the client send a
user_code, setoauthBackchannelUserCodeParametertoTRUE.
Requests:
POST /oauth2/bc-authorize
client_id=ciba-poll&client_secret=<secret>&scope=openid&login_hint=alice
[&binding_message=…][&client_notification_token=…]
→ auth_req_id, expires_in, interval
(alice approves on /portal/ciba)
POST /oauth2/token
grant_type=urn:openid:params:grant-type:ciba&auth_req_id=<id>
&client_id=ciba-poll&client_secret=<secret>
Pre-authorized code (OpenID4VCI)
A credential offer carries a pre-authorized code, and a wallet exchanges it for an access token to the credential endpoint:
POST /oauth2/token
grant_type=urn:ietf:params:oauth:grant-type:pre-authorized_code
&pre-authorized_code=<code>&tx_code=<PIN>
No application needs registering, because the offer is the grant. The
settings are oid4vci.txCodeLength (default 5) and oid4vci.txCodeMaxAttempts
(default 5). See OpenID4VCI.
Client authentication methods
oauthTokenEndpointAuthMethod names the methods: a checkbox per method on the
application’s OAuth 2.0 / OpenID Connect sub-tab, and a list in the API (applications/add and
applications/remove, or an array in create). A client may hold several
— a secret and a key pair, say — and the token endpoint accepts whichever one
a request presents: a client_assertion is private_key_jwt or
client_secret_jwt (by its alg where both are held), an Authorization:
Basic header is client_secret_basic, a client_secret in the body is
client_secret_post, the attestation headers are the attestation methods and
a client certificate is tls_client_auth or self_signed_tls_client_auth.
none cannot be held with any other method, because it is what makes a
client public; a save that ticks it beside another is refused
(STS-REG-0207). Registration (RFC 7591) reports the first method held, since
its token_endpoint_auth_method is a single value. Each method needs something
more on the application:
| Method | What the application needs | How the client presents it | Job |
|---|---|---|---|
none |
nothing more (a public client) | client_id only; PKCE S256 in product mode |
oauth_fixtures.js |
client_secret_basic |
oauthClientSecret |
Authorization: Basic |
sts_token_revocation.js |
client_secret_post |
oauthClientSecret |
client_id and client_secret in the body |
sts_scope_policy.js |
client_secret_jwt |
oauthClientSecret; optionally oauthTokenEndpointAuthSigningAlg (HS256/HS384/HS512) |
a client assertion with an HMAC signature, addressed to the issuer or the token endpoint. An HS512 key must be at least 512 bits (RFC 7518 section 3.2). |
sts_client_authentication.js |
private_key_jwt |
a key: pki/issue as in JWT bearer, or oauthJwks or oauthJwksUri |
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer, with iss = sub = the client_id and aud = the token endpoint |
sts_jwt_bearer_grant.js |
saml2_bearer |
pki/issue with "purpose":"saml" |
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:saml2-bearer, with Issuer = Subject = the client_id |
sts_saml2_bearer_grant.js |
tls_client_auth |
a certificate issued on its Credentials tab (Mutual TLS (RFC 8705) → Issue a TLS client certificate from this realm’s CA; API: applications/issue-tls-client-certificate), or exactly one of oauthTlsClientAuthSubjectDn, …SanDns, …SanUri, …SanIp, …SanEmail |
the certificate in the TLS handshake; the token is bound to it (cnf.x5t#S256) |
sts_client_authentication.js (a certificate from this realm’s CA), tests/rfc8705_mtls.js (the subject parameters) |
self_signed_tls_client_auth |
oauthJwks with x5c, or oauthTlsClientCertificateThumbprint |
the certificate in the TLS handshake | sts_client_authentication.js (x5c), tests/rfc8705_mtls.js (thumbprint) |
attest_jwt_client_auth |
the realm setting oauth2.clientAttestationTrustAnchors or …TrustedKeys |
the OAuth-Client-Attestation and …-PoP headers |
sts_client_attestation.js |
What development mode checks. Outside RFC 9700 mode, development mode
observes a client_secret_jwt assertion without verifying its HMAC or its
jti, so a wrong secret or a replay is still issued a token there; product
mode refuses both. A registered oauthTokenEndpointAuthSigningAlg and both
RFC 8705 methods are checked in every mode. sts_client_authentication.js
asserts each of these in a development and a product realm.
OAuth 2.0 and OpenID Connect → Client authentication describes every method in full.
Client secrets
An application may hold several client secrets at once, each with its own
expiry, up to oauth2.clientSecretsMax (5). The token endpoint accepts any
one of them; product mode refuses one that has expired. The newest is the primary: it is the one this
service signs HS256 ID Tokens and JARM responses with.
The first secret’s lifetime is set on the create (#394). On the
new-application form, type it in Lifetime (days) beside Generate
Secret. Through the API, give lifetimeDays beside fields:
api applications/create '{"identifier":"generate-secret-app","protocols":["oauth2"],
"fields":{"oauthClientSecret":"'"$SECRET"'"},"lifetimeDays":30}'
The value is whole days, 0 to 730, and 0 never expires. Left out or empty, it
is oauth2.clientSecretLifetimeDays, which is 0 by default. A lifetime given
with no secret is refused. tests/application_generate_secret.js creates
with 30 and with 0.
An application that exists has its secrets on its Credentials tab, under Client secrets: a table of the secrets held, each with its expiry and a Remove button, and these forms:
| Console | API (POST /admin-api/applications/…) |
What it does |
|---|---|---|
| Lifetime (days), Description, Add a client secret | add-secret {application, lifetimeDays?, description?} |
Mints a secret and adds it. The others keep working until their own expiry. |
| Rotate the client secret | rotate-secret {application} |
Adds a new secret and moves every live one to expire after oauth2.clientSecretOverlapS (604800, seven days). |
| Regenerate: replace every secret (Generate a client secret when it holds none) | regenerate-secret {application} |
Makes a new secret the only one. Every other secret stops working at once. |
| Remove on a row | remove-secret {application, secret} |
Removes one secret by its id, at once. |
api applications/add-secret '{"application":"rv-a","lifetimeDays":30}'
The answer to each of the first three carries the new secret in
clientSecret. It is the one time the value is handed out. Afterwards a
GET shows each secret’s id and expiry, never its value; reveal-secret
with the secret’s id hands it back and writes an audit row.
tests/client_secret_rotation.js covers rotation, the cap and the lifetimes.
| Setting | Default | What it does |
|---|---|---|
oauth2.clientSecretLifetimeDays |
0 |
The lifetime of a secret when none is given. 0 never expires. |
oauth2.clientSecretOverlapS |
604800 |
How long a rotation leaves the old secrets working. 0 makes a rotation a regeneration. |
oauth2.clientSecretsMax |
5 |
How many secrets one application may hold (STS-REG-0208 past it). |
oauth2.clientSecretExpiryWarningDays |
14 |
How far ahead the daily job oauth2.client-secret-expiry warns about a secret that is about to expire. |
Related
- OAuth 2.0 and OpenID Connect: every setting, and why.
- Security profiles: RFC 9700, OAuth 2.1, DPoP, mTLS, FAPI.
- Applications: the registry these recipes write to.
- Management API: the token, and the OpenAPI document at
/admin-api/openapi.json. - Configuring OpenID Connect flows and Configuring SAML profiles.