Troubleshooting SCIM Configuration

Applies from release 2021.3

Logs

SCIM-related API calls are logged at different logger levels (Debug, Info, and Error) in different files in site/logs/ (path inside the Alation Chroot):

  • scim-error.log: Logs the unexpected exceptions

  • scim-info.log: SCIM configuration errors and exceptions, authentication errors, and received API requests.

  • scim-debug.log: application behaviors pertaining to user lifecycle and group lifecycle.

Checking the Configuration

View SCIM Credentials

The currently set SCIM service account credentials can be viewed from the Alation Django shell. To view the service account credentials for SCIM:

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

    sudo etc/init.d/alation shell
alation_django_shell

  2. From the Django shell, run the following code:

    from rosemeta.utils.users_and_groups.configuration_utils import get_scim_basic_auth_info

get_scim_basic_auth_info()

This will print the credentials to the console.

View SCIM Configuration

SCIM configuration values are saved in alation_conf. To check the currently set values, you can use the alation_conf command and the corresponding parameter name: Viewing SCIM Configuration in alation_conf.

Allowing Okta IP Addresses

Issue in Okta

In the Okta user interface, when testing the connection between Alation and Okta during SCIM configuration, the following error occurs:

Error Authenticating: Null

Solution

  1. Check the basic authentication username and password saved within Django.

  2. Check the SCIM-related information in the SCIM application.

  3. Check alation-debug.log for any authentication-specific errors.

If none of the above checks renders a solution, this may be a network issue. The SCIM protocol requires network access to the Alation instance in order to send user and group packages to the corresponding REST API endpoint. To allow Okta to reach Alation, you need to allow access from the Okta IP address range relevant to your region to the network hosting the Alation server. Refer to the following Okta documentation for more details:

Test the connection again after you have enabled network access from the Okta IP addresses.

Allowing Azure AD IP Addresses

Issue in Azure AD

In the Azure portal interface, when testing the connection between Alation and the Azure application during SCIM configuration, the following error occurs:

Error code: systemForCrossDomainIdentitiyManagementCredentialValidationUnavilable
Details: We received this unexpected response from your application:
Message: An error occurred while sending the request

Solution

  1. Check the basic authentication username and password saved within Django.

  2. Check the SCIM-related information.

  3. Check alation-debug.log for any authentication-specific errors.

If none of the above checks renders a solution, this may be a network issue:

  • The Alation server in your network does not allow traffic from Azure AD

  • Azure AD cannot resolve the DNS of the SCIM endpoint of the Alaiton server.

You need to ensure that the network policy in your network allows access from the Azure AD IP addresses for the Azure public cloud.

Find the Azure AD IP Range

The Azure AD provisioning service currently operates using the IP ranges for Azure Active Directory as listed in Azure IP Ranges and Service Tags – Public Cloud.

Important

The IPs in this list change every week. Alation strongly recommends adding an automation to regularly refresh the IPs in the load balancer security group.

In the file you download from Azure, find the AzureActiveDirectory tag and the IPs listed under this tag. The screenshot below shows an example of the IP address range as can be seen in the file.

../../_images/SCIM_sync_prereq.png

Add Azure IPs to the Security Group of the Load Balancer

To allow traffic from the Azure AD provisioning service to the Alation server on your network, add the Azure IP range for AzureActiveDirectory to the security group of the load balancer of the network that hosts the Alation server.

After the IPs are added the connection test should be successful.

If not, this could be a DNS issue. Azure should be able to resolve the REST API endpoint of the Alation instance used by SCIM. This endpoint follows this format: https://mycatalog.alationdata.com/scim/v2/. Use the tips below to check if Azure AD can reach Alation.

Check if Azure AD Can Access Alation

Run dig <alation server name> from the Azure AD network to check if it can access the Alation server.

The screenshot below shows the output when we are not able to get an IP for the DNS name.

../../_images/SCIM_sync_prereq2.png

If you get a similar output, this may be due to the fact that the server can only be accessed through the internal VPN. Compare the output that shows that the DNS is successfully resolved and that returns IP addresses:

../../_images/SCIM_sync_prereq3.png

The solution will be specific to your network configuration. You can also contact Alation Support to help find a solution.

Error Messages

Alation follows exception handling as prescribed in the SCIM specification that defines exception types. Use the table below to interpret exceptions found in the logs.

Symptoms

Example of Error Message

Cause

Resolution

Admin changes a username in the IdP but the change is not reflected in Alation after the SCIM push

Exception - Integrity: Can’t update username to <username>, user with that name already exists

The username was updated to a username that already exists in Alation

Change the username to a username value that does not exist in Alation

Admin does not see a user in the SCIM group in Alation

An update to a user profile is not reflected in Alation

Un-assigning a user from the SCIM app did not deactivate this user in Alation

Exception - NotFound: Not found user by identifier <uid>

The user with UUID <uid> is not found in Alation.

Re-assign the user to the SCIM app in the IdP

Users are not synced to Alation

Exception - InvalidValue: Required userName field is missing

The userName field is missing

Set userName as user resource identifier in the IdP

Admin changes a Group name in the IdP but this change is not reflected in Alation after the SCIM push

Exception - Integrity: Can’t update displayName to <name>, group with that name already exists

The displayName of a Group is updated to a name which already exists in Alation

Change the group displayName to a value that does not exist in Alation

Admin does not see a SCIM group in Alation

DisplayName updated in the IdP for a group is not updated in Alation

Updated group members are not updated in Alation

Exception - NotFound: Not found group by identifier <uid>

The group with UUID <uid> is not not found in Alation

Re-push the group in the IdP

Authentication errors

Exception - UnAuthorized: Authentication credentials were not provided

Exception - UnAuthorized: Authentication Failed for user <user> Incorrect username or password

Username and password set up in Alation for the SCIM client and the credentials provided for SCIM Basic Auth in the IdP do not match

Check the SCIM client credentials in both Alation and the IdP. Make sure they match

Bad API request errors

Sync from directory provider flag is off or protocol flag is not SCIM on the Alation server. Please make sure enable sync from directory provider flag and choose SCIM as protocol

SAML authentication mode is disabled at Service Provider (Alation). Please use SAML authentication method in Alation

SCIM sync is not enabled

Enable SCIM sync in the Alation Django shell

Filter query errors

Exception - InvalidFilter: Incorrect filtering format. More info <…>

Exception - InvalidFilter: Invalid filter operation or unsupported operator. Supported operation: [‘eq’]

Exception - InvalidFilter: Invalid filter attribute. Only support userName for users and displayName for groups.

Filtering users or groups resource format is incorrect

Verify the resource format set in the IdP or raise a Support ticket for Alation to review the errors and propose a solution

PATCH method Bad request

Exception - BadRequest: PATCH call made without operations array

Exception - InvalidFilter: Unknown PATCH op

Exception - InvalidFilter: “value” must be specified during “add” PATCH calls

Exception - NoTarget: “path” must be specified during “remove” PATCH calls

The patch request does not follow the SCIM specification or is not supported by Alation

Verify the IdP settings or raise a Support ticket for Alation to review the errors and propose a solution