Authentication Configuration Methods for External Systems¶

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Applies from version 2022.3

For data sources that support authentication with external systems, Server Admins can create the required authentication configurations on the Admin Settings > Authentication page.

Configurations can be created for the AWS IAM, AWS Secrets Manager, Azure Keyvault, HashiCorp Vault, and OAuth authentication methods. These methods generally require preliminary configuration in the relevant external systems. For detailed help, see the dedicated topics below:

If you are configuring SSO authentication in Compose for a data source, refer to the specific data source documentation to learn which external configuration method to use.

To configure OAuth authentication or to create a new configuration after completing the preliminary configuration in the relevant external system, you can use the instructions below.

Create a New Configuration¶

To create a new configuration:

Log in to your Alation instance as a Server Admin.
Click the Admin Settings gear icon on top right to open the Admin Settings page.
Click Authentication to open the Authentication tab. Locate the section Authentication Configuration Methods for External Systems.
If you’re on a customer-managed (on-prem) instance of Alation, skip to the next step.

If you’re on an Alation Cloud Service instance, click the drop-down menu next to See configurations for to choose the location of the configuration:
- Choose Alation Cloud Service to create the authentication configurations for Alation Cloud Service itself.
- Choose the name of an Alation Agent to create the configuration for an Agent. An Agent name will only be listed if you’ve installed the Authentication Service Add-on on that Agent.
Click the Add Configuration button to the right of the section title to expand the list of options and then click the name of the appropriate plug-in. The corresponding settings page will open in a new browser tab.
On the configuration method editor page, fill in the appropriate information. For an explanation of the required and optional fields for each of the authentication methods, see the following sections:
Note

When creating a new configuration, you can switch between the plug-in types using the Method list. After saving a configuration, the Method field becomes read-only.
After populating the fields, click Save to save the configuration. If you get an error while saving, see the Troubleshooting section for help.
Refresh the Authentication page. The new configuration will be displayed in the table.
Continue the configuration in the data source settings. You will need to associate your specific data source with the configuration you created under Authentication Configuration Methods for External Systems. The steps to configure a data source depend on the database type. Follow the relevant connector documentation to complete this configuration.

Troubleshooting¶

Something Went Wrong¶

In some rare cases, you may see the Something went wrong error on the Authentication page or in the configuration editor when saving a configuration.

This error may indicate that AuthService has been stopped. To resolve this issue, check the status of AuthService and restart it. For information about starting AuthService, see, for example, Enable AuthService.

Changes Unsaved¶

The Changes unsaved error message may appear after clicking the Save button on the configuration editor page.

This error means that some fields do not pass validation. Make sure you enter the values in the required format.

AWS IAM¶

Use this section to review the information you will need to provide in the Alation user interface when configuring authentication for your data source with AWS IAM.

Field	Required?	Description
Config Name	Yes	A name for the configuration that is being created. The Config Name value will be used to identify and manage the corresponding configuration on the Alation server. The Config Name has the following restrictions: Can’t be edited after saving the configuration. Should be unique. Can’t use any of the reserved config names. See Reserved Config Names below. Shouldn’t be present in the `excluded_configs_in_auth_ui` alation_conf parameter. See Blocking Config Names below. Has a maximum length of 250 characters.
STS Duration	Yes	The lifetime of the temporary credentials generated by the AWS STS service (in seconds). You can provide a value from 900 seconds (15 minutes) up to the maximum of 43200 seconds (12 hours).
Region	Yes	The AWS region of the AWS account used for authentication. This field is a list containing all supported AWS regions.
Cred Type	No	Type of authentication to use when the AWS `AssumeRole` API operation of the authentication flow assumes a role. Supported values: `instance_profile` — Use `instance_profile` when configuring extraction from AWS data sources. This choice relies on permissions associated with the EC2 instance role. `credentials` — Use `credentials` when configuring authentication for Compose. This choice relies on the IAM user credentials.
SAML authenticate request XML	No	The request XML to be used for SAML authentication.
Multi role flow	No	Indicates if multiple roles may be returned in the SAML response. Selected by default.
Encode Relay State	No	Indicates if the relay state needs to be encoded.
Redirect URL	No	The redirect URL for the identity provider. Mandatory if the configuration is used for SAML authentication. This should be a valid URL.
Entity Id	No	A string value that represents the Entity ID used in the <Issuer> element of the <AuthNRequest>. This value is usually used when the same Alation instance is authenticated against different IdP endpoints. Uses the default of `https://www.alation.com` if this field is not populated. This value should be a valid URL.

AWS Secrets Manager¶

Applies from version 2023.1.5

Use this section to review the information you will need to provide in the Alation user interface when configuring integration with AWS Secrets Manager for authentication to your data source.

Field	Required?	Description
Config Name	Yes	A name for the configuration that is being created. The Config Name value will be used to identify and manage the corresponding configuration on the Alation server. The Config Name has the following restrictions: Can’t be edited after saving the configuration. Should be unique. Can’t use any of the reserved config names. See Reserved Config Names below. Shouldn’t be present in the `excluded_configs_in_auth_ui` alation_conf parameter. See Blocking Config Names below. Has a maximum length of 250 characters.
Region	Yes	The AWS region of the Secrets Manager service. This field is a list containing all supported AWS regions.
Authentication Type	Yes	Type of authentication to use. Supported values: IAM User (iam_user on versions before 2024.1.1): User credentials must be provided and the user should have read access to AWS Secrets Manager. IAM Role (iam_role on versions before 2024.1.1): - The role attached to Alation’s EC2 instance will assume the given role that has access to AWS Secrets Manager. - The given role will be assumed on behalf of a user if the credentials of the user `AWS Access Key` and `AWS Secret Key` are provided. IAM Instance Profile (on Alation Cloud Service version 2024.1.4 or later, if an Alation Agent has the Auth Service plugin installed): A role has read access to AWS Secrets Manager and is attached to the Alation Agent EC2 machine. IAM User Profile (on Alation Cloud Service version 2024.1.5 or later, if an Alation Agent has the Auth Service plugin installed): A user has read access to AWS Secrets Manager and their keys are stored on the Alation Agent machine.
Profile Name	Yes, if authentication type is IAM User Profile.	Name of the profile defined on the Alation Agent machine. See Integrate Agent with Secrets Manager Using IAM User Credentials for help setting up this type of integration.
AWS Access Key	Yes, if authentication type is IAM User.	AWS Access Key
AWS Secret Key	Yes, if authentication type is IAM User.	AWS Secret Key
Role ARN	Yes, if authentication type is IAM Role.	Amazon Resource Name (ARN) of the role to be assumed.5cm
External ID	Yes, if authentication type is IAM Role.	External ID passed during the Assume Role operation. The external ID is needed to avoid the confused deputy problem*.
STS Duration	Yes, if authentication type is IAM Role.	The lifetime of the temporary credentials generated by the AWS STS service (in seconds). You can provide a value from 900 seconds (15 minutes) up to the maximum of 43200 seconds (12 hours).

* See this AWS documentation for more information on the confused deputy problem.

Azure Keyvault¶

Use this section to review the information you will need to provide in the Alation user interface when configuring authentication for extraction from your data source with Azure AD and Azure Keyvault.

Field	Required?	Description
Config Name	Yes	A name for the configuration that is being created. The Config Name value will be used to identify and manage the corresponding configuration on the Alation server. The Config Name has the following restrictions: Can’t be edited after saving the configuration. Should be unique. Can’t use any of the reserved config names. See Reserved Config Names below. Shouldn’t be present in the `excluded_configs_in_auth_ui` alation_conf parameter. See Blocking Config Names below. Has a maximum length of 250 characters.
Client Id	Yes	The client ID value of the Azure AD application.
Client Secret	Yes	The client secret value of the Azure AD application.
Tenant Id	Yes	The tenant ID value of the Azure AD application.
Vault URL	Yes	The URL to access the Azure key vault. This should be a valid URL.

HashiCorp Vault¶

Applies from version 2025.1.1

Use this section to review the information you will need to provide in the Alation user interface when configuring authentication for your data source with HashiCorp Vault.

Field	Required?	Description
Config Name	Yes	A name for the configuration that is being created. The Config Name value will be used to identify and manage the corresponding configuration on the Alation server. The Config Name has the following restrictions: Can’t be edited after saving the configuration. Should be unique. Can’t use any of the reserved config names. See Reserved Config Names below. Shouldn’t be present in the `excluded_configs_in_auth_ui` alation_conf parameter. See Blocking Config Names below. Has a maximum length of 250 characters.
Vault URL	Yes	The URL to access the HashiCorp Vault. This should be a valid URL.
Authentication Type	Yes	Type of authentication to use. Supported values: LDAP: An LDAP user’s credentials must be provided, and the user should have policies to be able to read the needed secrets. AppRole: The AppRole auth method typically is meant for machines or apps to authenticate with Vault. AppRole credentials (role_id and secret_id) can be fetched from Vault CLI. The AppRole must have policies to be able to read the needed secrets.
Secret Path for test connection	Yes	Path of a secret that is used to test connection. Must be of the below format: For `kv` v1: `<secrets-engine-mount-path>/<path-to-secret>/<secret-name>` For `kv` v2: `<secrets-engine-mount-path>/data/<path-to-secret>/<secret-name>` For PKI: `pki/cert/<certificateName>`
Username	Yes, if authentication type is LDAP	Username used in LDAP authentication.
Password	Yes, if authentication type is LDAP	Password used in LDAP authentication.
Role ID	Yes, if authentication type is AppRole	Role ID used in AppRole based authentication.
Secret ID	Yes, if authentication type is AppRole	Secret ID used in AppRole based authentication.

OAuth¶

Use this section to review the information you will need to provide in the Alation user interface when configuring authentication for your data source with Azure AD using the OAuth protocol.

Field	Required?	Description
Config Name	Yes	A name for the configuration that is being created. The Config Name value will be used to identify and manage the corresponding configuration on the Alation server. The Config Name has the following restrictions: Can’t be edited after saving the configuration. Should be unique. Can’t use any of the reserved config names. See Reserved Config Names below. Shouldn’t be present in the `excluded_configs_in_auth_ui` alation_conf parameter. See Blocking Config Names below. Has a maximum length of 250 characters.
Client Id	Yes	The client ID of the Azure AD application.
Client Secret	Yes	The client secret of the Azure AD application.
Scope	Yes	The scope of the request. Some examples can be `openid`, `email`, `profile`, and `offline_access`.
Subject	No	This field indicates which claim in the token should be used as username, for example: `unique_id` or `name`.
Token Buffer time	No	Buffer time to check the token validity before it expires so that the token can be refreshed before expiration. Set in minutes. Default: five minutes (`5`). Allowed values: one through ten minutes (`1 - 10`).
Grant Type	No	Grant types: `auth_code` — Default. The default value is used if the field is not populated. Use this grant type if you are creating a configuration for a user-initiated authentication flow, such as authentication to a data source from Compose. `credentials_flow` — Use this grant type if you are creating a configuration for authentication on the database for extraction of metadata.
PKCE Verifier	No	Enable or disable Proof Key for Code Exchange in your authentication flow. Default: enabled.
Authorize Endpoint URL	Yes	The Authorize Endpoint URL for the identity provider. This should be a valid URL.
Redirect URL	Yes	Redirect URL for the identity provider. This should be a valid URL.
Token Endpoint URL	Yes	Token URL for the identity provider. This should be a valid URL.
User Info Endpoint URL	Yes	User Info Endpoint URL for the identity provider. This should be a valid URL.

Reserved Config Names¶

On the Alation server, there are Config Names that are reserved and cannot be used when creating new configurations. These values are stored in these two alation_conf parameters:

alation.authentication.oidc.authservice_plugin_config = oauth_login_config

alation.authentication.oidc.authservice_plugin_test_config = oauth_login_test_config

Blocking Config Names¶

It is possible to block the creation of new configurations with specific names in the user interface or to hide existing configurations with specific names from the user interface. To prevent a configuration with a specific name from being created or visible, use the parameter alation.authentication.excluded_configs_in_auth_ui in alation_conf. The configurations with the names added to the list of values of this parameter, will not be visible in the Authentication Configuration Methods for External Systems table. Also, users will not be able to create a new configuration with any of the listed names.

Note

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

On how to use alation_conf, see Using alation_conf. The Django server restart is required if the value of alation.authentication.excluded_configs_in_auth_ui is changed.

alation_supervisor restart web:*

View or Edit a Configuration¶

You can view and edit the settings of existing configurations. To view or edit a configuration:

Log in to your Alation instance as a Server Admin.
Click the Admin Settings gear icon on top right to open the Admin Settings page.
Click Authentication to open the Authentication tab. Locate the section Authentication Configuration Methods for External Systems.
If you’re on a customer-managed (on-prem) instance of Alation, skip to the next step.

If you’re on an Alation Cloud Service instance, click the drop-down menu next to See configurations for to choose the location of the configuration:
- Choose Alation Cloud Service to see authentication configurations that have been created for Alation Cloud Service itself.
- Choose the name of an Alation Agent to see configurations for an Agent. An Agent name will only be listed if you’ve installed the Authentication Service Add-on on that Agent.
Note

If any configurations already exist, you’ll see them listed in the table under Authentication Configuration Methods for External Systems. If they were created on the Alation server backend in a previous release, the columns Created At, Created By, Updated By, and Updated At will contain the value Not Set. These fields only capture the changes made in the user interface. For new configurations created in the user interface, these columns will be populated. For the configurations created on the server backend, the Updated At column will be populated if edits are made to the configuration in the user interface.
In the Authentication Configuration Methods for External Systems table, click View/Edit for the configuration you want to view or edit. The configuration editor page will open in a new browser tab. For an explanation of the required and optional fields for each of the authentication methods, see the following sections:
Edit the values as necessary.

Note

The fields Methods and Config Name cannot be changed.
Click Save.

Delete a Configuration¶

It is possible to delete existing configurations. Currently, Alation does not validate if the configuration that is being deleted is in use in the application. Before deleting a configuration, make sure it is not associated with any data sources by checking the settings of your data sources. To delete:

Log in to your Alation instance as a Server Admin.
Click the Admin Settings gear icon on top right to open the Admin Settings page.
Click Authentication to open the Authentication tab. Locate the section Authentication Configuration Methods for External Systems.
If you’re on a customer-managed (on-prem) instance of Alation, skip to the next step.

If you’re on an Alation Cloud Service instance, click the drop-down menu next to See configurations for to choose the location of the configuration:
- Choose Alation Cloud Service to see authentication configurations that have been created for Alation Cloud Service itself.
- Choose the name of an Alation Agent to see configurations for an Agent. An Agent name will only be listed if you’ve installed the Authentication Service Add-on on that Agent.
In the Authentication Configuration Methods for External Systems table, click Delete for the configuration you want to delete.
In the delete confirmation dialog that pops up, click Delete to confirm your action. The configuration will be deleted.