File(s): conf/relying-party.xml, conf/oidc.properties
Format: Native Spring, Spring Properties
Overview
The OAUTH2.Token profile configuration bean enables support for the OAUTH 2 Token endpoint, which implements the flow that supports OAuth token granting use cases, including OIDC-specific grant features in support of that particular use case.
In V3.1+ of the plugin, the behavior of the Authorization and Token endpoints has been optionally split into separate profile configurations, in order to support additional OAuth use cases specific to the token endpoint and to allow for more configuration flexibility. When this profile bean is absent, the presence of the OIDC.SSO profile configuration bean implies the OIDC-specific functionality of this endpoint is active with the settings configured on that bean. When present, it supersedes that behavior and directly configures all uses of the endpoint.
Configuration
The most typical options used are described in more detail below, but not every obscure option is discussed. See the javadoc for all of the possible configuration options for this profile (note that some of them are inherited from parent classes).
Virtually all the configuration options below can be set via two different properties: a static property that explicitly sets the value to use and a lookup strategy or predicate property that takes a Function or Predicate and returns the value to use. The dynamic property is generally named "propertyNamePredicate" or "propertyNameLookupStrategy" for Boolean- and non-Boolean-valued properties respectively.
Common
Options common to most/all profiles:
Name | Type | Default | Description |
---|
securityConfiguration | SecurityConfiguration | Bean named shibboleth.DefaultSecurityConfiguration | An object containing all of the default security-related objects needed for peer authentication and encryption. See SecurityConfiguration for complete details. |
disallowedFeatures | Integer | 0 | A bitmask of features to disallow, the mask values being specific to individual profiles |
inboundInterceptorFlows | List<String> | | Ordered list of profile interceptor flows to run prior to message processing |
outboundInterceptorFlows | List<String> | | Ordered list of profile interceptor flows to run prior to outbound message handling |
Guidance
Modifying the security configuration is usually done to:
specify an alternate signing or decryption key to use
control signing or encryption algorithms (but for metadata you control, it's advisable to control algorithms by using an extension to specify supported algorithms).
The two interceptor lists allow the much less commonly used profile interceptor injection points to be used. This is largely a Java-based way of doing very low-level sorts of “message rewriting” hackery that might otherwise be impossible to pull off. One use case for the inbound side might be picking up non-standard parameters in a SAML request.
Flow Types
Options common to OP profiles with OIDC flow settings:
Name | Type | Default | Description |
---|
authorizationCodeFlowEnabled | Boolean | true | Whether to enable the authorization code flow |
hybridFlowEnabled | Boolean | true | Whether to enable the hybrid flow |
implicitFlowEnabled | Boolean | true | Whether to enable the implicit flow |
refreshTokensEnabled | Boolean | true | Whether to enable refresh token support |
Client Authentication
Options common to OP profiles that support client authentication:
Name | Type | Default | Description |
---|
tokenEndpointAuthMethods | Collection<String> | client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt | Enabled endpoint client authentication methods |
unregisteredClientPolicy 4.0 | Map<String, UnregisteredClientPolicy> | See wiki page | The policy used to verify unverified clients when this profile is enabled in the unverified RP config |
For convenience, this is also controllable globally via the idp.oidc.tokenEndpointAuthMethods property.
Since OP v3.4, the JWT-based client authentication methods (client_secret_jwt and private_key_jwt) accepts any of the following three audiences:
OP issuer value (profile responder ID)
The token flow endpoint URL value (even for introspection and revocation endpoints)
The flow endpoint URL value
Prior to V3.4, only the flow endpoint URL value could be used. Any custom bean for validating the audience can be set via idp.oauth2.jwtAuth.audienceValidator -property.
OAuth Profile-Specific
Options specific to generic or OAuth usage of the Token flow:
Name | Type | Default | Description |
---|
resolveAttributes | Boolean | true | Whether to resolve attributes during the token issuance process |
grantTypes | Collection<String> | authorization_code, refresh_token | OAuth grant types to allow |
accessTokenLifetime | Duration | PT10M | Lifetime of access token issued to client If you customize this, make sure to set the revocation cache lifetime (See Replay and Revocation section later at this page) to at least this length of time. Also check refreshTokenTimeout and use whichever is longer. |
refreshTokenLifetime
| Duration
| PT2H
| Lifetime of refresh token issued to client (Deprecated since 3.4)
|
refreshTokenTimeout 3.4 | Duration | PT2H | Lifetime of a single refresh token issued to client If you customize this, make sure to set the revocation cache lifetime (See Replay and Revocation section later at this page) to at least this length of time. Also check accessTokenLifetime and use whichever is longer. |
refreshTokenChainLifetime 3.4 | Duration | PT2H | Lifetime of the chain of refresh tokens issued to client. The expiration instant is calculated by adding the lifetime to the end-user authentication instant. |
forcePKCE | Boolean | false | Whether client is required to use PKCE |
allowPKCEPlain | Boolean | false | Whether client is allowed to use PKCE code challenge method "plain" |
accessTokenType 3.2 | String | | Format of access token. Supported values are “JWT” or nothing/empty/null, implying opaque tokens. |
refreshTokenType 4.1 | String | | Format of refresh token. Supported values are “JWT” or nothing/empty/null, implying opaque tokens. |
enforceRefreshTokenRotation 3.2 | Boolean | false | Whether to enforce refresh token rotation. If enabled, the refresh token is revoked whenever it is used for issuing a new refresh token. |
accessTokenClaimsSetManipulationStrategy 3.2 | BiFunction< ProfileRequestContext, Map<String,Object>, Map<String,Object> > | | Manipulation strategy for customising access token claims set contents. The BiFunction inputs are the ProfileRequestContext and the current contents of the claims set as a Map<String,Object>. If the result is non-null, the result (Map<String,Object) is used to replace the contents of the claims set. It is the deployer’s responsibility to ensure the results remain valid/appropriate. |
refreshTokenClaimsSetManipulationStrategy 3.2 | BiFunction< ProfileRequestContext, Map<String,Object>, Map<String,Object> > | | Manipulation strategy for customising refresh token claims set contents. The BiFunction inputs are the ProfileRequestContext and the current contents of the claims set as a Map<String,Object>. If the result is non-null, the result (Map<String,Object) is used to replace the contents of the claims set. It is the deployer’s responsibility to ensure the results remain valid/appropriate. |
The following properties can be used to globally adjust some of the settings above (some of them affect other profiles as well).
idp.oauth2.grantTypes
idp.oidc.accessToken.defaultLifetime
idp.oidc.refreshToken.defaultLifetime (deprecated since v3.4)
idp.oidc.refreshToken.defaultTimeout 3.4
idp.oidc.refreshToken.defaultChainLifetime 3.4
idp.oidc.forcePKCE
idp.oidc.allowPKCEPlain
idp.oauth2.enforceRefreshTokenRotation 3.2
idp.oauth2.accessToken.type 3.2
idp.oauth2.refreshToken.type 4.1
idp.oauth2.refreshToken.deserializers 4.1
idp.oauth2.refreshToken.serializationStrategies 4.1
OIDC Profile-Specific
Options specific to the use of OIDC with the Token flow (in addition to the OAuth settings above):
Name | Type | Default | Description |
---|
encryptionOptional | Boolean | true | Whether the absence of encryption details in a client’s metadata should fail when issuing an ID token |
iDTokenLifetime | Duration | PT1H | Lifetime of ID token issued to client |
additionalAudiencesForIdToken | Set<String> | | Adds additional valid audiences for ID token. This feature does not involve any policy controls or features that may be added in the future to support issuing tokens to parties other than the OIDC client. It should be used with caution, and in most cases avoided. |
alwaysIncludedAttributes | Set<String> | | Specifies IdPAttributes to always include in ID token regardless of response_type |
issueIdTokenViaRefreshToken 3.4 | Boolean | true | Whether to issue id_token when refresh_token grant type is used. |
IDTokenManipulationStrategy 3.2 | BiFunction< ProfileRequestContext, Map<String,Object>, Map<String,Object> > | | Manipulation strategy for customising id_token contents. The BiFunction inputs are the ProfileRequestContext and the current contents of id_token as a Map<String,Object>. If the result is non-null, the result (Map<String,Object) is used to replace the contents of the id_token. It is the deployer’s responsibility to ensure the results remain valid/appropriate. |
The following properties can be used to globally adjust some of the settings above (some of them affect other profiles as well).
idp.oauth2.encryptionOptional
idp.oidc.idToken.defaultLifetime
idp.oidc.alwaysIncludedAttributes
idp.oidc.issueIdTokenViaRefreshToken 3.4
The final option relates to "claims splitting" and override the typical processing rules for when to insert claims into particular tokens. Typically most "data" is omitted from the front-channel ID token unless no authorization code is being issued, with the claims only accessed via the UserInfo endpoint. This setting forces claims into or out of the ID token.
Replay and Revocation
Authorization codes are bearer tokens and have to be limited to a single use as a security measure. Reuse is monitored by storing reference values in the existing IdP replay cache that handles related SAML and CAS needs. It should be noted that the criticality of this cache to CAS and OIDC are generally much higher than for SAML (unless SAML artifacts are used), and the limitations of an in-memory cache that is not clustered across servers much more severe.
Reuse of an authorization code invalidates all tokens derived from it by tracking revoked codes. This is handled by another (obviously server-side) cache, the revocation cache.
Two properties are provided in conf/oidc.properties to control aspects of this process:
Since V3.2, via support for revoking single tokens instead of the whole chain (see https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1376879313/OPRevocation#Configuration), an attempt to use a revoked refresh token causes the whole chain derived from the single revoked token to be revoked. The lifetime for this revocation record is then taken from https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1376879313/OPRevocation#Configuration.
Reference
Properties
Properties directly related to this configuration area follow:
Property / type | Default | Function |
---|
idp.oauth2.grantTypes | authorization_code,refresh_token | Comma-separated list of allowed grant types |
idp.oauth2.refreshToken.activation Bean ID for Predicate<ProfileRequestContext> | DefaultRefreshTokenActivationCondition | Activation condition for issuing refresh tokens |
idp.oauth2.enforceRefreshTokenRotation 3.2 | false | Flag to enforce refresh token rotation |
idp.oauth2.accessToken.type 3.2 | | Access token type, null/empty referring to opaque format |
idp.oauth2.refreshToken.type 4.1 | | Refresh token type, null/empty referring to opaque format |
idp.oauth2.refreshToken.deserializers 4.1 Bean ID for list of deserializer functions BiFunction<ProfileRequestContext,String,RefreshTokenClaimsSet> | shibboleth.oidc.DefaultRefreshTokenDeserializers | List of deserializer bi-functions that are used for decoding refresh token string value into RefreshTokenClaimsSet |
idp.oauth2.refreshToken.serializationStrategies 4.1 Bean ID for the map of serializer functions BiFunction<ProfileRequestContext,RefreshTokenClaimsSet,String> | shibboleth.oidc.DefaultRefreshTokenSerializationStrategies | Map of serializer functions tha are used for encoding RefreshTokenClaimsSet into refresh token string value. Keys refer to the refresh token types. |
idp.oidc.xmlSafeIdentifier 4.1 | true | Flag to use xml-safe identifiers: in practise it usually means '_' -prefix |
idp.oidc.logging.removeIpAddressFromProtocolMessage | false | Flag to remove IP address from protocol messages on DEBUG. On TRACE all information is included. |
idp.oidc.metadata.saml Bean ID for Predicate<ProfileRequestContext> | shibboleth.Conditions.TRUE | Condition to exploit SAML metadata |
idp.oidc.logging.objectMapper 4.1 Bean ID for ObjectMapper | shibboleth.oidc.JSONObjectMapper | The object mapper used for pretty-printing JSON in the protocol messages |
idp.oidc.idToken.defaultLifetime | PT1H | |
idp.oidc.accessToken.defaultLifetime | PT10M | |
idp.oidc.refreshToken.defaultTimeout 3.4 | PT2H | |
idp.oidc.refreshToken.defaultChainLifetime 3.4 | PT2H | |
idp.oidc.forcePKCE | false | Flag to enforce use of PKCE |
idp.oidc.allowPKCEPlain | false | Flag to allow plain PKCE challenges |
idp.oidc.alwaysIncludedAttributes | | Comma-separated list of attribute IDs that will be included to both id_token and user info response |
idp.oidc.issueIdTokenViaRefreshToken 3.4 | true | Flag to include ID token in the token response message when refresh token grant is used |
Beans
Beans directly related to this configuration area follow:
Name | Type | Description |
---|
shibboleth.oidc.UnregisteredClientPolicyEnforcer | BiFunction<Object,MetadataPolicy,Pair<Object,Boolean>> | Bi-function bean to enforce the given policy (second input) to the given object (first input). The result is a pair: the first item describing the object after enforcing policy and the second indicating whether the operation was successful. Overrides shibboleth.oidc.DefaultUnregisteredClientPolicyEnforcer |
shibboleth.oidc.UnregisteredClientPolicyValidator | Predicate<Map<String, UnregisteredClientPolicy>> | Predicate bean to verify that the given map of policies is valid. Overrides shibboleth.oidc.DefaultUnregisteredClientPolicyValidator |
shibboleth.oidc.AllowedScopeStrategy | Function<ProfileRequestContext, Scope> | Function bean to discover allowed scope. See scope filtering page for more information. Overrides shibboleth.oidc.DefaultAllowedScopeStrategy |
shibboleth.oidc.AllowedAudienceStrategy | Function<ProfileRequestContext, Audience> | Function bean to discover allowed audience for access token. Overrides shibboleth.oidc.DefaultAllowedAudienceStrategy |
shibboleth.oidc.token.MappedErrors | Map<String, ErrorObject> | Overrides shibboleth.oidc.DefaultApiMappedErrors |
shibboleth.oidc.IDTokenReservedClaimNames | List<String> | List of reserved claim names for ID token. Overrides shibboleth.oidc.DefaultIDTokenReservedClaimNames |
shibboleth.oidc.AccessTokenReservedClaimNames | List<String> | List of reserved claim names for access token. Overrides shibboleth.oidc.DefaultAccessTokenReservedClaimNames |
shibboleth.oidc.TokenPostResponseAuditExtractors | List<String> | List of audit extractors populated after token response. Overrides shibboleth.oidc.DefaultTokenPostResponseAuditExtractors |