PingDirectory

Configure the SCIM 2.0 external server

The System for Cross-domain Identity Management (SCIM) 2.0 external server configuration object provides the information that the PingDataSync server needs to connect and authenticate to the SCIM 2.0 service.

First, you must create an HTTP authentication method that allows the PingDataSync server to authenticate to the SCIM 2.0 server to authorize requests. In most cases, this authentication is an OAuth 2.0 bearer token, and you will likely want to obtain that token using the client credentials grant type. This allows you to provide a client ID and client secret to the OAuth authorization server to obtain a bearer token.

In this case, the client secret is sensitive information, so the PingDataSync server uses a passphrase provider to access it, which allows it to be obtained from a variety of sources, like an optionally encrypted file, Amazon Secrets Manager, Azure Key Vault, a CyberArk Conjur instance, or a HashiCorp Vault instance. For example:

dsconfig create-passphrase-provider \
     --provider-name "SCIMv2 Client Secret" \
     --type file-based \
     --set enabled:true \
     --set password-file:config/scimv2-client-secret.txt

dsconfig create-http-authorization-method \
     --method-name "SCIMv2 Authorization Method" \
     --type client-credentials-bearer-token \
     --set enabled:true \
     --set oauth-server-token-endpoint-url:https://oauth.example.com/as/token \
     --set hostname-verification-method:strict \
     --set oauth-client-id:this-is-the-client-id \
     --set "oauth-client-secret-passphrase-provider:SCIMv2 Client Secret" \
     --set request-method:get \
     --set credentials-submission-method:basic-authorization \
     --set "maximum-token-lifetime:1 h"

The SCIM 2.0 external server configuration offers the following properties:

scim-service-url

The base URL to the SCIM 2.0 service to be used. This should not include any endpoint name because that will be appended through the endpoint mapping. This is required.

key-manager-provider

A key manager provider to use during SSL negotiation with the SCIM 2.0 server. This is optional, and it will likely only be used if the PingDataSync server needs to supply a client certificate to the SCIM 2.0 server.

ssl-cert-nickname

The nickname (alias) of the client certificate to present to the SCIM 2.0 server. This is only needed if a key-manager-provider is specified and only if the associated key store has multiple certificates that could be used.

trust-manager-provider

A trust manager provider to use to determine whether to trust the certificate chain presented by the SCIM 2.0 server during Secure Sockets Layer (SSL) negotiation. This is optional, and if you don’t specify it, then the PingDataSync server will rely primarily on the Java Virtual Machine (JVM)’s default set of trusted issuers. If the SCIM 2.0 server is using a certificate signed by one of those trusted issuers, then you can leave this property unset.

hostname-verification-method

Indicates whether the PingDataSync server should verify that the certificate presented by the SCIM 2.0 server is appropriate for the intended address. A value of strict, which is the default, indicates that the connection should only be established if the certificate has a subject alternative name extension with a value that matches the address provided in the scim-service-url property (or if the certificate does not have a subject alternative name extension, then it falls back to using the CN attribute of the certificate subject). A value of allow-all indicates that the PingDataSync server should not attempt to confirm that the certificate was issued for the intended server.

http-authorization-method

The HTTP authorization method that the PingDataSync server should use to authenticate to and authorize requests in the SCIM 2.0 server. This is required.

response-timeout

The maximum length of time that the PingDataSync server should wait for a response from the SCIM 2.0 server when issuing requests. If this is not specified, a default of 10 seconds is used.

client-reconnect-interval

The maximum length of time that a SCIM 2.0 client instance will be used before a new one is created, which might potentially include obtaining new credentials. If the client credentials grant HTTP authorization method is used and the OAuth authorization server specified an expiration time for the bearer token that it issued, then the actual reconnect interval is based on the lesser of the two values. If this is not specified, and if the HTTP authorization method does not indicate a maximum lifetime for its credentials, then the same SCIM 2.0 client instance is used indefinitely.

The server will automatically try to refresh the credentials if the SCIM 2.0 service returns a 401 (unauthorized) error in response to any request.

For example, you can use the following change to configure a SCIM 2.0 external server:

dsconfig create-external-server \
     --server-name "SCIMv2 Server" \
     --type scim2 \
     --set scim-service-url:https://scim2.example.com/scim/v2 \
     --set "http-authorization-method:SCIMv2 Authorization Method"