PingDirectory

SCIM 1.1 servlet extension authentication

The SCIM 1.1 servlet supports authentication using either the HTTP Basic authentication scheme, or OAuth 2.0 bearer tokens. When authenticating using HTTP Basic authentication, the SCIM 1.1 servlet attempts to correlate the user name component of the Authorization header to a DN in the PingDirectory server. If the user name value cannot be parsed directly as a DN, it is correlated to a DN using an Identity Mapper. The DN is then used in a simple bind request to verify the password.

In deployments that use an OAuth authorization server, the SCIM 1.1 extension can be configured to authenticate requests using OAuth bearer tokens. The SCIM 1.1 extension supports authentication with OAuth 2.0 bearer tokens (per RFC 6750) using an OAuth Token Handler Server SDK Extension. Because the OAuth 2.0 specification does not specify how contents of a bearer token are formatted, the Server provides the token handler API to decode incoming bearer tokens and extract or correlate associated authorization DNs.

Neither HTTP Basic authentication nor OAuth 2.0 bearer token authentication are secure unless SSL is used to encrypt the HTTP traffic.

Enabling HTTPS communications

To make the System for Cross-domain Identity Management (SCIM) HTTP connection handler use SSL (which is mandated by the SCIM specification), enable a Key Manager provider and Trust Manager provider.

About this task

This topic applies only to the PingDirectoryProxy server.

Steps

  • To enable SSL during the server’s initial setup, include the --ldapsPort and the --generateSelfSignedCertificate subcommands with the setup command.

  • If your server already has a certificate that you would like to use:

    Choose from:

    • Set the key-manager-provider to the value you set when you enabled SSL in the server..

    • Define a new key manager provider.

    For more information, see Configuring HTTP connection handlers.

Configuring basic authentication using an identity mapper

About this task

By default, the SCIM servlet is configured to use the Exact Match Identity Mapper, which matches against the uid attribute. In this example, an alternate Identity Mapper is created so that clients can authenticate using cn values.

Steps

  1. Create a new Identity Mapper that uses a match attribute of cn.

    Example:

    $ bin/dsconfig create-identity-mapper \
  --mapper-name "CN Identity Mapper" \
  --type exact-match \
  --set enabled:true \
  --set match-attribute:cn

  2. Configure the SCIM servlet to use the new Identity Mapper.

    Example:

    $ bin/dsconfig set-http-servlet-extension-prop \
  --extension-name SCIM \
  --set "identity-mapper:CN Identity Mapper"

Enabling OAuth authentication

About this task

To enable OAuth authentication, you need to create an implementation of the OAuthTokenHandler using the API provided in the Server SDK. For details on creating an OAuthTokenHandler extension, see the Server SDK documentation.

Steps

  1. Install your OAuth token handler on the server using dsconfig.

    Example:

    $ bin/dsconfig create-oauth-token-handler \
  --handler-name ExampleOAuthTokenHandler \
  --type third-party \
  --set extension-class:com.unboundid.directory.sdk.examples.ExampleOAuthTokenHandler

  2. Configure the SCIM servlet extension to use it as follows:

    Example:

    $ bin/dsconfig set-http-servlet-extension-prop \
  --extension-name SCIM \
  --set oauth-token-handler:ExampleOAuthTokenHandler

Using HTTP basic authentication with bare UID on the PingDirectoryProxy server

Clients can authenticate to the System for Cross-domain Identity Management (SCIM) extension using HTTP basic authentication and a bare UID value.

About this task

This topic applies only to the PingDirectoryProxy server.

When a SCIM extension is hosted by a PingDirectoryProxy server, you must explicitly configure the server with the names of subordinate base distinguished names (DNs) to search.

Make sure to specify your deployment’s subordinate base DN.

Steps

  • To configure the server with the names of subordinate base DNs, run the following command on the PingDirectoryProxy server for every base DN that you can access using SCIM.

    $ bin/dsconfig set-root-dse-backend-prop \
  --set subordinate-base-dn:dc=example,dc=com