Creating and Configuring a SCIM-based System of Record

Prerequisites

A System of Record that supports SCIM 2.0
An account capable of reading the desired entities from the SCIM 2.0 SoR

Configuring a SCIM-based System of Record

Each SCIM-based System of Record (SoR) may behave slightly differently in the set of steps and flows required to configure a new service to interact with it.

Some general tips to get started:

Ensure that the SCIM SoR supports SCIM 2.0 – SGNL supports this version of SCIM and beyond, but is not supported for older versions of SCIM such as 1.0 and 1.1
Ensure that you have a credential that is capable of communicating with the SCIM service, and if using OAuth2, is allowed to request the appropriate scopes that allow reading of the entities you’re interested in syncing, commonly these will take the form of the entity followed by the permission, e.g. users.read
If using OAuth 2 – ensure you have a Client ID and Client Secret available for the above, you will require this to complete the configuration inside of SGNL, if using some other method of authentication, such as an API Key or Username/Password, you will similarly need these credentials
Understand the APIs you plan to interact with, if using OAuth to authenticate your SCIM service, you will need to know the authentication endpoints, you’ll also need to understand the base URL of your service that will enable SGNL to synchronize entities – SGNL follows the SCIM Specification in building endpoints based on the names of the entities

Configuring SGNL

Login to the SGNL Console
From the left menu, select Systems of Record
Add a New System of Record and select SCIM 2.0
Enter the following data into SGNL:
- Hostname: Enter the Hostname and Path (e.g. scim.myidp.com/usermanagement) of your SCIM SoR, remembering that SGNL will use this to append relevant entity names to synchronize the various entities from your SCIM SoR
- Adapter: This should be selected by default, but ensure that the SGNL SCIM 2.0 Adapter is selected
- Authentication: Dependent on the implementation of SCIM you are working with, however this will commonly be OAuth2 Client Credentials which will then require you to enter a Client ID and Client Secret into SGNL as well as:
  - Scope: (Optional) If you have been issued specific scopes, enter them here
  - Token URL: This will be different to the hostname above and entered in the format of a URL to tell SGNL where to send OAuth2 Client Credentials in order to interact with entities in the SCIM Server, the path for this will commonly follow the OAuth2 standard of some base url appended with /oauth/v2/token or similar
  - Audience: (Optional) If required, specify the requested audience for the token being issued
- Auth Style: By default, SGNL will determine whether to add the Authentication configuration into URL Parameters, or into the Headers of the request - you can override this behavior by selecting the appropriate method for your SCIM SoR
- Adapter Config: For SCIM 2.0, you can use the Adapter Config to apply filters to your SCIM instance, a sample Adapter Config is below:
```
   {
      "requestTimeoutSeconds": 10,
      "localTimeZoneOffset": 43200,
      "queryParams": {
         "Users": {
               "filter": "userType eq \"Employee\" and (emails co \"wholesalechips.co\" or emails.value co \"wholesalechips.org\"",
               "sortBy": "userName",
               "ascending": true
         },
         "Groups": {
               "filter": "displayName eq \"Wholesale\"",
               "sortBy": "displayName",
               "ascending": true
         }
      }
   }
```
Once configured, click Continue to save your System of Record and move on to configuring Entities
From the Entities tab, click on ‘Edit Attributes’ to select the entities and attributes you will need synchronized into SGNL to be used in your specified SGNL policies
(If applicable) If you will be synchronizing entities and attributes from 2+ different Systems of Record into SGNL to define policies, click on Add join rule to specify the attribute(s) that will join the entities you’ve configured to synchronize from SCIM to other entities in the SGNL Graph
- You only have to specify a join rule from one System of Record. For instance, if you specify a join rule between SCIM Users and Azure Active Directory Users, you only need to configure the relationship from either the SCIM or Azure Active Directory System of Record
- E.g. If User Employee IDs are found in SCIM and your HRIS system and are consistent, you can choose the Employee ID Attribute in this SCIM Instance and the Employee ID Attribute in your HRIS System of Record to join these entities together
- Join rules should only be used for entities that represent the same object across 2+ different Systems of Record. For instance, if a User in SCIM represents the same User as one in Azure Active Directory, it is a good candidate for a join rule
  - However, a User in Azure Active Directory and a Group in ServiceNow represent different objects and are therefore not good candidates for join rules, and instead should have custom relationships created via the Relationships API. Additionally, if a User in Azure Active Directory is not the same User as one in ServiceNow, it is not a good candidate for a join rule
Save the Configuration
Once ingestion is complete and the data from your SCIM SoR is in the SGNL graph, you can use Data Lens to explore the SGNL graph.