SCIM

A SCIM datasource consumes the web-based API of a SCIM server. The SCIM datasource can be setup to verify credentials, but it is also possible to use it for account management.

To access the SCIM server, the connection settings that specify hostname, port and context must be configured, as well as the HTTP-client that is configured with the appropriate server- and client certificates, when needed.

The SCIM data-sources supports SCIM version 1.1 and 2.0.

Note

It is recommended to use SCIM 2.0 when possible, it contains a richer feature set for account and credential management.

SCIM 1.1

SCIM 1.1 support account retrieval and credential verification. It also support account creation and updates, but is limited to the PUT operation, which means that any update of the account means a full retrieval of the account, and then a PUT operation to set it back. If the backend fails to return all values this may cause inconsistencies in the backend data.

Special care should be taken with the password, since it should never be returned on a GET, it must not be overwritten if not set during PUT.

The SCIM 1.1 data source is configured by creating an http client and adding it to the scim configuration.

SCIM 1.1 only support filter queries to be sent via GET. This is inappropriate when queying for a user and password to match. Therefore the SCIM 1.1 client in Curity support the credential query to be executed as a SCIM 2.0 search query using POST. If the backend can support this it is recommended to enable that setting to avoid the risk of password being caught by proxies.

See the developer guide for details on how the scim 1.1 data source operates.

Configuration

Create an http client that can connect to your SCIM backend.

Listing 53 SCIM 1.1 data-source example configuration
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<data-source>
    <id>WebserviceScim</id>
    <scim xmlns="https://curity.se/ns/conf/data-access/scim">
      <hostname>some.scim.server.com</hostname>
      <port>443</port>
      <context>/basepath/scim/v1</context>
      <http-client>httpClient</http-client>
      <use-scim-2-search-for-credential-validation>true</use-scim-2-search-for-credential-validation>
    </scim>
  </data-source>

SCIM 2.0

SCIM 2.0 is a protocol for CRUD operations of users and other resources. It consists of two parts, the protocol for the CRUD operations and a schema for defining a resource. They are defined in RFC 7643 and RFC 7644. Curity Identity Server can use the User endpoint of SCIM 2.0 to provide credential management and as a source of attributes.

To use a SCIM 2.0 web service, web-service-settings needs to be configured. This is where you set things like hostname context, tls-settings and such.

See Http Clients for more details.

Credential Data Access

When using a SCIM 2.0 data source to verify credential using a credential manager, Curity Identity Server use a POST request to the /Users/.search endpoint to find the user account and verify the credentials. The filter can be configured by setting verify-password-filter, the default is userName eq ":username" and password eq ":password" and active eq true. As you can see, the default filter searches for a user with matching username and password, and with the active flag set. If this is not sufficient, the filter string can be changed. To read more about filters, see SCIM 2.0 Filtering.

Attribute Data Access

When using the SCIM 2.0 data source to append attributes or with an account manager, there are multiple filters to set to customize the search queries.

scim-attribute-to-fetch is a specific list of attribute names to fetch from the server. All other attributes will be excluded, except the ones marked as return:always in RFC 7643.

scim-excluded-attribute-to-fetch is a list of attributes that will be excluded from the result.

To configure the way Curity Identity Server finds the user account, the search-filter can be configured. The default value is userName eq :username. As an example, you can configure the filter to be userName eq :username or email.value eq :username if your not sure if the username in session is the username or the email address of the user.

PATCH support

Curity Identity Server supports using the HTTP PATCH method to update resources. This is an optional method, and not all servers support it. For that reason, Curity Identity Server queries the /ServiceProviderConfig endpoint of the server to find out if PATCH is supported. This query happens on each reconfiguration. If you are certain of the capabilities of your server, you can disable this query by setting supports-http-patch to true or false.

If PATCH is not supported by the server, Curity Identity Server needs to make two request for an update. One GET to get the full current account, and one PUT to replace the account with the updated information.

Example Configuration

Listing 54 A SCIM 2.0 service that runs on localhost with the Users endpoint on /scim/Users, it requires a token, and with custom filters
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
  <data-source>
  <id>Scim2Webservice</id>
  <scim2 xmlns="https://curity.se/ns/conf/data-access/scim2">
      <hostname>localhost</hostname>
      <port>8443</port>
      <context>/scim</context>
      <http-client>oauthClient</http-client>
      <account>
      <verify-password-filter>userName eq ":username" and password eq ":password"</verify-password-filter>
      <search-filter-mail>emails.value eq ":email"</search-filter-mail>
      <search-filter-phone>phones.value eq ":phone"</search-filter-phone>
      </account>
      <attributes>
      <search-filter>userName eq ":username"</search-filter>
      </attributes>
  </scim2>
  </data-source>
  …
  <client>
  <id>oauthClient</id>
  <scheme>https</scheme>
  <oauth-credentials>
      <client-id>test_cc_1</client-id>
      <client-secret>Password1</client-secret>
      <scope>read</scope>
      <token-endpoint>https://localhost:8443/dev/oauth/token</token-endpoint>
      <token-endpoint-tls>
      <use-truststore>true</use-truststore>
      </token-endpoint-tls>
  </oauth-credentials>
  <tls>
      <use-truststore>true</use-truststore>
  </tls>
  </client>
Listing 55 SCIM 2.0 data-source for authentication, that allows the user to enter either username or email
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
  <data-source>
  <id>Scim2Webservice</id>
  <scim2 xmlns="https://curity.se/ns/conf/data-access/scim2">
      <hostname>localhost</hostname>
      <port>8443</port>
      <context>/scim</context>
      <http-client>oauthClient</http-client>
      <account>
      <verify-password-filter>(userName eq ":username" or emails eq ":username") and password eq ":password" and active eq true</verify-password-filter>
      </account>
  </scim2>
  </data-source>