Configure System for Cross-domain Identity Management (SCIM) with OneLogin

ADMIN PRIVILEGES REQUIRED

Overview

System for Cross-domain Identity Management (SCIM) is an open API for securely sharing user information between online systems. In Stack Internal Community, SCIM 2.0 support allows an Identity Provider (IdP) to automatically update Stack Internal Community with the user's activation status and/or role. Unlike SAML 2.0, which passes user information only at login, SCIM sends updates whenever they occur. This provides Stack Internal Community near-real-time updates to user status and role as changes happen at the IdP.

This article covers integrating OneLogin and your Stack Internal Community site with SCIM. For a better understanding of using SCIM with Stack Internal Community, read our SCIM 2.0 support article.

Configure SCIM on Stack Internal Community

To configure your Stack Internal Community site, follow the steps in the "Configure SCIM support on Stack Internal Community" section of the System for Cross-domain Identity Management (SCIM) 2.0 Support article. When done, return to this article and follow the IdP-specific instructions below.

Configure SCIM in OneLogin

OneLogin has an article on creating a SCIM 2.0 application which we recommend reviewing before proceeding.

1. Using the OneLogin Administration panel, navigate to Apps, then Add Apps.
2. Search for SCIM apps that support SCIM 2.0 and OAuth bearer tokens (such as SCIM Provisioner with SAML (SCIM v2)) and add that application. This will take you to an application creation wizard.
3. On the configuration page, set the Display Name with a descriptive name (such as SCIM Stack Internal Community). Leave other settings at their defaults, or change them as needed for your application.
4. Click Save.

Set up user deactivation and reactivation

1. Click on your new SCIM application and click the Configuration tab.
2. Check Enable API Integration and set the following parameters
   • SCIM Base Url Set to https://[your_site].stackenterprise.co/api/scim/v2.
   • SCIM Bearer Token Enter the SCIM authorization bearer token you created on your Stack Internal Community SCIM settings screen.
   • SCIM JSON Template SCIM requires a JSON template to pass the correct data to Stack Internal Community. Specifics will vary by organization, but you can modify the following example template as required.

Example JSON template (no userType field)

{
    "userName": "{$parameters.scimusername}",
    "name": {
        "familyName": "{$user.lastname}",
        "givenName": "{$user.firstname}",
        "formatted": "{$user.display_name}"
    },
    "emails": [
        {
            "value": "{$user.email}",
            "type": "work",
            "primary": true
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ]
}

3. Click Enable. You should see an "Enabled" confirmation message.
4. Click Save.
5. On the Provisioning tab, check Enable provisioning.
   • Make changes to the fields on this page as required. To have OneLogin events deactivate Stack Internal Community users, choose Suspend from the action drop-down. Stack Internal Community does not support deletion of users via SCIM.
   • Click Save.

When users are deactivated or reactivated in OneLogin, and are assigned to the appropriate SCIM app, the SCIM update should change their status in Stack Internal Community as well.

Assign users to the SCIM application

You can add users either directly or by role, both under the Users menu. Select a target user or role, then click through to the Applications tab. Add applications with the [+] icon.

Configure administrator and moderator promotion and demotion (optional)

You can use SCIM to promote/demote users between administrator, moderator, and regular user roles. This requires enabling Allow Moderator Promotion via a userType property and/or Allow Admin Promotion via a userType property on the SCIM integration settings page in Stack Internal Community.

User promotion is determined by the userType field in the SCIM payload. Stack Internal Community will change a user's role based on the following userType values: Registered, Moderator, or Admin.

To set up user promotion and demotion in OneLogin:

1. Add a custom user field by selecting Users then Custom User Fields from the top navigation menu.
2. Click CREATE NEW USER FIELD. The Shortname must be userType. We recommend setting the field's Name to userType as well for consistency. The case of the characters must match that of the SCIM JSON template (for example: $user.custom_fields.userType).
3. Modify the SCIM JSON template by clicking the Configuration tab. Add the userType field to the payload. Click Save.

Below is an example template with the optional userType field.

Example JSON template with optional userType field

{
    "userName": "{$parameters.scimusername}",
    "name": {
        "familyName": "{$user.lastname}",
        "givenName": "{$user.firstname}",
        "formatted": "{$user.display_name}"
    },
    "emails": [
        {
            "value": "{$user.email}",
            "type": "work",
            "primary": true
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userType": "{$user.custom_fields.userType}"
}

3. Add the userType parameter in the OneLogin application by clicking the Parameters tab, then Add parameter. Create a parameter with Name userType and Value userType (Custom). Enable both Include in SAML assertion and Include in User Provisioning. Click Save to update the application.

4. Use one of the following methods to configure userType mapping in OneLogin.

   • By custom field on the individual user profile at Users -> All Users. You can edit a user and set the userType field under the "Custom Fields" section of the User Info tab. You may need to click Show Custom Fields to expand the options. You'll have to do this for every user you want to promote to moderator or administrator.
   • By Application mapping under Users -> Mappings. You can configure field mappings for each application based on certain conditions. For example: you could define a mapping for admin or moderator permissions based on role membership. See OneLogin documentation for more information.

Update user department and job title (optional)

You can add optional user department and job title fields to your SCIM data. Adding these fields allows you to use Stack Internal Community's connectivity reporting feature. Learn more in the Connectivity article.

Follow the process above for userType to add and map department and title fields. Then add the fields to your JSON data file. When finished, the data file should look like this:

{
    "userName": "{$parameters.scimusername}",
    "name": {
        "familyName": "{$user.lastname}",
        "givenName": "{$user.firstname}",
        "formatted": "{$user.display_name}"
    },
    "emails": [
        {
            "value": "{$user.email}",
            "type": "work",
            "primary": true
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userType": "{$user.custom_fields.userType}",
    "department": "{$user.department}",
    "title": "{$user.title}"
}