PingDirectory

Configuring SCIM 1.1 for PingDirectory

The PingDirectory server provides a default SCIM HTTP Servlet Extension that can be enabled and configured using a dsconfig batch script located in the config directory. The script runs a series of commands that enables an HTTPS Connection Handler, increases the level of detail logged by the HTTP Detailed Access log publisher, and adds access controls to allow access to LDAP controls used by the SCIM Servlet Extension. There are additional optional configurations (for example, changing the log format, enabling the entryDN virtual attribute, and using VLV indexes) that you can make by altering the dsconfig batch script.

The SCIM resource mappings are defined by the scim-resources.xml file located in the config directory. This file defines the SCIM schema and maps it to the LDAP schema. This file can be customized to define and expose deployment specific resources.

The following procedures show how to configure SCIM on the server. The first example procedure shows the steps to manually configure SCIM without using the script. The second example procedure uses the dsconfig batch script to configure SCIM.

Configuring SCIM manually

About this task

The following example procedure assumes that you have configured the PingDirectory server using the default settings, which means that SSL and the HTTPS Connection Handler haven’t been configured. The examples show both the dsconfig non-interactive commands and interactive menu locations. You can only access some of the dsconfig interactive menu locations by displaying the Standard or Advanced object menus.

Steps

  1. Set up your certificates. Follow the examples shown in the manage-certificates section. You should have a keystore and truststore set up in the config directory. Make sure that keystore.pin and truststore.pin are set.

  2. Enable the key manager provider. The key manager provider accesses the certificate during the SSL handshake.

    Example:

    $ bin/dsconfig create-key-manager-provider \
  --provider-name JKS \
  --type file-based --set enabled:true
  --set key-store-file:config/keystore \
  --set key-store-type:JKS
  --set key-store-pin-file:config/keystore.pin

    If you’re running dsconfig interactively, go to Key Manager Provider > View and edit an existing Key Manager Provider > JKS (or the type of certificate you’re working with) and set enabled to true. Select finish to save your changes.

  3. Enable the trust manager provider. The trust manager provider determines if a presented certificate can be trusted.

    Example:

    $ bin/dsconfig create-trust-manager-provider
  --provider-name JKS \
  --type file-based --set enabled:true \
  --set trust-store-file:config/truststore \
  --set trust-store-type:JKS \
  --set trust-store-pin-file:config/truststore.pin

    If you’re running dsconfig interactively, go to Trust Manager Provider > View and edit an existing Trust Manager Provider > JKS (or the type of certificate you’re working with) and set enabled to true. Select finish to save your changes.

  4. Configure the HTTPS Connection Handler. If not already created, this command creates and enables the connection handler, specifies the SCIM HTTP servlet extension, and sets the listen port to a port of your choice. For this example, use 8443. The command also specifies the type of key manager and trust manager providers and sets the log publisher to HTTP Detailed Access.

    Example:

    $ bin/dsconfig create-connection-handler \
  --handler-name "HTTPS Connection Handler" \
  --type http --set enabled:true \
  --set listen-port:8443 \
  --set use-ssl:true \
  --set http-servlet-extension:SCIM \
  --set "http-operation-log-publisher:HTTP Detailed Access" \
  --set key-manager-provider:JKS --set trust-manager-provider:JKS

    If you’re running dsconfig interactively, go to Connection Handler > View and edit an existing Connection Handler > HTTPS Connection Handler. Change the parameters to match your setup, and then select finish to save your changes.

    If the HTTPS Connection Handler already exists, use the following:

    Example:

    $ bin/dsconfig set-connection-handler-prop \
  --handler-name "HTTPS Connection Handler" \
  --add http-servlet-extension:SCIM

  5. Turn on the connection handler:

    Example:

    $ bin/dsconfig set-connection-handler-prop \
  --handler-name "HTTPS Connection Handler" \
  --add http-servlet-extension:SCIM

  6. Add access controls to allow access to LDAP controls used by the SCIM Servlet Extension. These controls are the Post-Read Request Control (1.3.6.1.1.13.2), Server-Side Sort Request Control (1.2.840.113556.1.4.473), Simple Paged Results Control (1.2.840.113556.1.4.319), and Virtual List View Request Control (2.16.840.1.113730.3.4.9). We recommend using the following command to add access control instructions, rather than its dsconfig interactive equivalent:

    Example:

    $ bin/dsconfig set-access-control-handler-prop \
  --add 'global-aci:(targetcontrol="1.3.6.1.1.13.2 || 1.2.840.113556.1.4.473 || 1.2.840.113556.1.4.319 || 2.16.840.1.113730.3.4.9")
    (version 3.0;acl "Authenticated access to controls used by the SCIM servlet
     extension"; allow (all) userdn="ldap:///all";)'

  7. Add access controls to allow read access to operational attributes used by the SCIM Servlet Extension. We recommend using the following non-interactive command to add access control instructions, rather than its dsconfig interactive equivalent:

    Example:

    $ bin/dsconfig set-access-control-handler-prop \
  --add 'global-aci:(targetattr="entryUUID || entryDN || ds-entry-unique-id ||
    createTimestamp || modifyTimestamp")
    (version 3.0;acl "Authenticated read access to operational attributes \
    used by the SCIM servlet extension"; allow (read,search,compare)
    userdn="ldap:///all";)'

  8. (Optional) The SCIM HTTP Connection Handler automatically uses a detailed HTTP log publisher, which is implemented in a proprietary format. If you need a standard W3C common log format publisher, enter the following command:

    Example:

    $ bin/dsconfig create-log-publisher \
  --publisher-name "HTTP Common Access" \
  --type common-log-file-http-operation --set enabled:true \
  --set log-file:logs/http-common-access \
  --set "rotation-policy:24 Hours Time Limit Rotation Policy" \
  --set "rotation-policy:Size Limit Rotation Policy" \
  --set "retention-policy:File Count Retention Policy" \
  --set "retention-policy:Free Disk Space Retention Policy"

$ bin/dsconfig set-connection-handler-prop \
  --handler-name "HTTPS Connection Handler" \
  --add "http-operation-log-publisher:HTTP Common Access"

    If you’re running dsconfig interactively, go to Log Publisher > Create a new Log Publisher > new Log Publisher created from scratch > File Based Access Log Publisher. Enter the parameters to match your setup, and then select finish to save your changes. Then go to Connection Handler > HTTPS Connection Handler and add HTTP Common Access to the http-operation-log-publisher property. Select finish to save your changes.

  9. (Optional) To support searching or filtering by DN using the Identity Access API, you can enable the entryDN virtual attribute:

    Example:

    $ bin/dsconfig set-virtual-attribute-prop --name entryDN --set enabled:true

    If you’re running dsconfig interactively, go to Virtual Attribute > View and edit an existing Virtual Attribute > Entry DN and set enabled to true. Select finish to save your changes.

  10. (Optional) To support pagination, create some VLV indexes:

    Example:

    $ bin/dsconfig create-local-db-vlv-index --backend-name userRoot \
  --index-name ascending-uid --set base-dn:dc=example,dc=com \
  --set scope:whole-subtree \
  --set "filter:(objectclass=inetorgperson)" \
  --set "sort-order:+uid"

$ bin/dsconfig create-local-db-vlv-index --backend-name userRoot \
  --index-name ascending-sn \
  --set base-dn:dc=example,dc=com \
  --set scope:whole-subtree \
  --set "filter:(objectclass=inetorgperson)" \
  --set "sort-order:+sn"

$ bin/rebuild-index --baseDN dc=example,dc=com \
  --index vlv.ascending-uid \
  --index vlv.ascending-sn

    If you’re running dsconfig interactively, go to Local DB VLV Index > Create a new Local DB VLV Index and then enter the properties needed for your setup. Select finish to save your changes. Repeat the previous step for additional indexes. To put the new VLV indexes into action, run the rebuild-index command and specify the index names.

Enabling resource versioning

About this task

Resource versioning is enabled by default in new installations. Upgraded servers that had SCIM enabled need additional configuration to enable resource versioning.

Steps

  1. Enable the ds-entry-checksum virtual attribute:

    Example:

    $ bin/dsconfig set-virtual-attribute-prop \
    --name ds-entry-checksum \
    --set enabled:true

  2. Remove any existing access controls required by SCIM for read access to operational attributes:

    Example:

    $ bin/dsconfig set-access-control-handler-prop \
    --remove 'global-aci:(targetattr="entryUUID || entryDN || ds-entry-unique-id || createTimestamp || ds-create-time || modifyTimestamp || ds-update-time")(version 3.0;acl "Authenticated read access to operational attributes used by the SCIM servlet extension"; allow (read,search,compare) userdn="ldap:///all"'

  3. Add new access controls required by SCIM for read access to operational attributes with the addition of the ds-entry-checksum:

    Example:

    $ bin/dsconfig set-access-control-handler-prop \
    --add  'global-aci:(targetattr="entryUUID || entryDN || ds-entry-unique-id || createTimestamp || ds-create-time || modifyTimestamp || ds-update-time || ds-entry-checksum")(version 3.0;acl "Authenticated read access to operational attributes used by the SCIM servlet extension"; allow (read,search,compare) userdn="ldap:///all"'

  4. Enable SCIM resource versioning using the entry checksum virtual attribute:

    Example:

    $ bin/dsconfig set-http-servlet-extension-prop \
    --extension-name SCIM \
    --set entity-tag-ldap-attribute:ds-entry-checksum

    Result:

    If enabled, the value of the ds-entry-checksum attribute is returned as the ETag header value when accessing the resource through SCIM, and is checked against the If-Match header when updating the resource. When accessing the resource through LDAP, use the ds-entry-checksum attribute instead.

Configuring the SCIM servlet extension using the batch script

About this task

The following example procedure assumes that you have set up your certificates, keystore, and truststore.

Steps

  1. Open the <server-root>/config/scim-config-ds.dsconfig script in a text editor.

  2. For the optional elements (W3C common log, filtering by DN, and VLV Indexes, remove the comment (#) symbol on the dsconfig commands. Save the file when finished editing.

  3. To enable the SCIM servlet extension, run the dsconfig batch file. Remember to include the bind parameters.

    Example:

    $ bin/dsconfig --batch-file config/scim-config-ds.dsconfig