Brightidea offers support for SCIM (System for Cross-domain Identity Management) to enable automated provisioning and deprovisioning of users and groups from your identity provider (IdP). This guide walks administrators through the steps required to configure SCIM using your IdP (e.g. Okta. Microsoft Intra).
Table of Contents
1. Overview
3. Authentication and Authorization
4. Enable SCIM in Brightidea System
5. Map SCIM User Attributes to Brightidea Profile Fields
6. Groups and Group Membership
7. Compatibility with SCIM 2.0 Specification
1. Overview
Brightidea supports SCIM 2.0 to streamline identity management by automating the synchronization of user and group data from supported Identity Providers (e.g., Okta, Microsoft Intra).
Benefits of SCIM Integration include:
- Automatic provisioning and deprovisioning of users.
- Synchronized user attributes such as name, title, email, and department etc.
- Automated group membership assignment
2. Prerequisites
Before beginning setup, ensure you have the following:
- Access to your Brightidea System Setup as an administrator.
- An Identity Provider that supports SCIM 2.0
- Access to the SCIM feature in your Brightidea System. You should have access to System Menu > Users > SCIM. SCIM integration is disabled by default and must be manually enabled by your Brightidea administrator.
- Technical familiarity with authentication/authorization protocols, user provisioning and identity management.
Identity Management System
An Identity Provider (IDP) service or equivalent identity management system will be required to implement the SCIM provisioning with Brightidea. Several of the most common IDP services and their corresponding support links can be found below. Please note that Brightidea is not able to provide technical support when it comes to issues with your IDP. For any problems with your IDP service, please contact the IDP service provider.
The links provided below are just an entry point. Each of these providers have numerous ways to configure the IdP and you should verify your current setup before deciding how to configure the SCIM integration.
3. Authentication and Authorization
In order to provision users and synchronize user attributes the Identity Provider will make API calls to the Brightidea API using endpoints that follow the SCIM 2.0 protocol. This means that before any provisioning calls are made, the IdP must:
- Be registered with Brightidea as an app in the developer portal
- Possess a valid access token to make those API calls.
The app registration for the purposes of a SCIM integration happens automatically when you enable the feature in your Brightidea system and you access the SCIM configuration page (System Setup > Users > SCIM) for the very first time. Visiting this page will register an app specifically dedicated to the SCIM integration. If your organization has other apps registered for API access they will remain unaffected. The app that is automatically registered is effectively the same kind of app you would register manually as per Brightidea’s API documentation. It is simply a convenient way to get you started with SCIM. The SCIM configuration page will also show the app credentials for API authentication (i.e. Client ID and Client Secret) in the same setup menu page, so integrators don’t have to go to the developer portal to fetch them. It will also show a “Configure” link that will take you to the standard Brightidea app registration “Edit” page for this app.
The way the Identity Provider obtains an access token is by going through an authorization flow at the point of configuration of the integration. The Brightidea API provides Authentication and Authorization to other applications via the OAuth 2.0 protocol. This protocol supports methods depending on the setup of your IdP.
It is important to note that app registration and authorization have no bearing on SCIM. The SCIM integration and provisioning itself is agnostic as to the method you use to ultimately provide an access token for API access. See this documentation for a full description of the various methods of authentication against the Brightidea API that are supported.
An important aspect to keep in mind is that for the purposes of authorization to Brightidea’s API, the roles of Identity Provider and Service Provider are reversed. During the OAuth 2.0 flow, Bright Idea is the source of identity (i.e. for API users). As part of the SCIM app configuration steps, the admin user must authenticate against Bright Idea in order to grant access for the service app. The service app in this case is the SCIM app being configured in the customer IdP. Upon authentication, the admin user will be redirected back to the service app in the IdP site with an authorization code, which the service app can then exchange for an access token.
Consult the documentation of your identity provider and the Brightidea documentation on API access to setup the initial authentication and authorization before testing the SCIM provisioning.
Using long-lived OAuth Tokens for SCIM endpoints
Brightidea’s API OAuth tokens are valid for 24 hours. These tokens must be refreshed regularly using the refresh token provided during the authorization flow.
The API’s SCIM endpoints can be enhanced to support the use of long-lived tokens that are valid for 1 year. These tokens allow for integration scenarios where the IdP does not support the ability to generate and refresh OAuth tokens programmatically.
Using long-lived tokens, integrators can generate the tokens using an API client first and then manually copy and paste the generated token into their IdP’s SCIM application configuration for communication with the Brightidea system. They can then implement a maintenance policy to re-generate a new token every year to keep the integration functional. To enable long-lived tokens in your Brightidea system you must contact your Brightidea representative.
Once enabled, you will be able to generate tokens using an API client like Postman or Insomnia. To do this you follow the same process as if requesting a regular token as documented in the “Password Credentials Flow” section. The only difference is that you will pass an additional parameter called “long_term_token” and set it to “true”. If the authorization flow is successful, the API will then respond with a token whose validity is 1 year from now. See the screenshot below for an example:
4. Enable SCIM in Brightidea System
With the prerequisites met, the first step is to access the SCIM integration configuration page and toggle the switch to turn on the integration. Navigate to System Setup > Users > SCIM integration, select Enable SCIM integration and click the Save Configuration button at the bottom of the page.
5. Map SCIM User Attributes to Brightidea Profile Fields
The SCIM protocol has a specific set of supported schema attributes from which Brightidea can recognize a subset. More specifically Brightidea supports all User resource singular attributes including those in the Enterprise User schema extension.
As an administrator you may map these schema attributes to corresponding user profile fields in the Brightidea side. For this, navigate to System Setup > Users > SCIM integration and browse the page to the “User Schema Mapping” section. You will find a mapping table with the SCIM attributes on the left column and the profile fields on the right.
Some schema attributes have pre-defined mappings that cannot be changed. These are key semantical mappings that help with keeping data integrity between the two systems.
The rest of the attributes have a corresponding dropdown field where you can specify which field should receive the schema attribute value during provisioning and any subsequent synchronization events. The dropdown has options for each of the profile fields configured in the Brightidea system.
You do not have to provide mappings for all fields, you can pick and choose the ones that apply to your integration scenario. For any others you can choose the default “Not Mapped” option.
If you select the same profile field for more than one attribute you will receive an error message and the conflicting fields will be highlighted in red.
When you configure the IdP you will need to make sure that at a minimum you are sending the following required fields:
- userName: This should have the email address of the user so a corresponding member in bright idea can be created and kept in synch.
- displayName: This will be mapped to the member’s screen name
If you don’t specify an “active” attribute during new user provisioning the active is assumed to be true. If you want to create inactive users and update their active status, you must send the attribute with a value of false.
You may specify a password, otherwise a random one will be assigned when new users are created.
In general, fields that are not passed along in the payload of a SCIM resource request operation will be ignored. This means that in a CREATE operation, the value will be left to its default and on an UPDATE operation its value will be left untouched as it is currently set.
If you want to reset/delete the value of a field, you must pass the corresponding SCIM attribute with an empty string or null.
When you are satisfied with your mapping configuration click “Save Configuration” for the changes to take effect.
NOTE: Currently, Brightidea only supports attributes which are standard/default in the SCIM protocol. Custom SCIM attributes may be supported in future versions of Brightidea. Until then, customers are encouraged to use SSO or SFTP synch in order to map custom attributes.
6. Groups and Group Membership
Groups do not have corresponding fields to be mapped to.
Group provisioning works by taking the displayName attribute from the Group schema and using it as the group name in Brightidea. This works for both Create and Update operations.
Group membership is defined by the “members” attribute of the Group schema. The array of member ids is used to assign those members to the specified group. During Update operations, the set of specified members whole replace all previous group memberhip assignments for the group. This means that old members who are not part of the update list will be unassigned from the group and new members that were not previously group members will be added.
Group provisioning assumes all groups are system-level groups. Campaign-level groups are not currently supported.
Brightidea will also save the “externalId” attribute to the “external_id” field in the database. This might be helpful for data reconciliation although it does not have any effect in the Brightidea business logic.
7. Compatibility with SCIM 2.0 Specification
The SCIM 2.0 specification is very extensive and not all of its capabilities are supported. Here is a list of functions that Brightidea does not currently support:
- Multi-Value Attributes are not supported. These are lists of objects (Emails, Phone Numbers, Addresses, Photos, Instant Messaging Addresses, Entitlements, Roles and x509Certificates), each with their own attributes like Value, Type, Primary etc. Bright Idea's profile fields do not support the use of multiple values for a given field.
- Filtering applied to the root of the SCIM server address (i.e. To apply cross-resource type queries)
- Custom selection of fields to be returned in a given query
- Querying Resources Using HTTP POST
- Bulk operations
- Service Provider Configuration Endpoints
- Mapping SCIM attributes to multi-option BI attributes (i.e. Dropdowns and Checkboxes).
- JSON PATCH style operations (Where multiple patch operations are passed in a single HTTP call)
Other limitations:
- Member deletion through SCIM does not create the variety of log entries available when done through the regular delete member within the Brightidea application.
- Campaign level groups. The SCIM specification does not support fields that would allow us to create groups at different scopes (i.e. System vs Campaign). So, all groups are treated as system groups at the moment.
Example requests:
- This API Requests Collection file can be imported into your API Client of choice (e.g. Postman or Insomnia). Once imported you can see the list of API endpoints along with the parameters and sample request bodies for each type of operation
8. SCIM Request Logs
Brightidea will log all requests made to its SCIM API endpoints. The logs shows entries sorted by Date and include information about the HTTP request, including endpoint, verb, response code as well as the request parameters/payload and response body.
The log should help with debugging of any integration issues.
To see the logs:
- Navigate to System Setup > Users > SCIM Integration tab in Brightidea.
- Scroll to the SCIM Request Log.
- Click each log entry to expand and view details
9. Troubleshooting
If you are having problem with the initial setup and with the authorization of access to the Brightidea API consider the following:
- Make sure you have a solid understanding of OAuth 2.0 as a standard. Properly configuring OAuth 2.0 is relatively straight forward process with a few steps. But it is simple only if you understand well how this network protocol works. Otherwise, misconceptions can lead you to make small errors that will make you spin into more and more confusion.
- Make sure you have read in detail the OAuth 2.0 documentation for both the IdP and the Brightidea API.
- Make sure you understand which of the various methods of authentication and authorization supported by OAuth 2.0 you are trying to setup.
-
A common source of misunderstanding is where to get the various pieces of information needed for the authentication and authorization process. Here is a breakdown of common data points, their meaning and where to find them.
- SCIM API Endpoint: This is the endpoint where the IdP will be making calls to provision SCIM resources. It is an endpoint on the Brightidea API and it can be found in the SCIM Integration page under Site Setup > Users > SCIM integration. You will typically copy this value and paste it into a corresponding field in the IdP when prompted. Copy the value as is, including the trailing slash.
- Redirect URI: This is the URL where Brightidea will redirect the user after they have entered their correct username and password during the authentication flow (basically after visiting the Authorize URL described below). This is a url under your IdP domain and it is part of a standard OAuth 2.0 flow. The url is unique to every IdP configuration, but generally follows a pattern similar to https://your_idp_domain.com/<app_identifier>/oauth/callback. This value must be determined for your specific IdP and then entered in the BrightIdea’s app registration “Edit” page (e.g. https://acme.brightidea.com/_app/edit/<app_id>). You should do this before copying the Authorize URL from Brightidea into your IdP.
- Authorize URL: This is the url that provides the authentication interface for Brightidea in order to grant access to the service app to access the API. Your IdP will redirect you to this page during the configuration of SCIM app on their end. The url is under your Brightidea instance domain and can be found in the Brightidea App “Edit” page (e.g. https://acme.brightidea.com/_app/edit/<app_id>). You will typically copy this value and paste it into a corresponding field in the IdP when prompted. Please NOTE: In order to have this URL properly formatted to copy and paste into the IdP you must first specify the correct Redirect URI (see above).
- Token URL: This is the url that allows your IdP to exchange an authorization code (obtained through the authentication flow redirect) for an actual access token to make API calls. It lives in the Brightidea domain and it does not change based on customer system instances. You can find it in the Brightidea’s app registration “edit” page (e.g. https://acme.brightidea.com/_app/edit/<app_id>). You will typically copy this value and paste it into a corresponding field in the IdP when prompted.
If you are having problems with provisioning and data synchronization, consider the following:
- Make sure you don’t have authorization problems first. The relevant screens in your IdP where you configure the SCIM provisioning and enter the authentication parameters should be filled out, saved and free of any warnings or errors. Most IdPs provide a “Test” button to check that API communication is operational in general.
- Verify that the IdP has been properly configured to specify the SCIM attributes and request payload to be sent to Brightidea. Many times IdPs will have their own set of configuration and mapping screens to craft how the payloads should be structured. Default configuration will often miss the mark and cause problems, so it must be verified.
- Make sure the integration is fully enabled for the right app and that you have explicitly enabled the right events to trigger provisioning and synchronization calls in the IdP. IdPs tend to have a lot of config levers to move before the events actually trigger.
- Verify that you can call the Brightidea API independently. For example make calls directly to the various documented Brightidea API endpoints. The SCIM endpoints follow the same authorization parameters than the rest of the Brightidea API.
- Make sure you have enabled the SCIM integration as detailed in the other sections of this guide.
- Review logs. First check the logs on the IdP side to make sure your actions in the UI are triggering the expected provisioning requests. Then got to the Brightidea SCIM Integration page and see if any requests are being logged.
- Use a proxy to intercept payloads. You can use a tool like ngrok as a proxy to the Brightidea API. Ngrok allows you to see the full request payload coming out of the IdP and inspect for any problems. You can also inspect the token being used and validate that it is authorized properly.
- Validate that the SCIM payload is valid according to the SCIM schema. At a minimum it should be valid JSON, but you can also check for SCIM 2.0 compliance with a variety of code libraries or online tools. Example: https://www.betasystems.com/scim-schema-checker
- Test by making direct API calls with the help of a software engineers. They should be able to use client API tools like Postman or Insomnia to test the Brightidea API endpoints independently from the IdP.
- Analyze the response from the API. It should respond with either an HTTP error code and message, or it may also return a 200 status code but include a payload that includes an error message.
10. Additional Support
If the issue persists, contact Brightidea Support and provide:
- Date/time of failure.
- SCIM Request Log details.
- Screenshots of your IdP configuration.
- API request/response samples if available.Brightidea offers support for SCIM (System for Cross-domain Identity Management) to enable automated provisioning and deprovisioning of users and groups from your identity provider (IdP). This guide walks administrators through the steps required to configure SCIM using your IdP (e.g. Okta. Microsoft Entra).
Comments