If you want to integrate an application that supports SCIM with OneLogin, and there is no out-of-the-box application connector for your application, you can use a SCIM Custom Connector. OneLogin has multiple SCIM custom connectors to support SCIM versions 1.1 and 2.0 and to support the core and enterprise schemas.
For the purposes of this article, we assume that the application you want to integrate supports SCIM 2.0 and uses the Enterprise Schema. To add your application, go to Applications > Applications and select Add App. In the search box, enter the text “SCIM Provisioner”. You will see a number of SCIM connectors. Select the SCIM Provisioner with SAML (SCIM v2 Enterprise, full SAML) connector.
On the next screen, you can change the display name to be the name of your application. Save to make all other menu items visible.
In the Parameters tab you will see all the parameters that can be provisioned by default to your application. You can add additional parameters, as explained in the “provisioning additional attributes” section below.
You do not need to add parameters for first name, last name or email address. The SCIM provisioner automatically uses the default OneLogin attributes for these three values
The parameter SAML Name ID (Subject) is used for SAML single sign-on, not for SCIM provisioning.
The scimuername parameter uses the Username attribute by default. You may need to update this, depending on the value that your application expects.
For the default parameters, the display name is shown in the Parameters tab. The schema definition in the Configuration tab uses the API name, which is not always the same. The table below maps the display name to the API name:
| Parameter Display Name | Parameter API Name |
| Groups | N/A; Do not include group information in the SCIM schema. |
| Manager ID | external_manager_id |
| department | department |
| scimusername | scimusername |
| title | title |
Go to the Configuration tab. The Application Details section at the top of the page is used to configure SAML single sign-on. If you have already configured single sign-on for your application using a different connector, then you do not need to configure anything here. In that case, you should return to the Info tab and hide this application in the Portal. If you have not already configured single sign-on, and your application also supports SAML, please see Advanced SAML Custom Connector article, for details on how to configure this.
Scroll down to the API Connection section. This is where you will configure the SCIM connection to your application.
| SCIM Base URL | Enter the SCIM API URL for your application. This URL should not include /users at the end. |
| SCIM Bearer Token | If your application uses bearer tokens to authenticate, enter the token in this field. |
| Custom Headers | If your application uses some proprietary custom HTTP header value to authenticate, enter that value in this field in the format "<header-name>: <header-value>”. E.g.: Api-Token: abc123. |
Once you have entered the above values, Save, then select Enable to make the SCIM API connection to your application.
If you are unfamiliar with user provisioning in OneLogin, read Introduction to User Provisioning first.
Go to the Provisioning tab and select Enable Provisioning. For your initial testing, you may want to leave the Require Admin Approval options checked for the create, delete, and update operations.
Select appropriate values for the user deletion and user suspension operations in OneLogin as per your requirements, then Save.
If you plan to provision groups, select the refresh link in the Entitlements section to import existing groups. You can then go to the Access tab and assign a role to the application. All members of the role will be provisioned to the application.
If you wish to provision the same group to all users, you can select that group in the Groups attribute in the Parameters tab. Assuming that you selected the refresh link in the Entitlements section of the Provisioning tab, you should be able to see all available groups.
If you want to provision different group membership to different sets of users, you can do this by creating app rules. You can use regex such that the groups you assign to users in the application are based on each user’s OneLogin roles or Active Directory group membership. For more details, see Using Regex Provisioning with OneLogin and Using SAML to Send AD Group and OneLogin Role Information. The second link refers to a custom parameter for putting filtered group information in a SAML assertion; the exact same principle can be used for group provisioning.
Note: Do not include group information in the user schema.
In the Configuration tab, the SCIM JSON Template field shows the SCIM schema. By default, the following schema is used:
{
"schemas": [
"urn:scim:schemas:core:2.0",
"urn:scim:schemas:extension:enterprise:2.0"
],
"userName": "{$parameters.scimusername}",
"name": {
"familyName": "{$user.lastname}",
"givenName": "{$user.firstname}",
"formatted": "{$user.display_name}"
},
"emails": [{
"value": "{$user.email}",
"type": "work",
"primary": true
}],
"title": "{$parameters.title}",
"urn:scim:schemas:extension:enterprise:2.0": {
"department": "{$parameters.department}",
"manager": {
"value": "{$parameters.external_manager_id}",
"displayName": "{$user.manager_firstname} {$user.manager_lastname}"
}
}
}
For the attribute values, the syntax “$user” means that the value is taken directly from the user’s equivalent attribute value – e.g. “$user.lastname” maps to the user’s last name value.
The syntax “$parameter” means that the value is taken from the user’s attribute that is mapped in the Parameters tab. The name here must exactly match the API name in the Parameters tab. E.g. “$parameters.department” corresponds to the “department” in the Parameters tab.
Note how the “familyName”, “givenName”, “formatted”, “emails.0.value”, and “manager.displayName" attributes are mapped to $user attribute values. These are the only attributes that should be mapped to $user attribute values.
We recommended replacing the attributes for “familyName”, “givenName”, “formatted”, and “emails.0.value” with $parameter attribute values instead. This gives you more control over, and visibility of, the attribute values used. I.e. the relevant part of the schema would appear as follows (updates highlighted).
"userName": "{$parameters.scimusername}",
"name": {
"familyName": "{$parameters.lastname}",
"givenName": "{$parameters.firstname}",
"formatted": "{$parameters.display_name}"
},
"emails": [{
"value": "{$parameters.email}",
"type": "work",
"primary": true
}],
You must then add corresponding parameters in the Parameters tab by selecting the plus icon on the top right. In the New Field dialog, enter the field name. The value you enter is both the display name and the API name for the new parameter. It is case sensitive. Save. In the next screen, select the OneLogin attribute that you wish to map to the new parameter.
When extending the schema with additional attributes, always map them to $parameter attribute values, and add the corresponding parameter, with the exact same name (case sensitive) in the Parameters tab.
For example, your application may support the IETF SCIM 2.0 enterprise schema and you wish to also populate the organization attribute with the value of the company attribute in OneLogin. First, add a new parameter called company and map it to the Company attribute. Then update your schema to include this value. The below example uses the organization attribute, which is part of the SCIM 2.0 Enterprise Schema
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "{$parameters.scimusername}",
"name": {
"familyName": "{$parameters.lastname}",
"givenName": "{$parameters.firstname}",
"formatted": "{$parameters.display_name}"
},
"emails": [{
"value": "{$parameters.email}",
"type": "work",
"primary": true
}],
"title": "{$parameters.title}",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "{$parameters.department}",
"organization": "{$parameters.company}",
"manager": {
"value": "{$parameters.external_manager_id}",
"displayName": "{$user.manager_firstname} {$user.manager_lastname}"
}
}
}
If you are unsure which schema or attribute name to use, consult with the application vendor.
For further information on how OneLogin implements SCIM, and how to integrate a SCIM-enabled application with OneLogin, please see our Dev Overview of SCIM. Please note that the Dev Overview of SCIM lists all the $user values that are available. However, best practice now is to use $parameter values for all attributes.