PingDirectory

Configuring the SCIM 1.1 servlet extension

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, enable 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 have not been configured. The example also shows the dsconfig non-interactive commands. You can easily use the dsconfig interactive commands, which uses a menu-driven interface. If you use the dsconfig interactive, you must change to the Standard or Advanced object menu to access many of these configuration settings.

Steps

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

  2. Enable the key manager provider. The key manager provider accesses the certificate during the SSL handshaking process. If running dsconfig interactive, open the main menu, select "Key Manager Provider" → "View and edit an existing Key Manager Provider" → "JKS" (or the type of certificate you are working with) → "enabled" and then set the value to "true". Click "finish" to save the setting.

    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

  3. Enable the trust manager provider. The trust manager provider determines if a presented certificate can be trusted. If running dsconfig interactive, open the main menu, select "Trust Manager Provider" → "View and edit an existing Trust Manager Provider" → "JKS" (or the type of certificate you are working with) → "enabled" and then set the value to "true". Click "finish" to save the setting.

    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

  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, in 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." If running dsconfig interactive, open the main menu, select "Connection Handler" → "View and edit an existing Connection Handler" → "HTTPS Connection Handler". Change the parameters to match your setup, and then, click "finish" to save the setting.

    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 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. If running dsconfig interactive, open the main menu, select "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, click "finish" to save the setting. Go back to the main menu, select "Connection Handler" → "HTTPS Connection Handler", and then add "HTTP Common Access" to the http-operation-log-publisher property. Click "finish" to save the setting.

    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"

  9. Optional. To support searching or filtering by DN using the Identity Access API, you can enable the entryDN virtual attribute. If running dsconfig interactive, open the main menu, select "Virtual Attribute" → "View and edit an existing Virtual Attribute" → "Entry DN", and then change the enabled property to "true". Click "finish" to save the setting.

    Example:

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

  10. Optional. To support pagination, create some Virtual List View indexes. If running dsconfig interactive, open the main menu, select "Local DB VLV Index" → "Create a new Local DB VLV Index" and then enter the properties needed for your setup. Click "finish" to save the setting. Repeat again for the "ascending-sn" index. Then, run the rebuild-index command to let the VLV Indexes take effect.

    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

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

    Result: