PingDS 7.5.1

HTTP access

Set the HTTP port

The following steps demonstrate how to set up an HTTP port if none was configured at setup time with the --httpPort option:

  1. Create an HTTP connection handler:

    $ dsconfig \
 create-connection-handler \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --handler-name HTTP \
 --type http \
 --set enabled:true \
 --set listen-port:8080 \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

  2. Enable an HTTP access log.

    1. The following command enables JSON-based HTTP access logging:

      $ dsconfig \
 set-log-publisher-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --publisher-name "Json File-Based HTTP Access Logger" \
 --set enabled:true \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

    2. The following command enables HTTP access logging:

      $ dsconfig \
 set-log-publisher-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --publisher-name "File-Based HTTP Access Logger" \
 --set enabled:true \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

  3. After you set up an HTTP port, enable an HTTP endpoint.

    For details, refer to Use administrative APIs.

Set the HTTPS port

At setup time use the --httpsPort option.

Later, follow these steps to set up an HTTPS port:

  1. Create an HTTPS connection handler.

    The following example sets the port to 8443 and uses the default server certificate:

    $ dsconfig \
 create-connection-handler \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --handler-name HTTPS \
 --type http \
 --set enabled:true \
 --set listen-port:8443 \
 --set use-ssl:true \
 --set key-manager-provider:PKCS12 \
 --set trust-manager-provider:"JVM Trust Manager" \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

    If the key manager provider has multiple key pairs that DS could use for TLS, where the secret key was generated with the same key algorithm, such as EC or RSA, you can specify which key pairs to use with the --set ssl-cert-nickname:server-cert option. The server-cert is the certificate alias of the key pair. This option is not necessary if there is only one server key pair, or if each secret key was generated with a different key algorithm.

  2. Enable the HTTP access log.

    1. The following command enables JSON-based HTTP access logging:

      $ dsconfig \
 set-log-publisher-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --publisher-name "Json File-Based HTTP Access Logger" \
 --set enabled:true \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

    2. The following command enables HTTP access logging:

      $ dsconfig \
 set-log-publisher-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --publisher-name "File-Based HTTP Access Logger" \
 --set enabled:true \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

  3. If the deployment requires SSL client authentication, set the properties ssl-client-auth-policy and trust-manager-provider appropriately.

  4. After you set up an HTTPS port, enable an HTTP endpoint.

    For details, refer to Use administrative APIs.

Configure HTTP authorization

HTTP authorization mechanisms map HTTP credentials to LDAP credentials.

Multiple HTTP authorization mechanisms can be enabled simultaneously.

These HTTP authorization mechanisms are supported:

HDAP (enabled by default)

Process anonymous, basic and bearer authorization requests.

This mechanism treats anonymous requests like the HTTP Anonymous mechanism.

For HTTP Basic requests, this mechanism matches an HDAP resource _id to the DN. The _id matches the suffix of the path to the resource. For example, the default directory superuser _id is uid=admin. Babs Jensen’s _id is dc=com/dc=example/ou=People/uid=bjensen.

For HTTP Bearer requests, this mechanism uses a JSON Web Token (JWT). Get the JWT with the HDAP authenticate action. For details, refer to Bearer auth.

HTTP Anonymous (enabled by default)

Process anonymous HTTP requests, optionally binding with a specified DN.

If the client does not specify a bind DN (default), it binds as an anonymous LDAP user.

HTTP Basic (enabled by default)

Process HTTP Basic authorization requests by mapping the HTTP Basic identity to a user’s directory account.

By default, DS uses the exact match identity mapper with its default configuration to map the HTTP Basic username to an LDAP uid. DS searches all local public naming contexts to find the user’s entry based in the uid value. For details, refer to Identity mappers.

HTTP OAuth2 CTS

Process OAuth 2.0 requests as a resource server, acting as the AM Core Token Service (CTS) store.

When the client bearing an OAuth 2.0 access token presents the token to access the JSON resource, DS tries to resolve the access token against its CTS data. If DS finds the access token and it has not expired, DS extracts the user identity and OAuth 2.0 scopes. If the required scopes are present and the token is valid, DS maps the user identity to a directory account.

This mechanism makes an internal request, avoiding a request to AM. This mechanism does not ensure the token has been replicated to the DS serving the request.

The AM CTS store is constrained to a specific layout. The authzid-json-pointer must use userName/0 for the user identifier.

HTTP OAuth2 OpenAM

Process OAuth 2.0 requests as a resource server, sending requests to AM for access token resolution.

When the client bearing an OAuth 2.0 access token presents the token to access the JSON resource, DS requests token information from AM. If the access token is valid, DS extracts the user identity and OAuth 2.0 scopes. If the required scopes are present, DS maps the user identity to a directory account.

Send the requests to AM over HTTPS. Configure a truststore manager if necessary to trust the AM authorization server certificate. Configure a keystore manager if necessary to send the DS server certificate for mutual authentication.

HTTP OAuth2 Token Introspection (RFC7662)

Handle OAuth 2.0 requests as a resource server, sending requests to an RFC 7662-compliant authorization server for access token resolution.

The DS server must be registered as a client of the authorization server.

When the client bearing an OAuth 2.0 access token presents the token to access the JSON resource, DS requests token introspection from the authorization server. If the access token is valid, DS extracts the user identity and OAuth 2.0 scopes. If the required scopes are present, DS maps the user identity to a directory account.

Send the requests to the authorization server over HTTPS. Configure a truststore manager if necessary to trust the authorization server certificate. Configure a keystore manager if necessary to send the DS server certificate for mutual authentication.

The HTTP OAuth2 File mechanism is an internal interface intended for testing, and not supported for production use.

When more than one authentication mechanism is specified, DS applies the mechanisms in the following order:

  • If the client request has an Authorization header and an OAuth 2.0 mechanism is specified, DS attempts to apply the OAuth 2.0 mechanism.

  • If the client request has an Authorization header, or has the custom credentials headers specified in the configuration, and an HTTP Basic mechanism is specified, DS attempts to apply the Basic Auth mechanism.

  • Otherwise, if an HTTP anonymous mechanism is specified, and none of the previous mechanisms apply, DS attempts to apply the mechanism for anonymous HTTP requests.

There are many possibilities when configuring HTTP authorization mechanisms. This procedure shows only one OAuth 2.0 example.

The example below uses settings as listed in the following table. When using secure connections, make sure the servers can trust each other’s certificates. Download PingAM software from the BackStage download site:

Setting Value

OpenAM URL

https://am.example.com:8443/openam
(When using HTTPS, make sure DS can trust the AM certificate.)

Authorization server endpoint

/oauth2/tokeninfo (top-level realm)

Identity repository

DS server configured by the examples that follow.

OAuth 2.0 client ID

myClientID

OAuth 2.0 client secret

password

OAuth 2.0 client scopes

read, uid, write

Read the PingAM documentation if necessary to install and configure AM. Then follow these steps to try the demonstration:

  1. Update the default HTTP OAuth2 OpenAM configuration:

    $ dsconfig \
 set-http-authorization-mechanism-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --mechanism-name "HTTP OAuth2 OpenAM" \
 --set enabled:true \
 --set token-info-url:https://am.example.com:8443/openam/oauth2/tokeninfo \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

  2. Update the default HDAP endpoint configuration to use HTTP OAuth2 OpenAM as the authorization mechanism:

    $ dsconfig \
 set-http-endpoint-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --endpoint-name "/hdap" \
 --set authorization-mechanism:"HTTP OAuth2 OpenAM" \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

  3. Obtain an access token with the appropriate scopes:

    $ curl \
--request POST \
--user "myClientID:password" \
--data "grant_type=password&username=bjensen&password=hifalutin&scope=read%20uid%20write" \
https://am.example.com:8443/openam/oauth2/access_token
{
 "access_token": "<access-token>"",
 "scope": "uid read write",
 "token_type": "Bearer",
 "expires_in": 3599
}

    Use HTTPS when obtaining access tokens.

  4. Request a resource with HTTP Bearer authentication with the access token:

    $ curl \
--header "Authorization: Bearer <access-token>" \
--cacert ca-cert.pem \
'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=bjensen?_prettyPrint=true'

    Use HTTPS when presenting access tokens.

Use administrative APIs

The APIs for configuring and monitoring DS servers are under the following endpoints:

/alive

Check whether the server is currently alive, meaning its internal checks have not found any errors that would require administrative action.

By default, this endpoint returns a status code to anonymous requests and supports authenticated requests. For details, refer to Server is alive (HTTP).

/healthy

Check whether the server is currently healthy, meaning it is alive, the replication server is accepting connections on the configured port, and any replication delays are below the configured threshold.

By default, this endpoint returns a status code to anonymous requests, and supports authenticated requests. For details, refer to Server health (HTTP).

/metrics/prometheus

Access the server monitoring information in Prometheus monitoring software format.

By default, DS protects this endpoint with the HTTP Basic authorization mechanism. Users reading monitoring information must have the monitor-read privilege.

To use these APIs, follow these steps:

  1. Grant access to the /metrics/prometheus endpoint, if necessary, by assigning the monitor-read privilege.

    For details, refer to Administrative privileges.

    Alternatively, create a monitor user with the setup command when installing DS.

  2. Adjust the authorization-mechanism settings for the Admin endpoint.

    By default, DS uses the HTTP Basic authorization mechanism. The HTTP Basic authorization mechanism default configuration resolves the user identity extracted from the HTTP request to an LDAP user identity as follows:

    • If the request has an Authorization: Basic header for HTTP Basic authentication, DS extracts the username and password.

    • If the request has X-OpenIDM-Username and X-OpenIDM-Password headers, DS extracts the username and password.

    • DS uses the default exact match identity mapper to search for a unique match between the username and the UID attribute value of an entry in the local public naming contexts of the DS server.

      In LDAP terms, it searches all user base DNs for (uid=<http-username>). The username kvaughan maps to the example entry with DN uid=kvaughan,ou=People,dc=example,dc=com.

      For details, refer to Identity mappers and Configure HTTP authorization.

  3. Test access to the endpoint as an authorized user.