This implementation guide is designed to guide you through the setup and configuration of a SCIM implementation. A large portion of the configuration must be completed in the client’s IDP (identity provider).

Configuration

Step #1: Prepare the account

1. Toggle on SCIM in the Integrations section of Client Setup.
2. Save the page.
3. Navigate to Roles and Permissions.
4. When the page opens, open the Roles and Permissions section from the left panel.
5. Click Add New Employee Role to create a new user role that can be used in testing the SCIM integration. 
6. Enter in a SCIM name identifier to reference the purpose of this user and then select Company Admin as the Legacy Employee Role.
7. Click Create Role.
8. The role permissions will then open. Grant the user access to Company/Account Admin permissions as well as toggling on the API Access permission at the top of the role and granting full access to the SCIM permission.
   • Note: If a client has multiple accounts, and they need to create duplicate users in each, you will need to enable full access to the Allow to Merge Employees permission as well.
9. Click Save in the top right corner of the page.
10. Open the Employees section of Roles and Permissions.
11. Click Add New Employee to create a test user and assign them the new SCIM user role.
12. Make a copy of the SCIM Attribute Mappings file, which lists all of the default Paradox Attributes that are supported, and share it with the client.
    • Note: Both the default and any additional custom attributes can be pulled from the schema APIs. This can be done by the client's technical resource or you.

Step #2: Determine the employee unique identifier

1. Return to the Integrations section of Client Setup.
2. In the SCIM subsection, select the Primary Attribute. This will default to the log in option set in the Data Privacy section of Client Setup, but it can be updated to one of the following:
   • Employee ID
   • Email
   • SCIM External ID
   • SCIM Username
   • Phone Number
3. Click the + Add IP Address button to add a whitelisted API.
4. Repeat step #3 for all IP addresses that should be whitelisted. Otherwise, all IPs will be available to call Paradox's SCIM endpoints.
5. Select the Max Bulk Operations limits. Options include:
   • 5
   • 10 (default)
6. Save the page.
7. Navigate to Roles and Permissions.
8. Open the Roles and Permissions section from the left panel.
9. Each user role in the CEM will need to have an External ID assigned to it. This will be the value that the client sends in the role attribute in order to assign the users to their appropriate user role. Hover over the first user role; click it's action menu, or ellipses; and then select Edit.
10. When the page opens, enter in the External ID assigned to the role. 
11. Save the page.
12. Repeat steps #9-11 for each user role.

Step #3: Generate auth token

1. Impersonate the new SCIM employee. You can do this by:
   1. Clicking your avatar.
   2. Clicking your name.
   3. Search for the SCIM user.
   4. Select their name from the list.
2. Open their My Profile from the avatar menu.
3. Click the Settings button in the top right corner of the profile.
4. From the Account ID and API Secret section, click Generate API Secret.
5. Copy the Account ID and the API Secret. These will be used as the client_id and client_secret, respectively, when generating the auth token.

6. Make an HTTP request to the Oauth2 endpoint using the appropriate base url, the client_id, and client_secret from the SCIM integration user.

{{base_url}}/api/v1/public/auth/token

Accept:application/json
Content-Type:application/x-www-form-urlencoded

client_id:{{client_id}}
grant_type:client_credentials
client_secret:{{client_secret}}

7. Save the access_token from the response body. The customer will need to add this to the SCIM integration in their IDP in order to successfully authorize their requests. 

2. The auth token should be shared with you as a private note using the Paradox PrivateBin tool.

Step #4: View the SCIM Resources

Customer users can review the below SCIM resources:

• Point the client to the SCIM 2.0 Implementations section of the SCIM Implementations documentation.
• The supported Paradox Implementation Client Handbook documentation (download and share as a PDF).
• Additional information can be found in this SCIM Protocol documentation on Paradox SCIM endpoints.

SCIM API testing

To test the SKIM authentication, follow the steps below.

1. Collect the client_id and secret_key for the SCIM integration user you created in step #1 above.
2. Apply the values to the appropriate variables in the SCIM Postman collection, and post to the oauth2 endpoint.

{
	"info": {
		"_postman_id": "b0cd3e06-1534-42f1-ba9a-a90a0007789b",
		"name": "SCIM",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "20564521"
	},
	"item": [
		{
			"name": "Users",
			"item": [
				{
					"name": "[Sample] Get Users",
					"protocolProfileBehavior": {
						"disabledSystemHeaders": {
							"host": true
						}
					},
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/scim+json"
							}
						],
						"url": {
							"raw": "{{host}}/scim/v2/Users",
							"host": [
								"{{host}}"

3.  The access_token in the response can now be used in the Authorization header.

SCIM attribute mapping

Troubleshooting