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 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"
```
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 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