Manage Token Authentication for SCIM Sync

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Applies from version 2021.4

Alation supports token authentication when syncing user and group information over SCIM. Token authentication can be configured during SCIM setup for an Alation instance. See Configure SCIM Integration about the end-to-end configuration of SCIM sync.

Token Lifespan

In 2023.3.2 and later, SCIM the token’s expiration can be anywhere from one to six months. You can create a new token at any time, which will immediately revoke the old token.

In 2023.3.1 and earlier, SCIM authentication tokens have a lifespan of 6 months. The expiration period cannot be customized: a token lasts for 6 months and expires. After 6 months, a new token needs to be created.

You do not have to wait for the token to expire to renew it. If you require a shorter expiration period for authentication tokens, you can create a new token after the desired period of time.

Important

After renewing the token on the Alation server, update the token value in the properties of the SCIM application in your IdP.

Token Expiration Notifications

In 2023.3.2 and later, all Server Admins will be notified when the SCIM token has expired or is about to expire.

Email Notifications

Server Admins will get an email at the following times:

• 15 days before the token expires

• 1 day before the token expires

• The day the token expires

• The day after the token expires

Banner Notification

Fifteen days before the token expires, a banner notification will appear at the top of the Alation catalog. The banner will keep appearing until the token is regenerated or the SCIM feature is disabled. Only Server Admins will see the banner.

Retrieve the Expiration Date of the Current Token

2023.3.2 and Later

Starting in 2023.3.2, the expiration date of the current token can be viewed in the Alation UI.

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

2. Find the SCIM Token section. If there’s already a token, you’ll see its expiration date.

   

2023.3.1 and Earlier

In 2023.3.1 and earlier, you must have access to the Alation server to get the token’s expiration date.

Note

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

To get the expiration date for the current token:

1. Use SSH to connect to the Alation server.

2. Enter the Alation shell using the following command:

   sudo /etc/init.d/alation shell
   

1. Enter the Django shell:

   alation_django_shell
   

4. In the Django shell, run:

   try:
       from scim.configuration import *
   except ImportError:
       print("Note: scim.configuration not found; using defaults.")
   
   try:
       from api_authentication.public.config import *
   except ImportError:
       print("Note: api_authentication.public.config not found; using defaults.")
   
   try:
       from rosemeta.utils.users_and_groups.configuration_utils import *
   except ImportError:
       print("Note: configuration_utils not found; using defaults.")
   
   try:
       from scim.public.config import *
   except ImportError:
       print("Note: scim.public.config not found; using defaults.")
   
   get_scim_bearer_token_expiry_date()
   

This will output the expiration date of the current token in UTC.

Replace an Existing Token

You can create a new token at any time, which will immediately revoke the old token.

2023.3.2 and Later

Starting in 2023.3.2, you can create a SCIM token using the Alation UI.

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

2. Find the SCIM Token section. If there’s already a token, you’ll see its expiration date.

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

4. Click Generate Token. A popup window with a caution appears when you replace an existing or expired token.

5. Click Continue to generate a new token with a new expiration date.

6. 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.

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

Note

The User & Group Sync page consolidates SCIM setup in one place. These steps cover only token generation. For the full setup procedure, including enabling directory sync and selecting an identity provider, see Configure SCIM User and Group Sync.

1. In Alation, go to Admin Settings, then User & Group Sync.

2. Under Authentication, select Bearer Token.

3. Click Generate Token. A popup window with a caution appears when you replace an existing or expired token.

4. Click Continue to generate a new token with a new expiration date.

5. Click Copy token 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. Click Update IdP Configuration to open a step-by-step guide for updating this token in your identity provider. For details, see Update the Token in Your Identity Provider.

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

2023.3.1 and Earlier

In 2023.3.1 and earlier, you must have access to the Alation server to create a new token.

Note

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

To create a new token:

1. Use SSH to connect to the Alation server.

2. Enter the Alation shell using the following command:

   sudo /etc/init.d/alation shell
   

1. Enter the Django shell:

   alation_django_shell
   

2. Run the following code from the Django shell:

   try:
       from scim.configuration import *
   except ImportError:
       print("Note: scim.configuration not found; using defaults.")
   
   try:
       from api_authentication.public.config import *
   except ImportError:
       print("Note: api_authentication.public.config not found; using defaults.")
   
   try:
       from rosemeta.utils.users_and_groups.configuration_utils import *
   except ImportError:
       print("Note: configuration_utils not found; using defaults.")
   
   try:
       from scim.public.config import *
   except ImportError:
       print("Note: scim.public.config not found; using defaults.")
   
   set_scim_bearer_token()
   

   This sets a new SCIM authentication token on the Alation server.

Update the Token in Your Identity Provider

Available in the new Alation experience (Neo) only

After you generate a new SCIM token on the User & Group Sync page, click Update IdP Configuration to open a guide with step-by-step instructions for updating the token in your identity provider (IdP). The guide shows different steps depending on the IdP you have configured, and displays the new token with a Copy token button so you can copy it again if needed.

To work through the guide:

1. Complete the steps shown for your IdP, described below.

2. Select the checkbox next to each step once you’ve completed it in your IdP.

3. Once you’ve checked every step, the guide displays a confirmation message that your IdP should now be using the new token.

4. Click Done to close the guide.

Okta

1. Access the Okta admin console and open Applications. In the guide, click Open Okta Console to open it directly.

2. Find the SCIM application configured for Alation.

3. On the Provisioning tab, select API Integration, then update the Bearer Token field with the new token.

4. Click Test API Credentials to verify the new token is working.

Azure Active Directory

1. Access Azure Portal: Log in to the Azure Portal and navigate to Azure Active Directory > Enterprise Applications. Click Open Azure Active Directory Console in the guide to go there directly.

2. Find Your Alation Application: Locate the enterprise application configured for Alation SCIM provisioning.

3. Update Secret Token: Go to Provisioning > Admin Credentials. Update the Secret Token field with the new token.

4. Save and Test: Save the configuration and click Test Connection to verify the new token works.

OneLogin

1. Access OneLogin Admin Portal: Log in to your OneLogin admin portal and navigate to Applications. Click Open OneLogin Console in the guide to go there directly.

2. Find Your Alation SCIM Connector: Locate the SCIM connector application configured for Alation.

3. Update Bearer Token: Go to the Configuration tab and update the Bearer Token field with the new token.

PingFederate, SailPoint, and Other Identity Providers

For PingFederate, SailPoint, and any other IdP, the guide shows generic steps instead of provider-specific ones:

1. Access Your IdP Admin Console: Log in to your identity provider’s administrative interface.

2. Find SCIM Configuration: Navigate to the SCIM provisioning or user synchronization settings for Alation.

3. Update Authentication Token: Replace the existing bearer token or API token with the new token generated above.

Note

Click View Documentation in the guide for help resources specific to your IdP:

• Okta and Azure Active Directory link to Alation’s own setup guides: Set Up SCIM Integration in Okta and Set Up SAML and SCIM Integration in Microsoft Entra ID.

• PingFederate and SailPoint also link to Alation’s own setup guides, even though their steps above are generic: Set Up SAML and SCIM Integration in PingFederate and Set Up SCIM Integration in SailPoint IdentityIQ.

• OneLogin links to OneLogin’s own developer documentation.

• Any other IdP links to the SCIM protocol specification (RFC 7644).

Retrieve the Current Token Value

To retrieve the current token value, you must have access to the Alation server.

1. Use SSH to connect to the Alation server.

2. Enter the Alation shell using the following command:

   sudo /etc/init.d/alation shell
   

1. Enter the Django shell:

   alation_django_shell
   

2. Run the following code from the Django shell:

   try:
       from scim.configuration import *
   except ImportError:
       print("Note: scim.configuration not found; using defaults.")
   
   try:
       from api_authentication.public.config import *
   except ImportError:
       print("Note: api_authentication.public.config not found; using defaults.")
   
   try:
       from rosemeta.utils.users_and_groups.configuration_utils import *
   except ImportError:
       print("Note: configuration_utils not found; using defaults.")
   
   try:
       from scim.public.config import *
   except ImportError:
       print("Note: scim.public.config not found; using defaults.")
   
   get_scim_bearer_token()