> For the complete documentation index, see [llms.txt](https://docs.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.collibra.com/data-quality-self-hosted/security-configuration/saml-authentication/configuring-saml-authentication.md).
# Configuring SAML authentication
You can integrate Data Quality & Observability (self-hosted) with an existing SAML solution and have your application act as a service provider. Once you set up the environment variables, you can access and configure SAML security settings as an administrator in the SAML Setup section of the Admin Console.
## 1. Set the SAML authentication properties
Before configuring SAML authentication, you must add the following required properties to your configuration.
{% tabs %}
{% tab title="Standalone" %}
{% stepper %}
{% step %}
Add the properties as environment variables to your owl-env.sh file.
{% endstep %}
{% step %}
Prefix all properties with the `export` statement.
{% endstep %}
{% step %}
Restart the DQ Web app.
{% endstep %}
{% endstepper %}
### Required properties
| Property | Configuration Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SAML\_ENABLED | Whether Collibra DQ uses SAML.
If set to false, users sign in with a username and password.
If set to true, SAML handles the authentication request.
|
| SAML\_ENTITY\_ID | The name of the application for the identity provider, for example Collibra DQ.
It is an immutable unique identifier of the service provider for the Identity Provider (IdP).
|
| SAML\_ENTITY\_BASEURL | The base URL that is provided in the service provider metadata. It is used to generate the ACS URL, which is the entity base URL with /saml/SSO appended to it. It must include a port number if one is configured on the IdP side.
Once you have enabled and configured SAML authentication, you can download the service provider metadata from https\://\/saml/metadata/SSO.
The /saml/SSO endpoint is case-sensitive. When you configure the ACS URL or sign-on URL in your identity provider, use /saml/SSO with a capital SSO. Using /saml/sso causes authentication failures.If you use Data Quality & Observability (self-hosted) with a Java version older than 21, such as Java 11, download your service provider metadata from https\://\/saml/metadata instead.
Whether the application needs to configure a load balancer.
You generally need this setting only when the Load Balancer is set for SSL Termination.
The default value is false.
If set to true, you must also provide a value for SAML\_LB\_SERVER\_NAME.
If the SAML\_LB\_EXISTS property is set to true and SAML\_LB\_INCLUDE\_PORT\_IN\_REQUEST set to false, you may need to update SAML\_ENTITY\_BASEURL to include the port in the URL. The SAML\_ENTITY\_BASEURL should match the IdP's ACS URL.
The attribute in which the identity provider stores the role of the user authenticating in the SAML response.
The default value is memberOf.
|
| SAML\_GRANT\_ALL\_PUBLIC | Whether any user authenticated by the identity provider is allowed to login the Collibra DQ application.
The default value is true.
|
| SAML\_USER\_NAME\_PROP | The name of the attribute in the SAML response that contains the username of the user who is authenticating. |
| SAML\_TENANT\_PROP\_NAME | If using multi-tenant mode and SAML\_TENANT\_PROP\_FROM\_URL is set to false, this is the variable in which the identity provider stores the tenant name of the user authenticating in the SAML response.
The default value is tenant.
|
| SAML\_TENANT\_PROP\_FROM\_URL | If using multi-tenant mode, this property controls where the tenant is set to use for authentication.
Set to true to identify the tenant from the SAML RelayState parameter.
Set to false to identify the tenant using a SAML response attribute defined by the SAML\_TENANT\_PROP\_NAME property (default= tenant).
|
| SAML\_KEYSTORE\_FILE | The path to the keystore file (p12 or jks format) for SAML SSO. The keystore manages the cryptographic keys and digital certificates used between the service provider (Data Quality & Observability (self-hosted)) and the IdP. For example: file:///etc/ssl/server.p12
If an error occurs with the SAML\_KEYSTORE\_FILE value, ensure that you added file: to the file path in the owl\_env.sh file. For example: SAML\_KEYSTORE\_FILE=file:/home/ec2-user/owl/config/collibraDQ-onelogin-keystore.p12
The default value is true.
If it is set to false, the SAML\_METADATA\_URL value must start with file: and be the fully qualified path to the IdP Metadata XML file that has already been mounted to the web pod. We only recommend this if the web pod is unable to resolve the URL where the IdP Metadata XML is hosted.
For example: file:/full/path/to/IdP\_metadata.xml
|
| SAML\_MAX\_AUTH\_AGE | Deprecated. |
| LOCAL\_REGISTRATION\_ENABLED | Allows you to display or hide the registration link for local users on the Collibra DQ sign-in page. Because the registration link is displayed on the sign-in page by default, this property is set to true.To display or hide the registration link from the owl-env.sh file, select from the following properties:
- export LOCAL\_REGISTRATION\_ENABLED=true: Displays the registration link on the sign-in page for local users. This is set to
true by default. - export LOCAL\_REGISTRATION\_ENABLED=false: Hides the registration link on the sign-in page for local users.
To display or hide the registration link from a K8s ConfigMap, select the from the following properties:
- LOCAL\_REGISTRATION\_ENABLED:"true": Displays the registration link on the sign-in page for local users. This is set to
true by default. - LOCAL\_REGISTRATION\_ENABLED:"false": Hides the registration link on the sign-in page for local users.
This property must be set globally on deployment.
| Property | Configuration Description |
|---|
| SAML_LB_INCLUDE_PORT_IN_REQUEST | Whether to include the port number in the request. The default value is false. |
| SAML_LB_PORT | The port number of the load balancer. The default value is 443. |
| SAML_LB_SCHEME | The protocol of the load balancer. The default value is https. |
| SAML_LB_SERVER_NAME | The server or DNS name. Usually, the same as SAML_ENTITY_BASEURL without specifying the protocol, for example without https://. This property is required and has no default. Don't include a trailing slash at the end of this value. A trailing slash can cause the base URL and port number to be parsed incorrectly, which results in authentication failures. |
| SAML_LB_CONTEXT_PATH | Any path that may be defined on the load balancer. |
### Example
```
#enable SAML & show the SAML SSO option on the login page
SAML_ENABLED=true
#set SSL communication properties for SAML
SAML_KEYSTORE_FILE=/keystore.p12
SAML_KEYSTORE_PASS=****
SAML_KEYSTORE_ALIAS=****
#in multi-tenant mode set the name of the IDP variable to hold the tenant name
export SAML_TENANT_PROP_NAME=tenant
#set the name of the IDP variable to hold the user roles in the response
export SAML_ROLES_PROP_NAME=memberOf
#allow login if authenticated to the IDP
export SAML_GRANT_ALL_PUBLIC=true
#set the EntityId of the application to be supplied to the IDP
export SAML_ENTITY_ID=OwlOneLogin
#optionally set a property that contains the username in the response
export SAML_USER_NAME_PROP=userName
```
{% hint style="success" %}
We recommend synchronizing the clocks of the Identity Provider (IdP) and Service Provider (Collibra DQ) using Network Time Protocol (NTP) to prevent authentication failures caused by significant clock skew.
{% endhint %}
## 2. Enable and configure the SAML SSO option
### Set up SSL for SAML
SSL is required by SAML. If using a custom SAML keystore, follow the instructions provided in [Migrating to a custom SAML keystore](/data-quality-self-hosted/security-configuration/saml-authentication/migrating-to-a-custom-saml-keystore.md).
Otherwise, if using the built-in keystore, configure the following variable:
* Standalone: `SAML_KEYSTORE_PASS`
* Cloud native: `global.web.security.saml.keyStorePass`
{% hint style="info" %}
You can find more information on setting up SSL in the topic, [Setting up SSL (HTTPS)](/data-quality-self-hosted/security-configuration/setting-up-ssl-https.md). In addition, example helm commands are provided in the section "Install with SAML enabled" in [Deploy on self-hosted Kubernetes](/data-quality-self-hosted/installation/installing-data-quality-observability-self-hosted-on-self-hosted-kubernetes/deploy-on-self-hosted-kubernetes.md).
{% endhint %}
### Update settings in Admin Console
When you are ready with your IdP settings, add the final configuration settings in the Admin Console:
{% stepper %}
{% step %}
Sign in to Data Quality & Observability (self-hosted) as an administrator with a username and password to the tenant you want to configure.
{% endstep %}
{% step %}
Click **Admin Console**.
{% endstep %}
{% step %}
Click **User Management**, then click **SAML Security**.\ :chevrons-right: The SAML Security Settings page opens.
{% endstep %}
{% step %}
Click the **SAML Enabled** dropdown menu, then select **Enabled**.
{% endstep %}
{% step %}
Under the SAML Enabled dropdown menu, to the far right side of the page, click 
.\ :chevrons-right: The Add Meta Data Configuration dialog box appears.
{% endstep %}
{% step %}
Enter the required information.
| Option | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Meta-Data URL | The URL of the identity provider metadata XML file or the location of the downloaded XML file.
The name of the XML file must begin with the prefix file: and typically uses file:/opt/owl/config/idp-metadata.xml format.
Whether Collibra DQ uses SAML.
If set to false, users sign in with a username and password.
If set to true, SAML handles the authentication request.
|
| SAML\_ENTITY\_ID | `--set global.web.security.saml.entityId` | The name of the application for the identity provider, for example Collibra DQ.
It is an immutable unique identifier of the service provider for the Identity Provider (IdP).
|
| SAML\_ENTITY\_BASEURL | `--set global.web.security.saml.entityBaseUrl` | The base URL that is provided in the service provider metadata. It is used to generate the ACS URL, which is the entity base URL with /saml/SSO appended to it. It must include a port number if one is configured on the IdP side.
Once you have enabled and configured SAML authentication, you can download the service provider metadata from https\://\/saml/metadata/SSO.
The /saml/SSO endpoint is case-sensitive. When you configure the ACS URL or sign-on URL in your identity provider, use /saml/SSO with a capital SSO. Using /saml/sso causes authentication failures.If you use Data Quality & Observability (self-hosted) with a Java version older than 21, such as Java 11, download your service provider metadata from https\://\/saml/metadata instead.
Whether the application needs to configure a load balancer.
You generally need this setting only when the Load Balancer is set for SSL Termination.
The default value is false.
If set to true, you must also provide a value for SAML\_LB\_SERVER\_NAME.
|
| SAML\_ROLES\_PROP\_NAME | `--set global.web.security.saml.rolePropName` | The attribute in which the identity provider stores the role of the user authenticating in the SAML response.
The default value is memberOf.
|
| SAML\_GRANT\_ALL\_PUBLIC | `--set global.web.security.saml.grantAllPublic` | Whether any user authenticated by the identity provider is allowed to login the Collibra DQ application.
The default value is true.
|
| SAML\_USER\_NAME\_PROP | `--set global.web.security.saml.userNamePropName` | The name of the attribute in the SAML response that contains the username of the user who is authenticating. |
| SAML\_TENANT\_PROP\_NAME | `--set global.web.security.saml.tenantPropName` | If using multi-tenant mode and SAML\_TENANT\_PROP\_FROM\_URL is set to false, this is the variable in which the identity provider stores the tenant name of the user authenticating in the SAML response.
The default value is tenant.
|
| SAML\_TENANT\_PROP\_FROM\_URL | `--set global.web.security.saml.tenantPropFromUrl` | If using multi-tenant mode, this property controls where the tenant is set to use for authentication.
Set to true to identify the tenant from the SAML RelayState parameter.
Set to false to identify the tenant using a SAML response attribute defined by the SAML\_TENANT\_PROP\_NAME property (default= tenant).
|
| SAML\_KEYSTORE\_FILE | `--set global.web.security.saml.keyStoreFile` | The path to the keystore file (p12 or jks format) for SAML SSO. The keystore manages the cryptographic keys and digital certificates used between the service provider (Data Quality & Observability (self-hosted)) and the IdP. For example: file:///etc/ssl/server.p12
If an error occurs with the SAML\_KEYSTORE\_FILE value, ensure that you added file: to the file path in the owl\_env.sh file. For example: SAML\_KEYSTORE\_FILE=file:/home/ec2-user/owl/config/collibraDQ-onelogin-keystore.p12
Allows you to display or hide the registration link for local users on the Collibra DQ sign-in page. Because the registration link is displayed on the sign-in page by default, this property is set to true.To display or hide the registration link from the owl-env.sh file, select from the following properties:
- export LOCAL\_REGISTRATION\_ENABLED=true: Displays the registration link on the sign-in page for local users. This is set to
true by default. - export LOCAL\_REGISTRATION\_ENABLED=false: Hides the registration link on the sign-in page for local users.
To display or hide the registration link from a K8s ConfigMap, select the from the following properties:
- LOCAL\_REGISTRATION\_ENABLED:"true": Displays the registration link on the sign-in page for local users. This is set to
true by default. - LOCAL\_REGISTRATION\_ENABLED:"false": Hides the registration link on the sign-in page for local users.
This property must be set globally on deployment.
| Kubernetes ConfigMap Metadata Property | Helm Upgrade Command Argument | Configuration Description |
|---|
| SAML_LB_PORT | --set global.web.security.saml.loadBalancerPort | The port number of the load balancer. The default value is 443. |
| SAML_LB_SCHEME | --set global.web.security.saml.loadBalancerSchema | The protocol of the load balancer. The default value is https. |
| SAML_LB_SERVER_NAME | --set global.web.security.saml.loadBalancerServerName | The server or DNS name. Usually, the same as SAML_ENTITY_BASEURL without specifying the protocol, for example without https://. This property is required and has no default. Don't include a trailing slash at the end of this value. A trailing slash can cause the base URL and port number to be parsed incorrectly, which results in authentication failures. |
### Example
Executing the following Helm upgrade command:
```
helm upgrade --namespace \
--set global.web.security.saml.enabled=true \
--set global.web.security.saml.entityId=cdq-prod \
--set 'global.web.security.saml.entityBaseUrl=https://cdq-env.domain.com' \
--set 'global.web.security.saml.keyStoreFile=file:///etc/ssl/dqkeystore.jks' \
--set global.web.security.saml.keyStoreAlias= \--set global.web.security.saml.keyStorePass= \--set global.web.security.saml.tenantPropName=tenant \--set global.web.security.saml.rolePropName=memberOf \--set global.web.security.saml.grantAllPublic=true \--set global.web.security.saml.userNamePropName=userName \
/path/to/helm/chart
```
Will result in the web ConfigMap being generated with these corresponding key-value pairs:
```
#enable SAML & show the SAML SSO option on the login page
SAML_ENABLED: 'true'
#set the EntityId of the application to be supplied to the IDP
SAML_ENTITY_ID: cdq-prodSAML_ENTITY_BASEURL: https://cdq-env.domain.com
#set SSL communication properties for SAML
SAML_KEYSTORE_FILE: file:///etc/ssl/dqkeystore.jksSAML_KEYSTORE_PASS: SAML_KEYSTORE_ALIAS:
#in multi-tenant mode set the name of the IDP variable to hold the tenant name
SAML_TENANT_PROP_NAME: tenant
#set the name of the IDP variable to hold the user roles in the responseSAML_ROLES_PROP_NAME: memberOf
#allow login if authenticated to the IDPSAML_GRANT_ALL_PUBLIC: 'true'
#optinally set a property that contains the username in the responseSAML_USER_NAME_PROP: userName
```
{% hint style="success" %}
We recommend synchronizing the clocks of the Identity Provider (IdP) and Service Provider (Collibra DQ) using Network Time Protocol (NTP) to prevent authentication failures caused by significant clock skew.
{% endhint %}
## 2. Enable and configure the SAML SSO option
### Set up SSL for SAML
SSL is required by SAML. If using a custom SAML keystore, follow the instructions provided in [Migrating to a custom SAML keystore](/data-quality-self-hosted/security-configuration/saml-authentication/migrating-to-a-custom-saml-keystore.md).
Otherwise, if using the built-in keystore, configure the following variable:
* Standalone: `SAML_KEYSTORE_PASS`
* Cloud native: `global.web.security.saml.keyStorePass`
{% hint style="info" %}
You can find more information on setting up SSL in the topic, [Setting up SSL (HTTPS)](/data-quality-self-hosted/security-configuration/setting-up-ssl-https.md). In addition, example helm commands are provided in the section "Install with SAML enabled" in [Deploy on self-hosted Kubernetes](/data-quality-self-hosted/installation/installing-data-quality-observability-self-hosted-on-self-hosted-kubernetes/deploy-on-self-hosted-kubernetes.md).
{% endhint %}
### Update settings in Admin Console
When you are ready with your IdP settings, add the final configuration settings in the Admin Console:
{% stepper %}
{% step %}
Sign in to Data Quality & Observability (self-hosted) as an administrator with a username and password to the tenant you want to configure.
{% endstep %}
{% step %}
Click **Admin Console**.
{% endstep %}
{% step %}
Click **User Management**, then click **SAML Security**.\ :chevrons-right: The SAML Security Settings page opens.
{% endstep %}
{% step %}
Click the **SAML Enabled** dropdown menu, then select **Enabled**.
{% endstep %}
{% step %}
Under the SAML Enabled dropdown menu, to the far right side of the page, click .\ :chevrons-right: The Add Meta Data Configuration dialog box appears.
{% endstep %}
{% step %}
Enter the required information.
| Option | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Meta-Data URL | The URL of the identity provider metadata XML file or the location of the downloaded XML file.
The name of the XML file must begin with the prefix file: and typically uses file:/opt/owl/config/idp-metadata.xml format.