Enable SCIM Integration for User and Group Management

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Available from release 2021.3

Overview

When SAML is in use as the authentication method in Alation, it is also possible to enable SCIM integration to auto-synchronize users and groups between the identity provider (IdP) and Alation. With groups synchronized over SCIM, group membership does not need to be managed manually. The groups and group members (users) will be automatically pushed to Alation from the IdP by the SCIM provisioning process. Changes to group membership and user properties will be picked up and applied automatically to Alation.

Note

The System for Cross-domain Identity Management (SCIM) 2.0 is an open specification that facilitates automated management of user identities and groups between identity providers and applications using REST API. Alation supports SCIM 2.0 (RFC7643 and RFC7644) to integrate with identity providers that support SCIM.

Alation supports basic authentication (username and password) and token authentication for user and group synchronization with SCIM.

Important

SCIM 2.0 is used by Alation for managing user account properties and groups but not for authentication.

SAML must be configured as the authentication method before enabling SCIM.

Depending on the capabilities of the IdP, you may be able to use one application on the IdP side to configure both SAML authentication and SCIM provisioning or two applications specialized for these two functions.

If using two applications, note that user and group assignments should be consistent in both of them so that all group members synced over SCIM are able to log in to Alation. If a user is assigned to the SAML app but not to the SCIM app, this user account will be created in Alation, but the user will not be managed with SCIM: the automatic sync process will not be able to update user information or deactivate this user in Alation. On the other hand, if a user is assigned to the SCIM app but not to the SAML app, this user’s information will be synced to Alation, but the user will not be able to log in.

Supported SCIM Identity Providers

Supported SCIM identity providers include:

• Okta

• PingFederate

• Microsoft Azure Active Directory (Entra ID)

• SailPoint IdentityIQ

• SailPoint IdentityNow

We recommend getting the assistance of your IdP admin to perform end-to-end configuration for SCIM.

How Does Group Sync Over SCIM Work?

With SCIM enabled, the IdP manages the following lifecycle operations:

• User lifecycle management

  • Create users

  • Update user profile attributes

  • Activate or deactivate users

• Group lifecycle management

  • Create groups

  • Update group membership

  • Delete groups

Let’s assume that an admin has enabled SCIM integration for an Alation instance, and now users and groups are auto-synchronized between Alation and the IdP. SCIM enablement makes specific manual admin actions unavailable as users and groups will now be provisioned from an external application.

Review the table below for a comparison of Alation user and group management capabilities with SCIM integration enabled vs. disabled:

Actions	SAML, SCIM disabled	SAML, SCIM enabled
Users can sign up for an Alation account on the Alation login screen	No	No
Users log in from their IdP login screen or from their IdP dashboard	Yes	Yes
Admins can choose to moderate account sign-ups	Yes	No
Admins can manually activate users	Yes	No* * Except for users whose accounts are not pushed from the IdP, for example, accounts created before enabling SCIM sync
Admins can manually suspend users	Yes	No * * Except for users whose accounts are not pushed from the IdP, for example, accounts created before enabling SCIM sync
Users can manually change the Display Name under User Profile	Yes	No On hover-over, users see a message that the Display Name is supplied using an automatic process
Users can manually change the email under User Profile	Yes	No On hover-over, users see a prompt to contact their directory admin to change the email
Admins can manually create, edit, and delete a group that is Defined in Alation	Yes	Yes
Admins can manually create or delete a SCIM group	No	No
Admins can manually assign roles to groups	Yes	Yes
Admin can enable the feature Use Custom Groups to manage user suspension and activation on the Groups page **	Yes	No This feature cannot be enabled when the automatic identity management process is in use

** See Use Custom Groups to Assign User Roles for information on using custom groups for user management.

Role Assignment Using Custom Groups

SAML, SCIM enabled or disabled	Use Groups to Assign Roles disabled	Use Groups to Assign Roles enabled
Admins can manually assign roles to groups	Yes	Yes
Admins can manually assign roles to users	Yes	No

With SCIM integration enabled, Alation supports the push of users and groups from the IdP to Alation. Any consequent changes in the IdP directory will be picked up immediately or after a short period of time, depending on the configuration of the provisioning process on the IdP side.

Prerequisites

Configuration for SCIM integration is performed on both the Alation server and the IdP side. Start with configuring Alation and then perform the required configuration in your IdP.

Note

Alation Cloud Service customers can request server configuration changes through Alation Support.

SCIM integration is configured using the Django shell of the Alation server. The configurations are saved in the corresponding alation_conf parameter values and can be later viewed using alation_conf. See View SCIM Configuration in alation_conf for more information.

Note

SCIM configuration must not be performed by modifying the alation_conf parameters directly.

Before configuring, ensure the following conditions are met:

1. Your Alation instance uses SAML as the authentication method. SAML has been successfully configured and enabled. See User Authentication With SAML about configuring SAML authentication in Alation.

2. Your IdP supports SCIM 2.0, basic or token authentication for SCIM 2.0, and has a way to enable SCIM for integrations with service providers.

3. The administrator configuring SCIM must have their own or have access to a user account in Alation with the Server Admin role. This account will be used to log in, test, and complete the configuration. This account should be assigned to the SAML application integration to enable the admin user to log in. Plan which Server Admin user account you are going to test with.

4. Check if the feature Use Custom Groups to Assign User Roles is enabled on your instance. If yes, make sure that the Server Admin account you plan to use for testing the SCIM setup is in a custom group with the Server Admin role mapped to it. When SCIM is enabled, this user must be able to log in as a Server Admin.

Network Configuration

The SCIM protocol requires that your IdP should be able to access the network hosting your Alation instance. For example, if your on-premise Alation instance is installed in a network provided by AWS, GCP, or MS Azure, you may have to allow the IP address range of the IdP on your network so that the IdP can reach the Alation server using SCIM.

The configuration will differ for each network provider and each IdP. You can use the following examples:

• Allowing Okta IP Addresses

• Allowing Azure AD IP Addresses

Configure SCIM Integration

To configure SCIM integration on customer-managed instances of Alation:

• Step 1: Set Up a SCIM Client

• Step 2: Set Up SCIM Authentication

• Step 3: Enable SCIM Sync

• Step 4: Review the Configuration

• Step 5: Set Up the IdP and Test

Note

Alation Cloud Service customers can request server configuration changes through Alation Support.

Step 1: Set Up a SCIM Client

A SCIM client is an application that pushes user identity and group data to the target service provider (Alation) using SCIM API. The client initiates SCIM HTTP requests for the push.

1. Use SSH to connect to the Alation server.

2. Enter the Alation shell using the following command:

   sudo /etc/init.d/alation shell
   

2. Enter the Django shell:

   alation_django_shell
   

3. Run the command given below to set the SCIM client. Supported values for the SCIM client are:

   • okta (default)

   • pingfederate

   • one_identity

   • azure_active_directory

   • sailpoint

   Values should be provided in single quotes.

   from rosemeta.utils.users_and_groups.configuration_utils import update_scim_client
   
   update_scim_client('<identity_provider>')
   

   Example 1: Okta

   from rosemeta.utils.users_and_groups.configuration_utils import update_scim_client
   
   update_scim_client('okta')
   

   Example 2: Azure AD

   from rosemeta.utils.users_and_groups.configuration_utils import update_scim_client
   
   update_scim_client('azure_active_directory')
   

Step 2: Set Up SCIM Authentication

Set either basic authentication credentials or the access token for SCIM.

Note

Okta supports both basic authentication and token authentication. Azure AD requires token authentication.

• Token Authentication

• Basic Authentication

Token Authentication

You can create a SCIM authentication token using the Alation UI. The token’s expiration can be from one to six months. You can create a new token at any time, which will immediately revoke the old token.

1. In Alation, go to Admin Settings > Authentication.

2. Find the SCIM Token section.

   

3. To create a new token, click the dropdown to select how long the token will be valid.

   

4. Click Generate Token. A pop-up window appears with the new token.

   

5. Click Copy and save the token in a secure location. It will be required later when you configure SCIM integration on the IdP side.

   Important

   The token will never be displayed again. It is not stored in Alation. Once you close the dialog, you will not be able to access it again in Alation. If needed, you can generate a new token.

6. Once you’ve saved the token, click Close.

Basic Authentication

Run the commands given below from the Alation Django shell to set basic authentication credentials for the SCIM service account to be used by the IdP to authenticate with Alation. Values should be provided in single quotes.

Important

The password must be longer than 16 characters. It must contain alphanumeric characters and at least one special character. Setting up this service account does not create a user in Alation. These credentials cannot access Alation and will only be used for authentication by the SCIM client. They do not have to map to an existing Alation user.

from rosemeta.utils.users_and_groups.configuration_utils import set_scim_basic_auth_username

from rosemeta.utils.users_and_groups.configuration_utils import set_scim_basic_auth_password

set_scim_basic_auth_username('your_username')

set_scim_basic_auth_password('your_password')

Example:

set_scim_basic_auth_username('scim_account_username@alation.com')

set_scim_basic_auth_password('scim_account_password_12345&&')

Record the username and password and store them safely. They will be required later when you configure SCIM integration on the IdP side.

Note

Alation does not enforce changing the password of the SCIM service account. If necessary, change the password at regular intervals according to the security policy at your company.

Step 3: Enable SCIM Sync

SCIM sync is an automatic process that keeps groups and users in the IdP and Alation synchronized. Enabling it means that user and group management in Alation will be controlled by this automatic process. It will disable sign-up moderation and some other admin features: see How Does Group Sync Over SCIM Work? for more information.

To enable SCIM sync, run these commands from the Django shell:

from rosemeta.utils.users_and_groups.configuration_utils import enable_scim_user_and_group_sync

enable_scim_user_and_group_sync()

Step 4: Review the Configuration

Review your configuration and verify that it’s correct.

1. To review the configuration:

   from rosemeta.utils.users_and_groups.configuration_utils import check_if_scim_sync_is_enabled
   
   check_if_scim_sync_is_enabled()
   
   from rosemeta.utils.users_and_groups.configuration_utils import get_scim_client
   
   get_scim_client()
   

2. To review the basic authentication credentials:

   from rosemeta.utils.users_and_groups.configuration_utils import get_scim_basic_auth_info
   
   get_scim_basic_auth_info()
   

3. To review the token:

   from rosemeta.utils.users_and_groups.configuration_utils import get_scim_bearer_token
   
   get_scim_bearer_token()
   

4. Exit the Django shell: exit

5. Exit the Alation shell: exit

Step 5: Set Up the IdP and Test

Complete the setup on the IdP side:

• Set Up SCIM Integration in Okta

• Set Up SAML and SCIM Integration in PingFederate

• Set Up SAML and SCIM Integration in Azure AD

• Set Up SCIM Integration in SailPoint IdentityIQ

• Set Up SCIM Integration in SailPoint IdentityNow

Once the IdP is set up, Test SCIM Configuration.

User Attributes Managed with SCIM

Once SCIM sync is enabled, user lifecycle management is handled through SCIM APIs. User lifecycle management refers to the administrative actions that correspond to the stages of a user’s presence in the organization. Common lifecycle events include:

• Creating a user

• Updating user profile attributes, including username, first_name, last_name, email, and displayName

• Activating or deactivating a user

Alation supports a limited set of user attributes: username, first_name, last_name, email, displayName, and status. Alation does not support the title attribute or multi-valued user attributes. For example, only one email address is supported.

Note

Group membership must be managed through the SCIM group sync rather than through user attributes.

SCIM User Attribute	Alation User Attribute	Type	Description
id	scim_user.scim_user_uuid	UUIDField	The unique identifier of the user between Alation and the IdP.
userName	auth_user.username	string	The username the user uses to log in. Alation user table username field. Note: username in Alation must be unique, is case-sensitive, and has a maximum length of 150 characters.
name.givenName	auth_user.first_name	string	The first name of the user. Note: first_name maximum length is 150 characters.
name.familyName	auth_user.last_name	string	The last name of the user. Note: last_name maximum length is 150 characters.
emails	auth_user.email	array (multi-valued)	Alation accepts the standard SCIM emails array but stores only a single email address. The primary email is preferred; if no primary is flagged, the first entry (alphabetically) is used. The maximum length of the stored email is 254 characters.
displayName	userprofile.display_name	string	The name displayed for the user in the user interface. The maximum length of display_name is 200 characters.
active	auth_user.is_active and userprofile.is_suspended	Boolean	Indicates whether the user is active in Alation. When set to false, the user is disabled and cannot log in to Alation. Note that the get_scim_group_members_by_group_id method filters members to only return users where is_active=true and is_suspended=false. This means suspended or deactivated users silently disappear from group membership responses.
groups	Computed from the SCIM user’s group memberships	array (multi-valued, read-only)	Returns the SCIM groups a user belongs to. Each entry contains value (group UUID) and $ref (group URL). Read-only, as group membership is managed via the Groups endpoint, not the Users endpoint.
members[].type	N/A (hardcoded)	string	Always returns user. Alation does not support nested groups, so group-type members are not included.

Group Attributes Managed with SCIM

Once SCIM sync is enabled, group lifecycle management is handled via SCIM APIs. Group lifecycle management refers to the administrative actions that correspond to the stages of a group’s existence in the organization. Common lifecycle events include:

• Creating a group

• Updating a group’s distinguished name

• Updating group membership for users

• Deleting a group

Alation supports a limited set of group attributes: displayName and members.

Alation does not support provisioning nested groups. If a group member is of type Group, Alation ignores that membership during provisioning.

SCIM Group Attribute	Alation Group Attribute	Type	Description
id	scim_group.scim_group_uuid	UUIDField	The unique identifier of the group between Alation and the IdP.
displayName	rosemeta_externaldirectorygroup.external_unique_name	string	The name for the external IdP group. Note: external_unique_name in Alation must be unique, is case-sensitive, and has a maximum length of 1000 characters. In Okta, the displayName attribute has a maximum length of 255.
members.value	scim_user.scim_user_uuid	string	The UUID value of the user who is a member of the group.

Disable SCIM Sync

You can stop syncing users and groups over SCIM at any time.

Note

Alation Cloud Service customers can request server configuration changes through Alation Support.

For customer-managed instances of Alation, you can stop syncing users and groups over SCIM by following these steps:

1. On the Alation host, enter the Alation shell and enter the Django shell:

   sudo /etc/init.d/alation shell
   
   alation_django_shell
   

2. In the Django shell, run the code given below to disable SCIM sync on the Alation instance:

   from rosemeta.utils.users_and_groups.configuration_utils import disable_sync_from_directory_provider
   
   disable_sync_from_directory_provider()
   

Disabling SCIM sync does not revert any synced user and Group data. It only stops the automatic synchronization between Alation and the IdP.

Changing the SCIM Provider

In rare cases, an organization may need to switch to a different IdP. The user and group records synced from the previous IdP will have to be cleaned up before changing the SCIM client configuration on the Alation server.

User and group records will not be cleaned up automatically. Contact Alation Support for assistance.

Alation provides a script to clean up the old records.

Troubleshooting

For error messages and troubleshooting tips, see Troubleshooting SCIM Configuration.

Review SCIM Configuration

SCIM configuration values are stored in alation_conf. While it is not recommended to modify SCIM configuration values directly through alation_conf, on-premise administrators can review the configuration values using alation_conf. Find more information in View SCIM Configuration in alation_conf.

SCIM Logging

SCIM operations are logged in the following files:

• site/logs/scim-debug.log: Detailed lifecycle events such as user and group synchronization

• site/logs/scim-info.log: Authentication failures and configuration errors

• site/logs/scim-error.log: Unexpected exceptions during SCIM operations

If SCIM synchronization fails, on-premise administrators can review the debug log for details.

Refer to Logs Overview for information about Alation logs.