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.
The OAuth Bearer SASL Mechanism Handler component inherits from the SASL Mechanism Handler
The following components have a direct aggregation relation from OAuth Bearer SASL Mechanism Handlers:
The properties supported by this managed object are as follows:
| 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 |
| 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 |
| 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 |
| 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:
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 |
| 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 |
| 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 |
| 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 |
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}