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
-
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. -
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
-
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
-
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
-
Turn on the connection handler.
Example:
$ bin/dsconfig set-connection-handler-prop \ --handler-name "HTTPS Connection Handler" \ --add http-servlet-extension:SCIM
-
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";)'
-
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";)'
-
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 thehttp-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"
-
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
-
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 therebuild-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
-
Enable the
ds-entry-checksum
virtual attribute.Example:
$ bin/dsconfig set-virtual-attribute-prop \ --name ds-entry-checksum \ --set enabled:true
-
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"'
-
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"'
-
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 theETag
header value when accessing the resource through SCIM, and is checked against theIf-Match
header when updating the resource. When accessing the resource through LDAP, use theds-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
-
Open the
<server-root>/config/scim-config-ds.dsconfig
script in a text editor. -
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. -
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: