Note: Please read our SCIM 2.0 Overview article to understand the feature capabilities and configurations necessary on your Stack Overflow Business site before proceeding.

Creating a SCIM 2.0 application in OneLogin

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

  • Using the Administration panel, navigate to Apps > Add Apps

  • Search for SCIM apps that support SCIM 2.0 and OAuth bearer tokens (such as SCIM Provisioner with SAML (SCIM v2)) and choose to add that application. This will take you to an application creation wizard

  • Configuration Set the Display Name with a descriptive name (such as SCIM 2.0 - Stack Overflow Business). Other settings may be left at their defaults or changed depending upon your requirements. Click Save, and continue on to the next section.

Assign users to the SCIM 2.0 application

  • Users may be added either directly or by Roles, both under the Users menu. Select a target User or Role, and click through to the Applications tab. Add applications with the "+" icon. 

Setting up user deactivation and reactivation

  • In Stack Overflow Business, enable SCIM and generate an a SCIM authorization token for your application at /c/{your_team}/admin/access/scim. Please note that this token will only be visible when you generate it. If it is lost, you will need to generate a new one and reconfigure your OneLogin application.

  • Navigate to your SCIM 2.0 application in OneLogin and click the Configuration tab

  • Check Enable API Integration and set the following parameters:

    • SCIM Base Url https://stackoverflow.com/c/{your_team}/auth/scim/v2

    • SCIM Bearer Token The token that you generated previously.

    • SCIM JSON Template A JSON template is required to pass the correct keys and variables to Stack Overflow Business. The specifics may vary by organization. Please modify and/or extend the following example template to suit your needs:

  {

      "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"

      ]

}


  • Click Enable. You should get a result similar to a green dot with the text Enabled

  • Click Save to effect these settings

  • On the Provisioning tab, check Enable provisioning

    • Make other adjustments as fit your organization's needs. Please note that the action drop-downs should be set to Suspend if you'd like for users to be deactivated  on those events in OneLogin. Stack Overflow Business does not support deletion of users via SCIM 2.0.

    • Click Save

Now, when users are deactivated or reactivated in OneLogin and are assigned to the appropriate SCIM 2.0 app, their status should be changed in Stack Overflow Business as well. You may stop here, or proceed on to also manage Admin permissions in OneLogin as well.

Optional Setting up Admin promotion and demotion

SCIM 2.0 may also be used to promote a Registered user to an Admin user, or to demote an Admin user to a Registered user.

User promotion is determined by a userType custom field in the SCIM 2.0 payload, which needs to be created following steps below. This key takes the value of either "Registered" or "Admin". If the value is "Admin", the user is promoted to an Admin. If set to "Registered", the user is demoted from Admin.

1) First, ensure that Allow SCIM to manage user roles is set to checked in /c/{your_team}/admin/access/scim. This is required for promotion and demotion to work.

2) Add a custom user field by selecting Users -> Custom User Fields from the top navigation menu, then clicking on "CREATE NEW USER FIELD".  The Shortname must be userType. We recommend setting the Name as userType as well for consistency. The case must match SCIM JSON template - e.g. $user.custom_fields.userType as seen in the next step.

3) Modify the SCIM JSON template. Navigate to your SCIM 2.0 application and click the Configuration tab. You'll need to add the userType field to the payload. Included is a sample template that you may modify and/or extend to suit your needs, including the userType field. Click "Save" once the template is updated.

  {

      "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}"

  }

4) Add the userType parameter in the application: click on Parameters tab, then "Add parameter", and create a parameter with Name "userType" and Value "userType (Custom)", with both "include in SAML assertion" and "Include in User Provisioning" enabled. Click on "Save" again to update the application once the parameter has been added.

5) The userType field can be set in multiple ways. Here are two common options to define a user's admin status:

  • By custom field on the user profile Under Users > All Users, you can edit a user and set the userTypefield under the Custom Fields section of the User Info tab. You may need to click Show Custom Fields to expand the options. This must be done for each admin individually.

  • By Application mapping Under Users > Mappings, field mappings may be configured for each application based on certain conditions. For example, one could define a mapping for Admin permissions based on Role membership. Create a New Role, and set the conditions accordingly (in this case, Roles include<admin role name>). Then, under actions, set the userType field (in this case, Set userType Admin). Then, clone this rule and create an inverse rule to set Registered/regular user status by tweaking the condition and userType value (here, Roles do not include <admin role name>, Set userType Registered). This will assure that the Admin privilege may be both set and removed by Role membership alone.

Note:

  • Enabling SCIM 2.0 user management in Stack Overflow Business does not disable user management within Stack Overflow Business. That is, a user may be active in OneLogin and assigned to the Stack Overflow Business SCIM 2.0 app, and they may still be manually disabled within Stack Overflow Business. We recommend standardizing on a single workflow within your organization so that expectations are shared.