Configuring SCIM 2.0 on your server

Review the following topics to configure SCIM 2.0 on your server instance.

There is a known issue with dot notation support for SCIM 2.0 sub-attributes.

Creating your own SCIM 2.0 application

The System for Cross-domain Identity Management (SCIM) is an open initiative designed to make moving identity data to, from, and between clouds standard, secure, fast, and easy. The SCIM SDK is a pre-packaged collection of libraries and extensible classes that provides developers with a simple, concrete API to interact with a SCIM service provider.

The SCIM 2 SDK is available for download at https://github.com/pingidentity/scim2.

Authentication requirements for SCIM 2.0 requests

All SCIM requests on a PingDirectory server must use OAuth 2.0 bearer token authentication. Bearer tokens are evaluated using the SCIM 2 servlet extension’s configured Access Token Validators. Basic authentication is not supported.

In addition to requiring bearer tokens, the server will not process any SCIM requests unless it has at least one encryption-settings definition in its encryption-settings database. You can create the necessary definition(s) with the encryption-settings command-line tool. See Encrypting sensitive data for more information. NOTE: Encryption settings need to be defined on the Proxy and all backend PD servers, and the encryption settings should match.

Defining permissions for SCIM 2.0 requests

Whether or not a SCIM request is executed on a server depends primarily on both the configured Access Control Instructions (ACIs) in the server and the scopes which are present in the provided OAuth bearer token used to authenticate the request.

SCIM 2.0 requests can be authorized in one of the two following ways:

By default, requests are processed using the cn=SCIM2 Servlet,cn=Root DNs,cn=config service account. Whether a requested operation is allowed depends on the ACIs that apply to the operation, which can include both the rights granted to that service account and any rights granted to scopes contained in the OAuth bearer token using the oauthscope ACI bind rule.
If user mapping is enabled, the subject of the OAuth bearer token is mapped to an account in the server. In this case, whether a requested operation is allowed depends on the ACIs that apply to the mapped user for the requested operation. You can also use the oauthscope bind rule to grant rights based on scopes in the presented token.

Because of implementation details, access to the objectclass operational LDAP attribute is necessary for SCIM requests to properly execute. However, you shouldn’t give the service account access to objectclass on a global level. Instead, add the ACI granting objectclass access to the LDAP subtree you want to expose to clients. See Configuring permissions for SCIM 2.0 operations for an example of this.

ACIs that don’t use the oauthscope bind rule can still apply to requested operations. For example, an ACI that grants unconditional read access to any authenticated LDAP user will also grant unconditional read access to SCIM requests regardless of the provided OAuth scopes because the requests are processed through the service account.

Enabling user mapping for SCIM 2.0 operations

Access token validator identity mapping ties a local user account to an operation performed in the SCIM 2.0 servlet in the PingDirectory server.

About this task

This topic applies only to the PingDirectory server.

The default configuration for the PingDirectory server for the SCIM 2.0 servlet doesn’t require an access token to map to a local user, and operations are recorded in the logs as the SCIM2 Servlet user. For more detailed logging and auditing, enable the map-access-tokens-to-local-users property to require access tokens to map to a local user.

The users that are being mapped to the access tokens must have the necessary access control rights required to perform the operations that the SCIM 2.0 servlet will invoke on their behalf.

You should update the authorization server to issue tokens that include the scim2 scope alongside any other scopes you need for access control purposes.

The map-access-tokens-to-local-users property is an optional configuration with the three settings shown in the following table.

Setting Definition

Setting	Definition
`Disabled` (default)	The server doesn’t attempt to map SCIM 2.0 access tokens to local users and operations are processed under the authority of the `SCIM2 Servlet` user.
`Optional`	The server attempts to map SCIM 2.0 access tokens to local users and, if successful, the operations are processed under the authority of that user. The distinguished name (DN) of the mapped user appears in the access logs. If unsuccessful, the server falls back to the default behavior.
`Required`	The server must map the SCIM 2.0 access token to one local user or the operation is rejected.

Disabled (default)

The server doesn’t attempt to map SCIM 2.0 access tokens to local users and operations are processed under the authority of the SCIM2 Servlet user.

Optional

The server attempts to map SCIM 2.0 access tokens to local users and, if successful, the operations are processed under the authority of that user. The distinguished name (DN) of the mapped user appears in the access logs. If unsuccessful, the server falls back to the default behavior.

Required

The server must map the SCIM 2.0 access token to one local user or the operation is rejected.

To set the map-access-tokens-to-local-users property:

Steps

Run dsconfig with the set-http-servlet-extension-prop option.

Choose from:

To set the property to required, run the following command.

dsconfig set-http-servlet-extension-prop \
  --extension-name SCIM2 \
  --set map-access-tokens-to-local-users:required

To set property to optional, run the following command.

dsconfig set-http-servlet-extension-prop \
  --extension-name SCIM2 \
  --set map-access-tokens-to-local-users:optional

To reset the property to the default setting, disabled, run the following command.

dsconfig set-http-servlet-extension-prop \
  --extension-name SCIM2 \
  --set map-access-tokens-to-local-users:disabled

SCIM 2.0 components

Unlike the SCIM 1.1 servlet extension, the SCIM 2.0 system is configured through the Administrative Console or with the dsconfig command-line tool. The SCIM 2.0 system consists of the following components:

SCIM resource types
SCIM schemas
- SCIM attributes
- SCIM sub-attributes
SCIM attribute mappings (mapping resource types only)
Correlated LDAP Data Views

A SCIM resource type defines a class of resources, such as users or devices. Every SCIM resource type features at least one SCIM schema, which defines the attributes that are available to each resource. If enabled for use, a SCIM resource type must also have a designated LDAP structural objectclass as well as an associated base DN.

The two types of SCIM resource types, mapping and pass-through, differ based on the definitions of the SCIM schema the resource types use.

An LDAP mapping SCIM resource type requires an explicitly defined SCIM schema with explicitly defined mappings of SCIM attributes to LDAP attributes. Use a mapping SCIM resource type to exercise detailed control over the SCIM schema and its attributes and mappings.
An LDAP pass-through SCIM resource type, by contrast, does not use an explicitly defined SCIM schema. Instead, an implicit schema is generated dynamically, based on the underlying LDAP schema. Use a pass-through SCIM resource type when you need to get started quickly.

A SCIM schema defines a collection of SCIM attributes, grouped under an identifier called a schema URN. Each SCIM resource type possesses a single core schema and can feature schema extensions, which act as secondary attribute groupings that the schema URN namespaces. SCIM Schemas are defined independently of SCIM resource types, and multiple SCIM resource types can use a single SCIM schema as a core schema or schema extension.

A SCIM attribute defines an attribute that is available under a SCIM schema. The configuration for a SCIM attribute defines its data type, regardless of whether it is required, single-valued, or multi-valued. When a SCIM attribute consists of SCIM sub-attributes, it is defined as a complex attribute.

A SCIM attribute mapping defines the manner in which a SCIM resource type maps the attributes in its SCIM schemas to native LDAP attributes of the PingDirectory server.

A Correlated LDAP Data View allows a single SCIM resource that consists of attributes that are retrieved from multiple LDAP entries (see Correlated LDAP data views).

Correlated LDAP data views

Correlated LDAP data views can be attached to a SCIM resource type to allow that resource type to use attributes from other LDAP entries. A SCIM resource type can have multiple data views configured.

Correlated LDAP data views share many configuration settings with SCIM resource types. The following exceptions are below:

primary-correlation-attribute: The LDAP attribute from the SCIM Resource Type whose value will be used to match entries in the data view. This property must be defined.
secondary-correlation-attribute: The LDAP attribute from the data view whose value will be matched with the primary-correlation-attribute. This property must be defined.
ldap-correlation-attribute-pair: Optional correlation attribute pairs. If these are configured, entries between the SCIM resource type and the correlated LDAP data view must also have matching values for the specified attributes for them to be returned together.

A correlated LDAP Data View cannot provide attributes from more than one LDAP entry at a time. If there are multiple LDAP entries with secondary-correlation-attribute values that match the primary-correlation-attribute from the SCIM resource type’s entry, an error will be thrown.

Correlated LDAP data views share many configuration settings with SCIM resource types. The following exceptions are below:

If the correlated LDAP data view is attached to a pass-through SCIM resource type, its attributes will appear as schema extensions, similar to the following:

{
      ...
	"uid": [
    	"user.8"
	],
	"entryDN": "uid=user.8,ou=people,dc=example,dc=com",
	"urn:pingidentity:schemas:correlated:Document": {
    	    "documentIdentifier": [
        	    "user.8"
    	    ],
    	    "description": [
        	    "This is the description for the document user.8 under ou=Documents,dc=example,dc=com."
    	    ],
    	    ...
	},
	...
	"schemas": [
    	"urn:pingidentity:schemas:correlated:Document",
    	"urn:pingidentity:schemas:passthrough:PassthroughUsers"
	]
}

If the correlated LDAP data view is attached to a Mapping SCIM resource type, its attributes must be mapped to a schema used by the SCIM resource type. This is done through the correlated-ldap-data-view property in a SCIM attribute mapping.

Configuring an LDAP Mapping SCIM 2.0 resource type

About this task

This example shows how to add a simple mapping SCIM 2.0 resource type to a PingDirectory server, backed by the inetOrgPerson LDAP objectclass. This example assumes that the server has been configured using the default settings, meaning that sample data has been imported into the server and that data encryption has been set up.

Steps

Create the SCIM schema that the resource type will use:

dsconfig create-scim-schema \
--schema-name urn:pingidentity:schemas:User:1.0 \
--set display-name:User

Under this schema, add the following SCIM attributes.

dsconfig create-scim-attribute \
--schema-name urn:pingidentity:schemas:User:1.0 \
--attribute-name displayName
dsconfig create-scim-attribute \
--schema-name urn:pingidentity:schemas:User:1.0 \
--attribute-name name \
--set type:complex
dsconfig create-scim-subattribute \
--schema-name urn:pingidentity:schemas:User:1.0 \
--attribute-name name \
--subattribute-name familyName
dsconfig create-scim-subattribute \
--schema-name urn:pingidentity:schemas:User:1.0 \
--attribute-name name \
--subattribute-name formatted
dsconfig create-scim-attribute \
--schema-name urn:pingidentity:schemas:User:1.0 \
--attribute-name userName

Create the LDAP mapping SCIM resource type on the PingDirectory server.

dsconfig create-scim-resource-type \
--type-name Users \
--type ldap-mapping \
--set enabled:true \
--set endpoint:Users \
--set structural-ldap-objectclass:inetOrgPerson \
--set include-base-dn:ou=People,dc=example,dc=com \
--set lookthrough-limit:500 \
--set core-schema:urn:pingidentity:schemas:User:1.0

Run the following commands to create the SCIM attribute mappings.

dsconfig create-scim-attribute-mapping \
--type-name Users \
--mapping-name displayName \
--set scim-resource-type-attribute:displayName \
--set ldap-attribute:displayName
dsconfig create-scim-attribute-mapping \
--type-name Users \
--mapping-name name.formatted \
--set scim-resource-type-attribute:name.formatted \
--set ldap-attribute:cn \
--set searchable:true
dsconfig create-scim-attribute-mapping \
--type-name Users \
--mapping-name name.familyName \
--set scim-resource-type-attribute:name.familyName \
--set ldap-attribute:sn \
--set searchable:true
dsconfig create-scim-attribute-mapping \
--type-name Users \
--mapping-name userName \
--set scim-resource-type-attribute:userName \
--set ldap-attribute:uid \
--set searchable:true

Configure the SCIM2 HTTP Servlet Extension to use a Mock Access Token Validator. Note that Mock Access Token Validators should never be used in production environments or with sensitive data.

dsconfig create-access-token-validator \
--validator-name "SCIM2 Mock Validator" \
--type mock \
--set enabled:true
dsconfig set-http-servlet-extension-prop \
--extension-name SCIM2 \
--set "access-token-validator:SCIM2 Mock Validator"

Send the following request to the SCIM /ResourceTypes endpoint to confirm that the new resource type has been added.
```
curl -k -X GET \
https://localhost:8443/scim/v2/ResourceTypes \
-H 'Authorization: Bearer {"active":true}'
```

The following JSON object should appear in the response in the “Resources” array:

{
...
"Resources": [{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
"id":"Users",
"name":"Users",
"endpoint":"Users",
"schema":"urn:pingidentity:schemas:Users:1.0",
"meta":{
"resourceType":"ResourceType",
"location":"https://localhost:8443/scim/v2/ResourceTypes/Users"
}
}]
...
}

Configuring a correlated LDAP data view

About this task

The following example shows how to add a correlated LDAP data view to a LDAP mapping SCIM resource type on a PingDirectory server. The SCIM resource type will be a user, and the correlated LDAP data view will allow access to a document that matches their user ID.

In this example, a new PingDirectory server is set up using custom sample data. When configuring the correlation, administrators should use attributes that are inherently either immutable or non-volatile, such as uid or entryUUID. This prevents errors produced by a conflict between the values of primary and secondary correlation attributes.

Administrators can make the correlation SCIM attributes immutable by setting the --set mutability:read-only property when defining an attribute in the SCIM schema configuration. That way, SCIM requests cannot modify the values of those attributes.

Steps

Copy the following text into the server root directory and save it as entries.ldif.template:

define suffix=dc=example,dc=com
define maildomain=example.com
define numusers=101

branch: [suffix]
subordinateTemplate: admin:1
aci: (targetattr="*")(version 3.0; acl "Grant full access for the scim2allaccess OAuth 2 scope"; allow (all) oauthscope="scim2allaccess";)

branch: ou=People,[suffix]
subordinateTemplate: person:[numusers]

branch: ou=Documents,[suffix]
subordinateTemplate: document:[numusers]

template: admin
rdnAttr: uid
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
uid: admin
givenName: Admin
sn: User
cn: Admin User
userPassword: password

template: person
rdnAttr: uid
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
employeeNumber: <sequential:0>
uid: user.{employeeNumber}
sn: {uid}
cn: {uid}
userPassword: password

template: document
rdnAttr: documentIdentifier
objectClass: top
objectClass: document
documentIdentifier: user.<sequential:0>
description: This is the description for the document {documentIdentifier} under ou=Documents,dc=example,dc=com.

Run the following command:

$ bin/make-ldif --templateFile entries.ldif.template --ldifFile entries.ldif

Run setup for the PingDirectory server.

Make sure to import the created entries.ldif file and set up encryption settings. After this is done, set up the SCIM resource type and the Correlated LDAP Data View.

Run the following command to define the SCIM schema:

"dsconfig create-scim-schema --schema-name urn:example:Users \
  --set "description:Users schema" --set display-name:Users
dsconfig create-scim-attribute --schema-name urn:example:Users \
  --attribute-name email --set required:true --set multi-valued:true
dsconfig create-scim-attribute --schema-name urn:example:Users \
  --attribute-name uid --set required:true --set mutability:read-only
dsconfig create-scim-attribute --schema-name urn:example:Users \
  --attribute-name documentId
dsconfig create-scim-attribute --schema-name urn:example:Users \
  --attribute-name documentDescription"

Run the following command to create the SCIM resource type:

dsconfig create-scim-resource-type \
  --type-name Users \
  --type ldap-mapping \
  --set core-schema:urn:example:Users \
  --set enabled:true \
  --set endpoint:Users \
  --set structural-ldap-objectclass:inetOrgPerson \
  --set include-base-dn:ou=people,dc=example,dc=com \
  --set create-dn-pattern:entryUUID=generated,ou=people,dc=example,dc=com

Run the following command to create the Correlated LDAP Data View:

dsconfig create-correlated-ldap-data-view \
  --type-name Users \
  --view-name Document \
  --set structural-ldap-objectclass:document \
  --set include-base-dn:ou=documents,dc=example,dc=com \
  --set create-dn-pattern:entryUUID=generated,ou=documents,dc=example,dc=com \
  --set primary-correlation-attribute:uid \
  --set secondary-correlation-attribute:documentIdentifier

Run the following command to create the attribute mappings for the SCIM resource type attributes.

Note that the correlated-ldap-data-view property is not set.

# The uid attribute, provided by the base SCIM Resource Type
dsconfig create-scim-attribute-mapping --type-name Users \
  --mapping-name uid \
  --set scim-resource-type-attribute:uid --set ldap-attribute:uid \
  --set writable:false --set searchable:true

# The email attribute, provided by the base SCIM Resource Type
dsconfig create-scim-attribute-mapping --type-name Users \
  --mapping-name email \
  --set scim-resource-type-attribute:email --set ldap-attribute:mail \
  --set searchable:true

Run the following command to create the DocumentId attribute mapping for the correlated LDAP data view attributes.

The only meaningful difference between mappings for SCIM resource type attributes and correlated LDAP data view attributes is the value of the correlated-ldap-data-view property.

# The documentId attribute
dsconfig create-scim-attribute-mapping --type-name Users \
  --mapping-name document.id \
  --set correlated-ldap-data-view:Document \
  --set scim-resource-type-attribute:documentId --set ldap-attribute:documentIdentifier

# The documentDescription attribute
dsconfig create-scim-attribute-mapping --type-name Users \
  --mapping-name description \
  --set correlated-ldap-data-view:Document \
  --set scim-resource-type-attribute:documentDescription \
  --set ldap-attribute:description

Run the following command to send a SCIM request:

curl -k -X GET \
  https://localhost:8443/scim/v2/Users \
  -H 'Authorization: Bearer {"active":true, "scope":"scim2allaccess"}'

The response should look similar to the following. Notice that 'uid' and 'documentId' have the same value, as they are in a correlation attribute pair.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 101,
    "Resources": [
        {
            "uid": "user.8",
            "id": "3715c022-1f34-36d9-bebc-7e74912106ec",
            "documentDescription": "This is the description \
            for the document user.8 under ou=Documents,dc=example,dc=com.,
            "documentId": "user.8",
            "meta": {
                "resourceType": "Users",
                "location": "https://localhost:8443/scim/v2/Users/3715c022-1f34-36d9-bebc-7e74912106ec"
            },
            "schemas": [
                "urn:example:Users"
            ]
        },
    ...
}

Configuring permissions for SCIM 2.0 operations

About this task

This example shows how to correctly configure permissions so POST requests with the "userAdd" scope will succeed. This example assumes that you have set up an LDAP mapping SCIM 2.0 Resource Type for the inetOrgPerson objectclass (see Configuring an LDAP Mapping SCIM 2.0 resource type.

Steps

If the SCIM Resource Type being targeted already has a value for the create-dn-pattern property, skip to step 2. Otherwise, the following dsconfig command can be used:
```
dsconfig set-scim-resource-type-prop \
  --type-name Users \
  --set create-dn-pattern:entryUUID=generated,ou=People,dc=example,dc=com
```

Send the following request to the SCIM /Users endpoint:

curl -k -X POST \
  https://localhost:8443/scim/v2/Users/ \
  -H 'Authorization: Bearer {"active":true}' \
  -H 'Content-type: application/json' \
  --data '{"username":"user.test", "name":{"formatted":"Test",
"familyName":"User"}, "schemas":["urn:pingidentity:schemas:User:1.0"]}'

The response from the server should have a status of 403 and contain a correlation ID, similar to the following:

{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status":"403",
  "detail":"Request failed:
correlationID='faa707b3-5d48-42e6-9e78-2c8dbb1e2cac'"
}

This is the expected response since this SCIM request does not have the permission needed to write to an entry. You can find instructions on viewing the full server error message in Troubleshoot the SCIM 2.0 servlet extension.

An ACI should now be added to the ou=People,dc=example,dc=com subtree. This will grant permission to add entries to this subtree as long as the SCIM request includes the userAdd scope. This can be done by running the following ldapmodify command. Note that this ACI does not grant write access to attributes, which means modify operations will fail. You can find more information about configuring ACIs in Overview of access control.
```
$ ldapmodify
dn:ou=People,dc=example,dc=com
changetype:modify
add:aci
aci:(version 3.0; acl "ACI for userAdd scope"; allow (add)
oauthscope="userAdd";)
```

Send the POST request to the SCIM / Users endpoint again, this time including the userAdd scope in the bearer token:

curl -k -X POST \
https://localhost:8443/scim/v2/Users \
-H 'Authorization: Bearer {"active":true, "scope":"userAdd"}' \
-H 'Content-type: application/json' \
--data '{"username":"user.test", "name":{"formatted":"Test",
"familyName":"User"}, "schemas":["urn:pingidentity:schemas:User:1.0"]}'

The response from the server should now contain the created SCIM resource, which should also contain values for the name and username attributes, similar to the following:

{
"name":{
"familyName":"User",
"formatted":"Test"
},
"username":"user.test",
"id":"6f9a89b8-e766-478c-9667-def049daf6bc",
"meta":{
"resourceType":"Users",
"location":"https://localhost:8443/scim/v2/Users/6f9a89b8-e766-478c-9667-def
049daf6bc"
},
"schemas":["urn:pingidentity:schemas:User:1.0"]
}

SCIM 2.0 searches

To prevent exhausting server resources, we recommend capping the total number of resources that are matched by a search. The configuration for each SCIM 2.0 resource type contains a lookthrough-limit property that defines this limit (the default lookthrough-limit value is 500).

If a search request exceeds the lookthrough limit, the client receives a 400 response with an error message similar to the following:

{
  "detail": "The search request matched too many results",
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "scimType": "tooMany",
  “status”: "400"
}

To prevent this error, you have these options:

The client must refine its search filter to return fewer matches.
Configure paged searches as explained in Using paged SCIM searches

Using paged SCIM searches

When searching large data sets, the results can be numerous and produce errors about a request matching too many results relative to the lookthrough limit. Paged searches avoid these errors and also reduce memory utilization.

About this task

The PingDirectory server does SCIM searches using LDAP requests. After you complete the steps below, PingDirectory creates LDAP requests that include request controls to sort and page the search results before returning the results.

If your SCIM searches result in an error because the request matched too many results, as discussed in SCIM 2.0 searches, you can avoid the error by using paged searches.

Complete the following steps for each search.

Steps

Decide your SCIM search.

To get paged results, your search must include at least one of these parameters: startIndex, count, or sortBy.

For example, your search might look like the following search.
```
https://<directory-hostname>:<directory-port>/scim/v2/Users/?filter=st eq "TX"&sortBy=sn&sortOrder=ascending
```
Here is the corresponding encoded version.
```
https://<directory-hostname>:<directory-port>/scim/v2/Users/?filter=st%20eq%20%22TX%22&sortBy=sn&sortOrder=ascending
```
On your PingDirectory server, collect some information to use later. Find the SCIM resource type, structural-ldap-objectclass, include-base-dn, and include-filter values by running this command.
```
$ dsconfig get-scim-resource-type-prop --type-name  <SCIM-resource-type-name>  \
--property structural-ldap-objectclass \
--property include-base-dn \
--property include-filter
```

On the PingDirectory server, complete the following steps.

Create a Virtual List View (VLV) index for your search.

Each SCIM search that you want to produce paged results must have its own VLV index.

Create this index using dsconfig create-local-db-vlv-index with the following options.

Option Description

Option	Description
`--index-name`	Names the index.
`--backend-name`	Specifies the name of the local database backend in which to place the index. The default database backend for PingDirectory is userRoot.
`--set base-dn`	Specifies the desired base dn. This value must match the value of the `include-base-dn` property that you found in the previous step.
`--set scope`	Is always `whole-subtree`.
`--set filter`	Specifies the filter. Specify `"(objectclass=<name-of-SCIM-resource-type-objectclass>)"` where `<name-of-SCIM-resource-type-objectclass>` is the name of the objectclass used by the SCIM resource type, which you found in the previous step. If the SCIM resource type has the `include-filter` property set, also specify that property value in the filter. For example, if the filter for the objectclass is `(objectclass=inetorgperson)` and the `include-filter` value is `(st=CA)`, specify the `--set filter` argument as `"(&(objectclass=inetorgperson)(st=CA))"`. Specify the LDAP attributes for all the components of your SCIM search filter. For example, if a mapping SCIM resource type maps the LDAP attribute `st` to the SCIM attribute `address.region` and the SCIM search filter requires that `address.region eq TX`, then this filter must include `(st = TX)` instead of `(address.region = TX)`.
`--set sort-order`	Specifies whether to sort ascending (+) or descending (-) and the LDAP attribute to sort by.If the SCIM search does not specify the `sortBy` parameter, specify the sort order as `+entryUUID`.

--index-name

Names the index.

--backend-name

Specifies the name of the local database backend in which to place the index.

The default database backend for PingDirectory is userRoot.

--set base-dn

Specifies the desired base dn. This value must match the value of the include-base-dn property that you found in the previous step.

--set scope

Is always whole-subtree.

--set filter

Specifies the filter.

Specify

"(objectclass=<name-of-SCIM-resource-type-objectclass>)"

where <name-of-SCIM-resource-type-objectclass> is the name of the objectclass used by the SCIM resource type, which you found in the previous step.

If the SCIM resource type has the include-filter property set, also specify that property value in the filter. For example, if the filter for the objectclass is (objectclass=inetorgperson) and the include-filter value is (st=CA), specify the --set filter argument as "(&(objectclass=inetorgperson)(st=CA))".

Specify the LDAP attributes for all the components of your SCIM search filter.

For example, if a mapping SCIM resource type maps the LDAP attribute st to the SCIM attribute address.region and the SCIM search filter requires that address.region eq TX, then this filter must include (st = TX) instead of (address.region = TX).

--set sort-order

Specifies whether to sort ascending (+) or descending (-) and the LDAP attribute to sort by.If the SCIM search does not specify the sortBy parameter, specify the sort order as +entryUUID.

Recall the original, decoded SCIM search, shown here.

https://<directory-hostname>:<directory-port>/scim/v2/Users/?filter=st eq "TX"&sortBy=sn&sortOrder=ascending

For example, to create a VLV index for that search, run the following command.

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

Stop the server. Rebuild the index. Start the server. Run the rebuild-index command specifying the baseDN and the name of the index.
```
$ rebuild-index --baseDN  <baseDN-value>  --index  <name-of-index>
```
For example, run these commands.
```
$ stop-server
$ rebuild-index --baseDN dc=example,dc=com --index vlv.sn
$ start-server
```

Run your SCIM search filter.

The search can include only the filter you specified with --set filter in the earlier step without the "(objectclass=<name-of-SCIM-resource-type-objectclass>)" portion.

In addition to the Virtual List View request control, the PingDirectory server adds a Server Side request control to the LDAP request. These request controls require certain parameters be set. To satisfy this requirement, the server uses the following parameters. If the client does not provide values for one of the parameters, the search uses the corresponding default value shown in the following table.

Parameter Default

Parameter	Default
startIndex	1
count	The value of the `lookthrough-limit` property of the SCIM resource type being searched. That default is 500.
sortBy	entryUUID With this default, the results appear unsorted.
sortOrder	ascending

startIndex

count

The value of the lookthrough-limit property of the SCIM resource type being searched. That default is 500.

sortBy

entryUUID

With this default, the results appear unsorted.

sortOrder

ascending

SCIM 2.0 PATCH operations

When using a PATCH request to modify a SCIM 2.0 resource that has one or more required SCIM 2.0 attributes, the requester must have permissions to read the values of these required attributes in addition to write permissions for the attributes being modified, even if the PATCH request does not alter said requirements.

For example, assume we want to modify an LDAP Mapping SCIM 2.0 resource type using the following schema definition, where uid and cn are mapped to their LDAP equivalents:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
  "id": "urn:test:schema:person",
  "attributes": [
    {
      "name": "uid",
      "type": "string",
      "multiValued": false,
      "required": true,
      "caseExact": false,
      "mutability": "readWrite",
      "returned": "default",
      "uniqueness": "none"
    },
    {
      "name": "cn",
      "type": "string",
      "multiValued": false,
      "required": false,
      "caseExact": false,
      "mutability": "readWrite",
      "returned": "default",
      "uniqueness": "none"
    }
  ],
  ...
        }

The following PATCH operation will fail if the SCIM 2 service account does not have access to both uid and cn:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations":[{
        "op":"add",
        "path":"cn",
         "value": "new cn value”
  }]
        }

Troubleshoot the SCIM 2.0 servlet extension

For security reasons, error messages specifically regarding LDAP systems are suppressed and do not appear in the HTTP responses from the server. Instead, you will see something similar to the following:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "400",
  "detail": "Request failed: correlationID='073eb1a8-8c51-48b3-83a0-380e1d4b4ab9'"
}

To view these messages, the Debug Trace Logger needs to be enabled. You can do this through the Administrative Console or with the following dsconfig command:

dsconfig set-log-publisher-prop --publisher-name "Debug Trace Logger" \
			--set enabled:true --add scim-message-type:error

After the Debug Trace Logger is enabled, the server will begin logging information related to SCIM operations to the file /logs/debug-trace , which will look somewhat like the following:

[09/Jun/2020:05:23:10.992 -0500] HTTP REQUEST requestID=3
correlationID="073eb1a8-8c51-48b3-83a0-380e1d4b4ab9" product="Ping Identity
Directory Server" instanceName="example" startupID="Xt9fJg==" threadID=173
from=[0:0:0:0:0:0:0:1]:53978 method=POST
url="https://0:0:0:0:0:0:0:1:9443/scim/v2/Users"

Note the presence of correlationID in these messages. By matching the id in the HTTP responses to the messages in the debug-trace log, the appropriate LDAP error message can be determined.

Disabling the SCIM 2.0 servlet extension

If you do not need to expose data through the SCIM 2 servlet, you can disable the SCIM 2.0 servlet extension by removing the SCIM2 HTTP servlet extension from the HTTPS connection handler, or from any other HTTP connection handler, and restart the handler:

dsconfig set-connection-handler-prop \
  --handler-name "HTTPS Connection Handler" \
  --remove http-servlet-extension:SCIM2 \
  --set enabled:false

dsconfig set-connection-handler-prop \
  --handler-name "HTTPS Connection Handler" \
  --set enabled:true