SCIM is the System for Cross-domain Identity Management. SCIM is used to connect Okta to other applications. With SCIM, user identities can be created either directly in a tool like Okta, or imported from external systems like HR software or Active Directory. Since it is a standard, user data is stored in a consistent way and can be communicated as such across different apps. This enables IT departments to automate the provisioning/deprovisioning process while also having a single system to manage permissions and groups. Since data is transferred automatically, risk of error is also reduced.
It is important to work with an Implementation Consultant on the Bridge team when you are first setting up user provisioning for Bridge. The Bridge team can support you in creating the required API key and secret, enabling provisioning for your account, and testing the provisioning process. Before attempting to configure the account, ensure that you meet the following requirements:
- Complete the steps in this document: Configuring Okta SSO with Bridge
- Your Bridge subdomain: https://[subdomain].bridgeapp.com - you will not need the whole URL, you will enter the subdomain in the general app configuration settings.
- Okta API Key/Secret: provided by the Implementation Consultant. This could take up to 24 hours to obtain.
A user will not be provisioned if your Bridge account has more than one user with the same unique identifier. This is possible when you’ve deleted a user and then created a new user with the same unique identifier. If this is an issue with your account at any time, your support representative can assist you in a permanent deletion of at least one of the users in your account with the same unique identifier, at which point you will be able to proceed with provisioning of that user.
Before you start to configure provisioning, be sure you’ve followed the requirements listed above and that you’ve worked with an Implementation Consultant to help with a strategy for both standard and custom fields in your user provisioning process.
To configure the application, click the General tab. Enter the subdomain of your account (do not enter the entire URL). Then click Save.
Click the Provisioning tab, then click the Configure API Integration button. Check the box labeled Enable API Integration. Enter the API Key and the API Secret which was provided to you by the Implementation Consultant.
Click the Test API Credentials button. You should see the following, if successful:
Bridge supports four operations for Okta provisioning:
You can now assign people to the app (if needed) and finish the application setup.
The only required attribute in Bridge is the Unique ID (uid). Okta requires email, firstname, and lastname so if you are using two-way sync, you’ll want to populate those fields as well. Add any custom fields to either the master user profile or the application specific profile record so that those fields can be created in Bridge and attributes can be included in user provisioning via Okta. All other attributes are optional, but it is recommended that you at least include:
*Potential Pitfall - Roles are sent by Okta by default and can wipe out roles if they are not set in Okta when users are synced to Bridge. For example, user_1234 has Account Admin permissions but that is not set in Okta. When the SCIM call is made to update user_1234, they will no longer have Account Admin permissions. If you are not managing Bridge roles through Okta SCIM, reach out to your IC and CSM indicating you'd like roles to be blacklisted.
Next, you will need to add attributes. From the Admin view, in the top navigation bar click on Directory > Profile Editor
Find the Bridge profile and click on Profile
On the Attributes page click on Add Attribute. If the attribute already exists click on the pencil to confirm that the attribute profile has the following info.
If the attribute does exist and does not have the correct external namespace, then delete and recreate using the info below.
To create an attribute that will be passed over to Bridge, the most important part is to have the following in the External Namespace field for each attribute:
Display name: This display name is used as a human readable label when the attribute appears in the UI.
Variable name: The variable name is used to refer to this attribute in profile mappings and expressions.
External Name: Name of Attribute
External Namespace: urn:scim:schemas:extension:custom:2.0:User
Description: Description of Attribute
Data type: must match data type of the attribute that you are mapping this to in the user's profile
Attribute Length: Left at between with min and max blank.
If you want to pass and associate managers from Okta into Bridge, you will want to add an attribute for Manager Id. You will follow the same steps as you did when creating the custom attribute (shown above). See troubleshooting tips regarding case sensitivity in this mapping.
External name: manager.value
External Namespace: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
Here is a screenshot of the values that you need to fill out. Most importantly are External Name and External Namespace. The values in these fields must be exact.
Next step is to map attributes to be synced from Okta to Bridge:
Click on Mapping
Select Okta to Instructure Bridge
Map the Okta user profile attribute(s) to the Bridge custom attribute
Save, As soon as you click on save the Okta to Bridge sync is live and users will flow from Okta to Bridge.
The most common error that will occur is when multiple users exist with the same UID. This often happens when you create a new user in Bridge rather than going through the typical user restore process. Okta will restore users via the provisioning functionality, but if you’ve restored users through any other method, you may end up with a duplicate user. The Bridge team can help you to resolve this. If you only use Okta provisioning for user creation and updates, then you should not run into this issue. This can be easily resolved by contacting Bridge support.
The SpEL-based Okta Expression Language (EL) allows you to reference, transform and combine attributes before storing them in a user profile or passing them to an app for authentication or provisioning. One example might be to use a custom expression to create a username by stripping "@company.com" from an email address. Or combining firstName and lastName attributes into a single displayName attribute.
This is useful when you need an attribute to match exactly what is in Bridge for example:
Users have capital letters in their email addresses. The Client is useing email as Unique ID (UID), by default the Bridge normilizes the UID field and Manager ID to an all lower case charestor set. TestUser@Email.com becomes email@example.com This can cause an issue if Okta is sending TestUser@Email.com as the manager id and Bridge is expecting firstname.lastname@example.org. The manager will fail to map.
Using SpEL-based Okta Expression Language (EL) the following value can be expressed to send Bridge an approperate vlaue: toLowerCase(getManagerUser("active_directory").email)
- Create Users: we support all of the initial provisioning attributes as well as custom fields in Bridge. The Okta application supports roles and the automatic creation of custom fields in Bridge on user provisioning/sync
- Update Attributes: we support the standard provisioning attributes: uid, firstname, lastname, roles, email, custom attributes
- Deactivate Users: we support soft-deletion from our application. The users are removed from the UI and no longer have any access to Bridge, but their data is left intact, in case they would like to restore the user later. The only way to fully delete a user is via support.
- Sync Password: we do not support this feature because Bridge does not support any back door for access. You either have your IdP working, or you have to switch to basic authentication.
- Unavailable Fields: Department (standard field), HRIS ID, Hire Date, Job Title (standard field) are all unable to be synced using Okta SCIM.