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 theoauthscope
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 |
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 |
The map-access-tokens-to-local-users
property is an optional configuration with the three settings shown in the following table.
Setting | Definition |
---|---|
|
The server doesn’t attempt to map SCIM 2.0 access tokens to local users and operations are processed under the authority of the |
|
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. |
|
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 theset-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 |
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 followingdsconfig
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. See Troubleshoot the SCIM 2.0 servlet extension for instructions on viewing the full server error message.
-
An ACI should now be added to the
ou=People,dc=example,dc=com
subtree. Thist will grant permission to add entries to the said subtree as long as the SCIM request includes the ‘userAdd’ scope. This can be done by running the followingldapmodify
command. Note that this ACI does not grant write access to attributes, which means modify operations will fail. See Overview of access control for more information on configuring ACIs.$ 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
, andinclude-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 --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 theinclude-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 attributeaddress.region
and the SCIM search filter requires thataddress.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 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
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