The Consent Service supports two HTTP authentication methods, which are both enabled by default:

  • Basic authentication
  • Bearer token authentication

The Consent servlet looks at the request's Authorization header to determine which authentication type is being used by the client.

With basic authentication, the client provides an encoded user name-password pair in the HTTP Authorization request header. When the Consent Service receives a request using basic authentication, it maps the user name credential to a DN using an identity mapper. This DN is designated the auth DN and is used to make subsequent authorization decisions. The Consent Service then performs an LDAP bind using the DN and password to determine if the request can be processed.

With bearer token authentication, the client provides an access token in the HTTP Authorization request header. The access token is always obtained by the client from an external OAuth 2 authorization server and encapsulates information ("claims") about a user identity, the client identity, and the requests that the client is authorized to make.

The PingDirectory Server must be configured to accept access tokens using one or both available access token validators:

  • PingFederate access token validator. Supports access tokens issued by a PingFederate authorization server. This validator verifies an access token and discovers its claims by making a request to the PingFederate server's token introspection endpoint.

    Note:

    If you are using PingFederate 10.0 or earlier, ensure that PingFederate is configured to respond to OAuth and OpenID Connect (OIDC) requests by selecting the Enable OAuth 2.0 Authorization Server (AS) role and OpenID Connect check boxes as explained in Enabling the OAuth AS role. Starting with PingFederate 10.1, these items are always enabled.

  • JWT access token validator. Supports signed or encrypted JWT access tokens issued by an arbitrary authorization server. This validator checks an access token by cryptographically verifying the token's signature using a trusted public certificate. The token's claims are encoded in the token itself, so discovering the token's claims does not require an outgoing token introspection request.

The token validator uses its identity mapper to map the subject claim to a DN. This DN is designated the auth DN and is used along with the token's claims to make subsequent authorization decisions.

If the PingDirectory Server is configured with at least one access token validator, it will be used by the Consent Service. If the PingDirectory Server is configured with more than one access token validator, the validators are consulted in order until one is able to successfully authenticate the request.

If the PingDirectory Server is configured with multiple access token validators, but only one should be used by the Consent Service, the access token validator can be configured by setting the access-token-validator property of the Consent HTTP Servlet Extension.

Note: Configuring an access token validator for the Consent Service requires information from the authorization server configuration:
  • The values that the authorization server sets for subject claims must be mappable to a DN in the PingDirectory Server.
  • The authorization server must be configured to authorize clients and grant scopes appropriately for privileged or unprivileged Consent API access.
  • The authorization server must be configured to issue tokens with scopes corresponding to the Consent Service's unprivileged-scope-name and privileged-scope-name configuration.
Refer to the authorization server's documentation for guidance.