Single Sign-On (SSO)
      Back to home
      1. Knowledge Base
      2. Learner Admins
      3. Single Sign-On (SSO)

      How do I implement SCIM in Azure for my organization's SSO profile?

      As a customer, I want to set up SCIM for easy automatic user provisioning to avoid having to manage employee listings with HSI Blue Ocean Brain.

      What are the features of SCIM for Azure?

      What are the prerequisites for setting up SCIM?

      How do I configure SCIM for my Azure integration?

      1. Enable Provisioning in Azure
      2. Configure and map SCIM attributes
      3. Establish user assignments

      Troubleshooting and Tips

      What are the features of SCIM for Azure?

      • Push New Users. New users created through Azure will also be created in HSI Blue Ocean Brain

      • Push Profile Updates. Updates made to the user's profile through Azure will be pushed to HSI Blue Ocean Brain.

      • Push User Deactivation. Deleting the user or disabling the user's access to the application through Azure will delete or deactivate the user in HSI Blue Ocean Brain (the "delete" or "deactivate" ability will depend on how your Azure configuration is set up to handle de-provisioning).

      • Push User Reactivation. Reactivating the user’s access to the application through Azure will reactivate the user in HSI Blue Ocean Brain.

      What are the prerequisites for setting up SCIM?

      SSO must be fully configured and working before provisioning can be enabled. Please ensure that you and your HSI Blue Ocean Brain IT contact have verified a working SSO setup through Azure before continuing.

      Note: At this time, the HSI BOB Azure app does not support SCIM. SCIM must be configured on an Azure SSO profile that was manually configured.

      How do I configure SCIM for my Azure integration?

      Please reach out to your HSI Blue Ocean Brain IT contact and request “SCIM” (automatic user provisioning) to be enabled for your account.

      If your SSO profile was configured using the HSI BOB Azure SSO app, you must configure a new SSO profile to then configure SCIM.

      The HSI Blue Ocean Brain IT contact will generate and provide you with an authentication token, which will be entered into the Azure application.

      Step 1: Enable Provisioning in Azure:

      You will need to set up a specific group in Azure in order to enable SCIM, even if you want everyone to have access to HSI BOB.

      1. On the HSI Blue Ocean Brain SSO app page, under Manage on the left panel, click the Provisioning tab.

      2. Click Get started.
      3. For Provisioning Mode, you have two options: Manual and Automatic.
        1. The Manual mode can be used if you want to manually add and remove users from an SSO profile in Azure. This will be more time-intensive to maintain as employees are onboarded or offboarded from your organization.
        2. The Automatic mode can be used if you have certain criteria that can auto-filter users to be added to the SSO profile in HSI BOB.
      4. You will be prompted to add Admin Credentials.
        1. The Tenant URL is https://api.blueoceanbrain.com/scim/v2
        2. The Secret Token will be provided to you by the HSI BOB IT team via an encrypted email.
      5. Click Test Connection.
        1. With a successful test, you'll see a pop-up message with a green check mark: "Testing connection to HSI Blue Ocean Brain. The supplied credentials are authorized to enable provisioning."
      6. Click Save.

      Step 2: Configure and map SCIM attributes.

      Once you save the Admin credentials, you'll see a new section appear below called Mappings. Employee attributes are used for HSI BOB reporting, and your company can map up to 25 additional attributes (not including First Name, Last Name, Email, Preferred Language, or the NameID/Unique User Identifier).

      1. For the Provision Azure Active Directory Groups, you may see that Enabled is selected as Yes. We do not support Group syncing, so you will need to disable this setting.
        1. Click Provision Azure Active Directory Groups.
        2. Under Enabled, click No.
        3. Click Save and click Save again to confirm the changes.
      2. Click Provision Azure Active Directory Users.
        1. Under Enabled, Yes should be selected.
        2. Under Target Object Actions, Create and Update should be selected.
        3. If you want to "soft delete" (ie. deactivate) your users, do not check Delete.
        4. If you want to erase your users' data using SCIM, select Delete.
        **Note: For de-provisioning, Azure SCIM supports both deleting and deactivating (archiving). How your users are de-provisioned (i.e. whether you delete or deactivate your users) will depend on which SCIM command you have configured.

      3. Under Attribute Mappings, you will see the attributes that are currently available for your SSO profile. By default, the following attributes are kept in sync with HSI Blue Ocean Brain and are automatically mapped.
        1. givenName
        2. surname
        3. mail
        4. preferredLanguage
        5. Username (the Unique Identifier)
      4. Any attributes already mapped in the SSO profile at the time when the BOB SSO profile was created will be available to map on the HSI BOB side for SCIM. You can remove (Delete) any attributes that you don't want to send to HSI BOB (aside from the default attributes required above).
      5. For the "Switch" attribute, which is required for SCIM, make the following change: 
        1. Update the default attribute mapping for Switch from Switch([IsSoftDeleted], "False", "True", "True", "False") to Switch(CBool([IsSoftDeleted]),"null","True","False","False","True").
      6. If you want to map "Manager" in your SSO profile, make sure that you update the mapping from "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager" (this is the Azure default) to "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value".
      7. To add additional existing attribute mappings, click Add New Mapping.
      8. To add a custom attribute, click Show Advanced Options.
        1. Then click Edit attribute list for custom app SSO.
        2. Scroll to the bottom and paste the following as a new attribute. urn:bob:params:scim:schemas:extension:meta:2.0:User:meta1. The Type should be set to String. Click save.
          1. Note: the number at the end of this string may change based on what your HSI Blue Ocean Brain IT contact provides you.
        3. Navigate back to Attribute Mapping and click Add New Mapping. A new screen will open for you to edit the attribute. Select the custom attribute you just created from the dropdown under Source Attribute.
        4. Click Ok.

      Step 3: Establish user assignments.

      1. On the HSI Blue Ocean Brain SSO app page, Under Manage on the left panel, click Users and Groups. This is where you'll set up your user group(s) of those who will be allowed access to BOB. 
        **Note: If you don't want all users with an SSO profile to be added to HSI Blue Ocean Brain, please make sure to set up a user group of people who will be assigned to Blue Ocean Brain. Exchange accounts in Azure should not be added to HSI BOB.
        1. Click Add user/group.
        2. Under the Users and groups tab on the left panel, search for the user(s)/group(s) that you want to assign to the HSI BOB SSO profile and click Select.
        3. Skip Select a role.

          **Note: All users are added with the same role to HSI BOB. Any Admin functions within BOB are configured by the BOB team and communicated to the individuals with those permissions at your organization.
        4. Click Assign.
      2. On the HSI Blue Ocean Brain SSO app page, under Manage on the left panel, click the Properties tab.
        1. For Enabled for users to sign-in?, select Yes.
        2. For Assignment required?, select Yes.
        3. If you're ready for users to be able to see the HSI BOB app within Azure, for Visible to users?, select Yes.
        4. Click Save.
      3. Once your user assignments are configured, on the Blue Ocean Brain SSO app page, under Manage on the left panel, click the Provisioning tab.
        1. Click Edit Provisioning on the top menu.
        2. Click the Settings accordion tab.
        3. Check the box for "Send an email notification when a failure occurs."
        4. In the Notification Email box, type the email address that would be alerted to any failures.

          **Note: Azure doesn't send the HSI BOB team information regarding failures with user account syncing. If there is an issue, please notify the HSI BOB IT team.
        5. Under the Scope tab, select "Sync only assigned users and groups."
      4. Once you're ready to sync your user list, on the HSI Blue Ocean Brain SSO app page, under Manage on the left panel, click the Provisioning tab.
        1. Click Start provisioning. A background task is now queued. If you are adding a large number of brand-new users, it will take some time to create all the employee accounts.
      5. To see the progress of the provisioning, under Current cycle status, click View provisioning logs.

      **Note: Azure syncs the user provisioning every 40 minutes.
       
      You're now finished with the SCIM setup for your Azure SSO profile!

      Troubleshooting and Tips

      • If there are errors when syncing a user in Azure, Azure will re-try to send every 15 minutes until the error is corrected with no end-limit.

      • By default, HSI Blue Ocean Brain will send a welcome email to the new user on account creation. If you’d prefer these welcome emails not to be sent, please contact your HSI Blue Ocean Brain Client Success Manager or Blue Ocean Brain IT contact.

      • In order to be supported by provisioning, a user must have a First Name and Last Name, as well as a unique email address.

      • The "Preferred Language" field is optional. If set, the field should be an “ISO 639-1” language code. If your HSI Blue Ocean Brain account doesn’t support the selected language, English is selected for the user. Contact HSI Blue Ocean Brain Support to inquire about enabling additional languages.