SCIM Integrations

Overview

This guide explains how you can create various JSONs for a REST based application. The example provided here are specific to application that supports SCIM and the same principles applies to all other REST based applications.

Understanding SCIM

SCIM stands for System for Cross-domain Identity Management, and it's a set of protocols that automates data provisioning across multiple domains. SCIM is an open standard that uses JSON, REST, and other authentication methods to standardize how identity information is shared between organizations. SCIM is often used to simplify the process of granting people access to cloud-based applications.

Integration of SCIM with Saviynt via REST Connector

Saviynt's Enterprise Identity Cloud (EIC) can integrate with SCIM-based applications using its REST connector to manage user lifecycle and access controls efficiently. Here's how the integration generally works:

Configuration of the REST Connector

Connection Setup Administrators set up a REST connection in Saviynt by specifying the endpoint URL, authentication credentials (such as OAuth, Basic Auth), and other necessary parameters like SSL certificates and vault configurations for secure connections.
Schema Definition SCIM uses a predefined schema for user and group management, which should be mapped to Saviynt’s schema to ensure that the identity attributes in SCIM are correctly understood and processed by Saviynt.

User Provisioning and Management

Import Operations Saviynt can perform full imports of users, accounts and their attributes and access from the SCIM service, adding them into the Saviynt management platform.
Provisioning Operations Similarly, changes made within Saviynt, like creating or updating user profiles, can be pushed to the SCIM-based application, ensuring consistent identity data across systems.

Deprovisioning and Access Management

Removing Access When access needs to be revoked, Saviynt can send appropriate commands via the REST connector to disable or delete accounts or modify entitlements in the SCIM service.

Benefits of SCIM Integration via Saviynt's REST Connector

Automated User Management: Reduces the administrative overhead by automating the creation, update, and deletion of user identities and their entitlements across different systems.
Consistency and Compliance: Helps maintain consistency of identity data across platforms, aiding compliance with various regulatory requirements.
Security: Offers robust security features, including support for secure connections, detailed access and change logs, and the ability to quickly revoke access when needed, reducing potential security risks.
Efficiency and Accuracy: Minimizes manual errors and improves operational efficiency in managing user identities and access.

Step by Step Instructions to onboard SCIM Applications

These instructions are specific to creating JSONs and do not detail all the activities that needs to be performed in Saviynt in order for these JSONs to be operational. Please refer to Saviynt documentation on how and where to use these jsons.

For the purpose of this guide, we will use Zscaler and build the relevant jsons.

Step 1 - ConnectionJSON

The ConnectionJSON in the context of Saviynt's REST connector is a structured JSON object used to configure the connection parameters for integrating with an external application via REST APIs. This JSON configuration includes details about how to authenticate, communicate, and handle errors when interacting with the application's endpoints.

Refer to ConnectionJSON In Depth for detailed information about various attributes of ConnectionJSON and what to use when.

Zscaler supports OAuth2 authentication with Bearer token. In order to manage users and access using Saviynt in Zscaler, SCIM needs to be enabled in Zscaler These steps are performed in the ZIA Admin Portal. For more information, see the applicable ZIA product documentation

Enable SCIM support for the selected IdP.
Make a note of these values because you’ll need them for the next step:

Base URL
Bearer token

The ConnectionJSON configuration will look like this -

{
  "authentications": {
    "acctAuth": {
      "authType": "oauth2",
      "httpHeaders": {
        "contentType": "application/json"
      },
      "authError": [
        "InvalidAuthenticationToken",
        "AuthenticationFailed"
      ],
      "url": "<Base URL>",
      "httpMethod": "POST",
      "httpContentType": "application/json",
      "errorPath": "error.code",
      "maxRefreshTryCount": 5,
      "tokenResponsePath": "access_token",
      "tokenType": "Bearer",
      "authHeaderName": "Authorization",
      "accessToken": "<Bearer Token>",
      "httpParams": "[object Object]",
      "retryFailureStatusCode": []
    }
  }
}

Breakdown of the connection json

authentications

This is the root element containing authentication configurations. Different authentications can be set up under this, identified by unique keys (in this case, acctAuth).

acctAuth

This key identifies a specific authentication configuration which can be referenced in various integration tasks within Saviynt.

authType

Indicates the authentication method, which is oauth2 here, signifying that OAuth 2.0 protocol is used for securing API access.

httpHeaders

Specifies additional headers to be sent with the API requests. Here, the Content-Type is set to application/json, indicating that the body of the HTTP requests will be formatted in JSON.

authError

An array of error messages that could be expected when authentication fails. These specific errors will be used to identify authentication issues and trigger error handling workflows.

url

The URL endpoint to which the REST API requests are made. The placeholder <Base URL> should be replaced with the actual tenant.

httpMethod

Specifies the HTTP method used for requests, which is POST in this context. This is typical for API endpoints that initiate a new session or access token.

httpContentType

Indicates the content type of the requests, reiterating that it is application/json.

errorPath

JSON path in the response that points to where error messages are provided by the API. This helps in parsing and identifying error details from the response.

maxRefreshTryCount

Specifies the maximum number of times the system should attempt to refresh the authentication token if the initial attempt fails, set to 5 in this case.

tokenResponsePath

Specifies the path in the JSON response from which the access token can be extracted, important for handling the OAuth2 token lifecycle.

tokenType

Defines the type of token, which is Bearer here. This is used in the Authorization header to provide the credential type.

authHeaderName

The name of the HTTP header where the access token should be included, which is Authorization here.

accessToken

The actual access token to be used for authentication. The placeholder <access token> needs to be replaced with a valid token.

httpParams

Additional HTTP parameters for the request. It appears to be incorrectly formatted as "[object Object]" and should ideally be a JSON object detailing specific parameters.

retryFailureStatusCode

An array of HTTP status codes that would trigger a retry of the request. It is empty in this configuration, suggesting no retries based on status codes are configured.

Notes

Error Handling

The authError and errorPath settings are critical for robust error handling, ensuring that the system can react appropriately to authentication failures or other API errors.

Security Considerations

Storing sensitive information like accessToken in plain text within configurations should be handled with care

Dynamic Elements

Elements like <Base URL> and <Bearer Token> suggest that this configuration should be dynamically populated with actual data during implementation.

This ConnectionJSON sets up the necessary parameters and structures to securely and effectively communicate with Zscaler SCIM endpoint.

Step 2 - ImportAccountEntJSON

Refer to Zscaler SCIM Examples for detailed Zscaler APIs for User Management

{
   "accountParams":{
      "processingType":"SequentialAndIterative",
      "connection":"ZscalerZia",
      "createUsers":false,
      "statusAndThresholdConfig":{
         "accountThresholdValue": 200000,
         "accountsNotInImportAction":"Suspend"
      },
      "successResponses":{
         "statusCode":[
            200,
            201,
            202,
            203,
            204,
            205
         ]
      },
      "call":{
         "call1":{
            "http":{
               "url":"https://scim.zscalertwo.net/51427645/318848/scim/Users",
               "httpContentType":"application/json",
               "httpMethod":"GET",
               "httpHeaders":{
                  "Authorization":"${access_token}",
                  "Accept":"application/json"
               }
            },
            "listField":"Resources",
            "keyField":"accountID",
            "colsToPropsMap":{
               "accountID":"id~#~char",
               "name":"externalId~#~char",
               "displayName":"displayName~#~char",
               "customproperty1":"id~#~char",
               "customproperty2":"externalId~#~char",
               "customproperty3":"userName~#~char",
               "customproperty4":"active~#~char"
            },
            "pagination":{
               "nextUrl":{
                  "nextUrlPath":"${response?.objectList?.size()>0?'https://scim.zscalertwo.net/51427645/318848/scim/Users?startIndex='+Math.addExact(response.completeResponseMap.itemsPerPage,response.completeResponseMap.startIndex)+'&count='+response.completeResponseMap.itemsPerPage:null}"
               }
            }
         }
      }
   },
   "entitlementParams":{
      "processingType":"SequentialAndIterative",
      "successResponses":{
         "statusCode":[
            200,
            201,
            202,
            203,
            204,
            205
         ]
      },
      "entTypes":{
         "Entitlement":{
            "call":{
               "call1":{
                  "connection":"ZscalerZia",
                  "http":{
                     "url":"https://scim.zscalertwo.net/51427645/318848/scim/Groups",
                     "httpContentType":"application/json",
                     "httpMethod":"GET",
                     "httpHeaders":{
                        "Authorization":"${access_token}",
                        "Accept":"application/json"
                     }
                  },
                  "listField":"Resources",
                  "keyField":"entitlementID",
                  "colsToPropsMap":{
                     "entitlementID":"id~#~char",
                     "entitlement_value":"displayName~#~char",
                     "customproperty1":"id~#~char"
                  },
                  "pagination":{
                     "nextUrl":{
                        "nextUrlPath":"${response?.objectList?.size()>0?'https://scim.zscalertwo.net/51427645/318848/scim/Groups?startIndex='+Math.addExact(response.completeResponseMap.itemsPerPage,response.completeResponseMap.startIndex)+'&count='+response.completeResponseMap.itemsPerPage:null}"
                     }
                  }
               }
            }
         }
      }
   },
   "acctEntParams":{
      "connection":"ZscalerZia",
      "entTypes":{
         "Entitlement":{
            "call":{
               "call1":{
                  "callOrder":"0",
                  "stageNumber":"0",
                  "processingType":"httpEntToAcct",
                  "http":{
                     "httpHeaders":{
                        "Authorization":"${access_token}",
                        "Accept":"application/json"
                     },
                     "url":"https://scim.zscalertwo.net/51427645/318848/scim/Groups/${id}",
                     "httpContentType":"application/json",
                     "httpMethod":"GET"
                  },
                  "entKeyField":"entitlementID",
                  "acctIdPath":"value",
                  "listField":"members",
                  "idPath":"value",
                  "acctKeyField":"accountID"
               }
            }
         }
      }
   }
}

Zscaler JSON Configuration for Importing Accounts and Entitlements

This JSON configuration is used to import accounts and entitlements from Zscaler into the Saviynt Enterprise Identity Cloud (EIC).

accountParams

processingType: Specifies the processing method for account data. Here, it's set to "SequentialAndIterative".
connection: The name of the connection to the target system, in this case, "ZscalerZia".
createUsers: Indicates whether new users should be created during the import process. Set to false here.
statusAndThresholdConfig: Configures thresholds and actions for account import.
- accountThresholdValue: Sets a threshold for account processing.
- accountsNotInImportAction: Action to take for accounts not included in the import, such as "Suspend".
successResponses: Lists acceptable HTTP status codes that indicate a successful operation.

HTTP Call Configuration (`call` > `call1`)

http: Configures the HTTP request details.
- url: Endpoint URL for fetching account data.
- httpContentType: Specifies the content type of the HTTP request, set to "application/json".
- httpMethod: HTTP method to use, here it is "GET".
- httpHeaders: Defines HTTP headers, including authorization and content type.
listField: Specifies the field in the response that contains the list of resources, here "Resources".
keyField: Key field in the response that uniquely identifies each account, here "accountID".
colsToPropsMap: Maps columns from the response to properties in Saviynt.

Pagination

pagination: Handles paginated responses.
- nextUrl: Defines the path for the next set of results.

entitlementParams

processingType: Specifies the processing method for entitlement data. Here, it's set to "SequentialAndIterative".
successResponses: Lists acceptable HTTP status codes that indicate a successful operation.
entTypes: Defines entitlement types to be imported.

HTTP Call Configuration (`entTypes` > `Entitlement` > `call` > `call1`)

connection: Connection name.
http: Configures the HTTP request details.
- url: Endpoint URL for fetching entitlement data.
- httpContentType: Content type of the HTTP request.
- httpMethod: HTTP method to use.
- httpHeaders: HTTP headers.
listField: Specifies the field in the response that contains the list of resources, here "Resources".
keyField: Key field in the response that uniquely identifies each entitlement, here "entitlementID".
colsToPropsMap: Maps columns from the response to properties in Saviynt.

Pagination

pagination: Handles paginated responses.
- nextUrl: Defines the path for the next set of results.

acctEntParams

Parameters

connection: The name of the connection to the target system, in this case, "ZscalerZia".
entTypes: Defines entitlement types to be associated with accounts.

HTTP Call Configuration (`entTypes` > `Entitlement` > `call` > `call1`)

callOrder: Specifies the order of the call.
stageNumber: Indicates the stage number in the process.
processingType: Processing type for associating entitlements with accounts, here it is "httpEntToAcct".
http: Configures the HTTP request details.
- httpHeaders: HTTP headers.
- url: Endpoint URL for fetching entitlement details.
- httpContentType: Content type of the HTTP request.
- httpMethod: HTTP method to use.
entKeyField: Key field for the entitlement in the response.
acctIdPath: Path to the account ID in the response.
listField: Field containing the list of members.
idPath: Path to the ID in the list.
acctKeyField: Key field for the account in the response.

Summary

This JSON configuration is used to import accounts and entitlements from Zscaler into the Saviynt EIC. It defines how to connect to the Zscaler API, how to handle responses, and how to map data from Zscaler to Saviynt. It also includes error handling and pagination to ensure robust and complete data import.

This comprehensive setup allows for effective integration between Zscaler and Saviynt, facilitating automated identity management and access governance.

SCIM Integrations

Overview​

Understanding SCIM​

Integration of SCIM with Saviynt via REST Connector​

Benefits of SCIM Integration via Saviynt's REST Connector​

Step by Step Instructions to onboard SCIM Applications​

Step 1 - ConnectionJSON​

Step 2 - ImportAccountEntJSON​

Zscaler JSON Configuration for Importing Accounts and Entitlements​

accountParams​

HTTP Call Configuration (call > call1)​

Pagination​

entitlementParams​

HTTP Call Configuration (entTypes > Entitlement > call > call1)​

Pagination​

acctEntParams​

Parameters​

HTTP Call Configuration (entTypes > Entitlement > call > call1)​

Overview

Understanding SCIM

Integration of SCIM with Saviynt via REST Connector

Benefits of SCIM Integration via Saviynt's REST Connector

Step by Step Instructions to onboard SCIM Applications

Step 1 - ConnectionJSON

Step 2 - ImportAccountEntJSON

Zscaler JSON Configuration for Importing Accounts and Entitlements

accountParams

HTTP Call Configuration (`call` > `call1`)

Pagination

entitlementParams

HTTP Call Configuration (`entTypes` > `Entitlement` > `call` > `call1`)

Pagination

acctEntParams

Parameters

HTTP Call Configuration (`entTypes` > `Entitlement` > `call` > `call1`)