Set Up SCIM

Use your identity provider to synchronize the creation, deletion, and updating of users and user groups in Visier.

Note: Limited Availability This feature is in limited availability. If you are interested, please contact your Customer Success Manager.

Overview

SCIM, the System for Cross-Domain Identity Management, automates how identity information is exchanged between two entities, such as your identity provider (IdP) and Visier. SCIM replaces manual user management and user group management in Visier. By setting up SCIM with Visier, you can reduce the effort it takes to create, modify, and synchronize employee accounts between your IdP and users and user groups in Visier.

SCIM in Visier synchronizes users from your IdP to Visier. If you delete a user in your IdP, SCIM deletes that user in Visier. If you delete a user in Visier, nothing happens to the user in your IdP.

Visier maps the following SCIM User properties to users in Visier.

SCIM User property	Visier user field
id	User ID. Not configurable in Visier.
displayName	Name
active	Access (enabled or disabled)
emails[primary eq true].value	Email
userName	Username
employeeNumber	EmployeeID

Visier maps the following SCIM Group properties to user groups in Visier.

SCIM Group property	Visier user group field
id	User group ID. Not configurable in Visier.
displayName	Display name

Step One: Configure SCIM in Visier

Prerequisites: Create a service account user in Visier and assign the Visier Analytics User and Visier Cloud Administrator profiles to the user. This user executes all SCIM requests in Visier.

On the global navigation bar, click Settings > SCIM Configuration. In Configuration type, select one of:

SCIM API token: Generates a long-lived token that authenticates SCIM API requests from the service account. As a bearer token, there is a higher security risk because any attacker who gains access to your key has direct access to your SCIM API. You can think of SCIM API token as a physical key that can be stolen and used by anyone.
Direct trust SCIM: Accepts a public RSA key from your identity provider. Direct trust SCIM uses asymmetric cryptography (public/private keys) and is more secure because the IdP signs a short-lived token (JWT) with its private key. Visier then verifies the JWT with the public key. The private key is never transmitted. You can think of direct trust SCIM as a bank verifying your signature instead of you handing over a key.

The following table differentiates between the two SCIM methods.

SCIM API token	Direct trust SCIM
Static secret security	Asymmetric cryptography security
Simple set up	More complex set up
Best for quick tests and low security integrations	Best for security-conscious organizations
Use only if your IdP doesn't support JWT authentication	Recommended for production environments

SCIM API token

Click Generate SCIM Token.
In Display name, type the token's name.
In User, select the service account user you created as part of the SCIM prerequisites.
Click Generate Token.
Click Copy to copy the SCIM token to your clipboard.
Warning: This token is only displayed once. Copy it and store it in a secure location. You will not be able to retrieve it again.

Direct trust SCIM

Click Configure Direct Trust SCIM.
In the Public RSA Key box, paste the public key associated with your IdP JSON Web Token (JWT). The public key must be an RSA public key in PEM encoding as specified in RFC 7468 and supports the formats X.509 certificate, PKCS#1 RSAPublicKey, and X.509 SubjectPublicKeyInfo.
Example:
Copy
```
1
2
3
4
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAoAF1T6ZubDUlCK1EJ1XX
…
-----END PUBLIC KEY-----
```
In the Issuer box, type the entity ID of the IdP. The issuer uniquely identifies the identity provider within the solution and must match the iss claim in the OAuth 2.0 bearer token provided by the IdP.
In the Subject box, type the subject ID of the JWT. The subject is a unique identifier that must match the sub claim in the OAuth 2.0 bearer token provided by the IdP.
In SCIM service account, select the user you created as part of the SCIM prerequisites.
Click Save.

(Optional) Network subnets

To set the network subnets that are allowed to make SCIM requests to Visier:

In Network subnets, type the IP addresses using the Classless Inter-Domain Routing (CIDR) format: xxx.xxx.xxx.xxx/xx.
When finished, click Save.

Step Two: Configure SCIM in your identity provider

This section describes the generic steps to set up SCIM with an IdP. Your provider may have similar but different configuration options.

In your identity provider, set the SCIM base URL to https://{vanity_name}.visier.com/hr/scim/v2.
Tip:
To find your vanity name:
1. In Visier, in the global workspace, click Settings > Single Sign-On.
2. Under Single Sign-On, find your service provider endpoint; for example, https://jupiter.visier.com/VServer/auth. In this example, jupiter is the vanity name.
Configure one or more of the following SCIM authentication options. Your IdP may only require a subset of the configuration options.
- Authentication method: HTTP header
- HTTP header: Authorization
- HTTP authorization type: Bearer
- Token type: OAuth 2.0 JWT
- Token: One of:
  - If using direct trust SCIM, the token must be signed by the public RSA key you set in Step One: Configure SCIM in Visier.
  - If using SCIM API token, the token is the API token generated in Step One: Configure SCIM in Visier.

Step Three: Make SCIM requests

Define the following headers in your SCIM requests to Visier:

Accept: application/scim+json
Content-Type: application/scim+json

The JWT must be signed using the signing algorithm RS256 and provided in the request with the HTTP Authorization header, as shown in the following code snippet example.

Example:

Copy

1
Authorization: Bearer mF_9.B5f-4.1JqM

Additionally, Visier validates the following JWT claims:

Algorithm (alg): Must be RS256.
Issuer (iss): Must match the value set in Step One: Configure SCIM in Visier.
Subject (sub): Must match the value set in Step One: Configure SCIM in Visier.
Issued at (iat): Must not be in the distant future when received by Visier; for example, you can set your iat to the current time plus 10 seconds.
Expiry (exp): Must not be expired when received by Visier; for example, you can set your exp to the current time plus 10 seconds.

Troubleshooting

The following table describes the possible errors and their solutions when making SCIM requests.

HTTP status code	Description	Solutions
400	Bad Request. The SCIM request may have invalid parameters, an unaccepted value, a missing request body, or a malformed request body.	Check the SCIM request parameters and body.
401	Forbidden. The SCIM request has invalid credentials.	Use the header Authorization: Bearer {scim_token} where {scim_token} is the OAuth 2.0 bearer token you configured in Step Two: Configure SCIM in your identity provider.
404	Not Found. The API route may not exist or the id does not exist.	Check the API route or the id (if defined) in the SCIM request. Refer to the base URL in Step Two: Configure SCIM in your identity provider.
406	Not Acceptable. The media type or content type is incorrect.	Check the Accept and Content-Type headers in the SCIM request. For more information, see Step Three: Make SCIM requests.
500	Internal Server Error.	An error occurred with Visier's servers. Try again later or contact Visier Technical Support.

For all other issues, please contact Visier Technical Support.

In this section