OAuth Bearer SASL Mechanism Handler

Note: this component is designated "advanced", which means that objects of this type are not expected to be created or altered in most environments. If you believe that such a change is necessary, you may want to contact support in order to understand the potential impact of that change.

The OAuth Bearer SASL Mechanism Handler may be used to authenticate to the Directory Server using the OAUTHBEARER SASL mechanism as described in RFC 7628. Clients using this mechanism must provide an OAuth 2.0 access token (or optionally an OpenID Connect ID token) that can be validated and mapped to a local user entry.

Parent Component Relations from This Component Properties dsconfig Usage

Parent Component

The OAuth Bearer SASL Mechanism Handler component inherits from the SASL Mechanism Handler

Relations from This Component

The following components have a direct aggregation relation from OAuth Bearer SASL Mechanism Handlers:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
 description  None
 enabled
 access-token-validator
 id-token-validator
 require-both-access-token-and-id-token
 validate-access-token-when-id-token-is-also-provided
 alternate-authorization-identity-mapper
 all-required-scope
 any-required-scope
 server-fqdn

Basic Properties

description

Description
A description for this SASL Mechanism Handler
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

enabled

Description
Indicates whether the SASL mechanism handler is enabled for use.
Default Value
None
Allowed Values
true
false
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

access-token-validator

Description
An access token validator that will ensure that each presented OAuth access token is authentic and trustworthy. It must be configured with an identity mapper that will be used to map the access token to a local entry. At least one access token validator or ID token validator must be configured. If multiple access token validators are configured, then they will be evaluated in ascending order of their evaluation-order-index property values.
If this OAuth Bearer SASL Mechanism Handler is only configured with one or more access token validators but no ID token validators, then all tokens presented in the "auth" element must be OAuth access tokens. Bind requests that also include the "pingidentityidtoken" element will be rejected because the server will not be able to validate that ID token.
If this OAuth Bearer SASL Mechanism Handler is only configured with one or more ID token validators but no access token validators, then all OAUTHBEARER bind requests must contain OpenID Connect ID tokens. If the bind request contains both an "auth" element and a "pingidentityidtoken" element, then the "auth" element must include an OAuth access token and the "pingidentityidtoken" must contain the ID token. If the "auth" element is present without a "pingidentityidtoken" element, then the token provided in the "auth" element must be an OpenID Connect ID token.
If this OAuth Bearer SASL Mechanism Handler is configured with both access token validators and ID token validators, then the token presented in the "auth" element of the bind request must always be an OAuth access token. If an ID token is to be provided, then it must be provided in the custom "pingidentityidtoken" element of the bind request (and the "auth" element must still be used to provide the access token). In such cases, the ID token will always be validated, and the validate-access-token-when-id-token-is-also-provided property will be used to determine whether to also validate the access token.
Default Value
None
Allowed Values
The DN of any Access Token Validator. The access token validator must be enabled, and it must be configured with an identity mapper.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

id-token-validator

Description
An ID token validator that will ensure that each presented OpenID Connect ID token is authentic and trustworthy, and that will map the token to a local entry. At least one access token validator or ID token validator must be configured. If multiple ID token validators are configured, then they will be evaluated in ascending order of their evaluation-order-index property values.
If an ID token is provided, then zero or more of the following additional elements may be included in the bind request to specify validation parameters for use in validating the ID token:
  • pingidentityidtokenclientid -- The client ID that is expected to match the ID token's "aud" value.
  • pingidentityidtokenissuer -- The issuer that is expected to match the ID token's "iss" value.
  • pingidentityidtokennonce -- The nonce that is expected to match the ID token's "nonce" value.

If this OAuth Bearer SASL Mechanism Handler is only configured with one or more access token validators but no ID token validators, then all tokens presented in the "auth" element must be OAuth access tokens. Bind requests that also include the "pingidentityidtoken" element will be rejected because the server will not be able to validate that ID token.
If this OAuth Bearer SASL Mechanism Handler is only configured with one or more ID token validators but no access token validators, then all OAUTHBEARER bind requests must contain OpenID Connect ID tokens. If the bind request contains both an "auth" element and a "pingidentityidtoken" element, then the "auth" element must include an OAuth access token and the "pingidentityidtoken" must contain the ID token. If the "auth" element is present without a "pingidentityidtoken" element, then the token provided in the "auth" element must be an OpenID Connect ID token.
If this OAuth Bearer SASL Mechanism Handler is configured with both access token validators and ID token validators, then the token presented in the "auth" element of the bind request must always be an OAuth access token. If an ID token is to be provided, then it must be provided in the custom "pingidentityidtoken" element of the bind request (and the "auth" element must still be used to provide the access token). In such cases, the ID token will always be validated, and the validate-access-token-when-id-token-is-provided property will be used to determine whether to also validate the access token.
Default Value
None
Allowed Values
The DN of any ID Token Validator. The ID token validator must be enabled.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

require-both-access-token-and-id-token

Description
Indicates whether bind requests will be required to have both an OAuth access token (in the "auth" element of the bind request) and an OpenID Connect ID token (in the "pingidentityidtoken" element of the bind request). If this property is true, then this OAuth Bearer SASL Mechanism Handler must be configured with both access token validators and ID token validators, and the server will reject any bind request that does not contain both an access token and an ID token. If this property is false, then either or both an access token and an ID token may be used to authenticate.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

validate-access-token-when-id-token-is-also-provided

Description
Indicates whether to validate the OAuth access token in addition to the OpenID Connect ID token in OAUTHBEARER bind requests that contain both types of tokens. For bind requests that include both an access token (in the "auth" element) and an ID token (in the "pingidentityidtoken" element), the ID token will always be validated using an ID token validator. The server may optionally also validate the access token, and may further optionally make sure that it maps to the same user as the ID token.
Default Value
validate-only-the-id-token
Allowed Values
validate-only-the-id-token - Indicates that the server should only use the configured ID token validators to validate the ID token and map it to a corresponding local user. The access token will not be validated.

validate-both-tokens-but-only-map-the-id-token - Indicates that the server should validate both the access token and the ID token to ensure that they are valid, but that it should only use the selected ID token validator's identity mapper to identify the corresponding local user. The server will not attempt to map the access token to a local user.

validate-and-map-both-tokens - Indicates that the server should validate both the access token and the ID token to ensure that they are valid, and that it should also use the selected access and ID token validators' identity mappers to identify the corresponding local user and verify that both tokens map to the same user.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

alternate-authorization-identity-mapper

Description
The identity mapper that will be used to map an alternate authorization identity (provided in the GS2 header of the encoded OAUTHBEARER bind request credentials) to the corresponding local entry. If this is not provided, then the identity mapper for the selected access token validator or ID token validator will be used. selected access token validator's identity mapper will be used.
Default Value
The identity mapper for the selected access token validator or ID token validator will be used.
Allowed Values
The DN of any Identity Mapper. The identity mapper must be enabled.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

all-required-scope

Description
The set of OAuth scopes that will all be required for any access tokens that will be allowed for authentication. If multiple all-required-scope values are configured, then access tokens must have all of those scopes to be allowed. Any access token that is missing one or more of the scopes will not be allowed to authenticate.
Because OpenID Connect ID tokens do not have scopes, scopes should only be required when access tokens will always be provided and validated (that is, when this OAuth Bearer SASL Mechanism Handler is configured with only access token validators but no ID token validators, or when it is configured with both access token validators and ID token validators and require-both-access-token-and-id-token is set to true).
Default Value
None
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

any-required-scope

Description
The set of OAuth scopes that a token may have to be allowed for authentication. If multiple any-required-scope values are configured, then acces tokens must have at least one of those scopes to be allowed. Any access token that does not have any of the scopes will not be allowed to authenticate.
Because OpenID Connect ID tokens do not have scopes, scopes should only be required when access tokens will always be provided and validated (that is, when this OAuth Bearer SASL Mechanism Handler is configured with only access token validators but no ID token validators, or when it is configured with both access token validators and ID token validators and require-both-access-token-and-id-token is set to true).
Default Value
None
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

server-fqdn

Description
The fully-qualified name that clients are expected to use when communicating with the server. This will be used for bind requests that include the optional host element. If it is not provided, then the server will attempt to infer a hostname from the underlying system.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured SASL Mechanism Handlers:

dsconfig list-sasl-mechanism-handlers
     [--property {propertyName}] ...

To view the configuration for an existing SASL Mechanism Handler:

dsconfig get-sasl-mechanism-handler-prop
     --handler-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing SASL Mechanism Handler:

dsconfig set-sasl-mechanism-handler-prop
     --handler-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new OAuth Bearer SASL Mechanism Handler:

dsconfig create-sasl-mechanism-handler
     --handler-name {name}
     --type oauth-bearer
     --set enabled:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing SASL Mechanism Handler:

dsconfig delete-sasl-mechanism-handler
     --handler-name {name}