HTTP Access

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 \
    --trustStorePasswordFile /path/to/opendj/config/keystore.pin

2. (Optional) Enable an HTTP access log.

   • 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 \
      --trustStorePasswordFile /path/to/opendj/config/keystore.pin

   • 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 \
      --trustStorePasswordFile /path/to/opendj/config/keystore.pin

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

   For details, see "Configure HTTP User APIs" or "Use Administrative APIs".

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

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 \
    --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
    --no-prompt

2. (Optional) Enable the HTTP access log.

   • 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 \
      --trustStorePasswordFile /path/to/opendj/config/keystore.pin

   • 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 \
      --trustStorePasswordFile /path/to/opendj/config/keystore.pin

3. (Optional) 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, see "Configure HTTP User APIs" or "Use Administrative APIs".

The way directory data appears to client applications is configurable. You configure a Rest2ldap endpoint for each HTTP API to user data.

A Rest2ldap mapping file defines how JSON resources map to LDAP entries. The default mapping file is /path/to/opendj/config/rest2ldap/endpoints/api/example-v1.json. The default mapping works with Example.com data from the evaluation setup profile.

Edit or add mapping files for your own APIs. For details, see REST to LDAP Reference.

If you have set up a directory server with the ds-evaluation profile, you can skip to Step 3:

1. (Optional) If necessary, change the properties of the default Rest2ldap endpoint, or create a new endpoint.

   The default Rest2ldap HTTP endpoint is named /api after its base-path. The base-path must be the same as the name, and is read-only after creation. By default, the /api endpoint requires authentication.

   The following example enables the default /api endpoint:

   $ dsconfig \
    set-http-endpoint-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN uid=admin \
    --bindPassword password \
    --endpoint-name /api \
    --set authorization-mechanism:"HTTP Basic" \
    --set config-directory:config/rest2ldap/endpoints/api \
    --set enabled:true \
    --no-prompt \
    --usePkcs12TrustStore /path/to/opendj/config/keystore \
    --trustStorePasswordFile /path/to/opendj/config/keystore.pin

   Alternatively, you can create another Rest2ldap endpoint to expose a different HTTP API, or to publish data under an alternative base path, such as /rest:

   $ dsconfig \
    create-http-endpoint \
    --hostname localhost \
    --port 4444 \
    --bindDN uid=admin \
    --bindPassword password \
    --endpoint-name /rest \
    --type rest2ldap-endpoint \
    --set authorization-mechanism:"HTTP Basic" \
    --set config-directory:config/rest2ldap/endpoints/api \
    --set enabled:true \
    --no-prompt \
    --usePkcs12TrustStore /path/to/opendj/config/keystore \
    --trustStorePasswordFile /path/to/opendj/config/keystore.pin

2. (Optional) If necessary, adjust the endpoint configuration to use an alternative HTTP authorization mechanism.

   By default, the Rest2ldap endpoint maps HTTP Basic authentication to LDAP authentication. Change the authorization-mechanism setting as necessary. For details, see "Configure HTTP Authorization".

3. (Optional) Try reading a resource.

   The following example generates the CA certificate in PEM format from the server deployment key and password. It uses the CA certificate to trust the server certificate. A CA certificate is only necessary if the CA is not well-known:

   $ dskeymgr \
    export-ca-cert \
    --deploymentKey $DEPLOYMENT_KEY \
    --deploymentKeyPassword password \
    --outputFile ca-cert.pem
   $ curl \
    --cacert ca-cert.pem \
    --user bjensen:hifalutin \
    https://localhost:8443/api/users/bjensen?_prettyPrint=true
   {
     "_id" : "bjensen",
     "_rev" : "<revision>",
     "_schema" : "frapi:opendj:rest2ldap:posixUser:1.0",
     "_meta" : { },
     "userName" : "bjensen@example.com",
     "displayName" : [ "Barbara Jensen", "Babs Jensen" ],
     "name" : {
       "givenName" : "Barbara",
       "familyName" : "Jensen"
     },
     "description" : "Original description",
     "contactInformation" : {
       "telephoneNumber" : "+1 408 555 1862",
       "emailAddress" : "bjensen@example.com"
     },
     "uidNumber" : 1076,
     "gidNumber" : 1000,
     "homeDirectory" : "/home/bjensen",
     "manager" : {
       "_id" : "trigden",
       "displayName" : "Torrey Rigden"
     }
   }

HTTP authorization mechanisms map HTTP credentials to LDAP credentials.

Multiple HTTP authorization mechanisms can be enabled simultaneously. You can assign different mechanisms to Rest2ldap endpoints and to the Admin endpoint.

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 ForgeRock Access Management software from the ForgeRock BackStage download site:

Read the ForgeRock Access Management 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 \
    --trustStorePasswordFile /path/to/opendj/config/keystore.pin

2. Update the default Rest2ldap 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 "/api" \
    --set authorization-mechanism:"HTTP OAuth2 OpenAM" \
    --no-prompt \
    --usePkcs12TrustStore /path/to/opendj/config/keystore \
    --trustStorePasswordFile /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": "token-string",
    "scope": "uid read write",
    "token_type": "Bearer",
    "expires_in": 3599
   }

   Use HTTPS when obtaining access tokens.

4. Request a resource at the Rest2ldap endpoint using HTTP Bearer authentication with the access token:

   $ curl \
    --header "Authorization: Bearer token-string" \
    --cacert ca-cert.pem \
    https://localhost:8443/api/users/bjensen?_prettyPrint=true
   {
     "_id": "bjensen",
     "_rev": "<revision>",
     "_schema": "frapi:opendj:rest2ldap:posixUser:1.0",
     "_meta": {},
     "userName": "bjensen@example.com",
     "displayName": ["Barbara Jensen", "Babs Jensen"],
     "name": {
       "givenName": "Barbara",
       "familyName": "Jensen"
     },
     "description": "Original description",
     "contactInformation": {
       "telephoneNumber": "+1 408 555 1862",
       "emailAddress": "bjensen@example.com"
     },
     "uidNumber": 1076,
     "gidNumber": 1000,
     "homeDirectory": "/home/bjensen",
     "manager": {
       "_id": "trigden",
       "displayName": "Torrey Rigden"
     }
   }

   Use HTTPS when presenting access tokens.

To use the Admin endpoint APIs, follow these steps:

1. Grant users access to the endpoints as appropriate:

   • For access to /admin/config, assign config-read or config-write privileges.

     The following example assigns the config-read privilege to Kirsten Vaughan:

     $ ldapmodify \
      --hostname localhost \
      --port 1636 \
      --useSsl \
      --usePkcs12TrustStore /path/to/opendj/config/keystore \
      --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
      --bindDN uid=admin \
      --bindPassword password << EOF
     dn: uid=kvaughan,ou=People,dc=example,dc=com
     changetype: modify
     add: ds-privilege-name
     ds-privilege-name: config-read
     EOF

   • For access to /metrics endpoints, if no account for monitoring was created at setup time, assign the monitor-read privilege.

     The following example adds the monitor-read privilege to Kirsten Vaughan's entry:

     $ ldapmodify \
      --hostname localhost \
      --port 1636 \
      --useSsl \
      --usePkcs12TrustStore /path/to/opendj/config/keystore \
      --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
      --bindDN uid=admin \
      --bindPassword password << EOF
     dn: uid=kvaughan,ou=People,dc=example,dc=com
     changetype: modify
     add: ds-privilege-name
     ds-privilege-name: monitor-read
     EOF

   For details, see "Administrative Privileges".

2. (Optional) Adjust the authorization-mechanism settings for the Admin endpoint.

   By default, the Admin endpoint 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:

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

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

   3. The server 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 other words, in LDAP terms, it searches under all user data 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, see "Identity Mappers", and "Configure HTTP Authorization".

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

   The following example reads the Admin endpoint resource under /admin/config. The following example generates the CA certificate in PEM format from the server deployment key and password. It uses the CA certificate to trust the server certificate. A CA certificate is only necessary if the CA is not well-known:

   $ dskeymgr \
    export-ca-cert \
    --deploymentKey $DEPLOYMENT_KEY \
    --deploymentKeyPassword password \
    --outputFile ca-cert.pem
   $ curl \
    --cacert ca-cert.pem \
    --user kvaughan:bribery \
    https://localhost:8443/admin/config/http-endpoints/%2Fadmin?_prettyPrint=true
   {
     "_id" : "/admin",
     "_rev" : "<revision>",
     "_schema" : "admin-endpoint",
     "java-class" : "org.opends.server.protocols.http.rest2ldap.AdminEndpoint",
     "base-path" : "/admin",
     "enabled" : true,
     "authorization-mechanism" : "HTTP Basic"
   }

   Notice how the path to the resource in the example above, /admin/config/http-endpoints/%2Fadmin, corresponds to the DN of the entry under cn=config, which is ds-cfg-base-path=/admin,cn=HTTP Endpoints,cn=config.

   The following example demonstrates reading everything under /metrics/api:

   $ curl \
    --cacert ca-cert.pem \
    --user kvaughan:bribery \
    https://localhost:8443/metrics/api?_queryFilter=true