Configuring SAML authentication

This page shows you how to integrate Collibra Data Quality & Observability with an existing SAML solution and have your application act as a service provider. Once you set the environment variables, you can access and configure SAML security settings as an administrator from the SAML Security page of the Admin Console.

Set the SAML authentication properties
Download service provider metadata for the IDP
Enable the SAML sign in option

Set the SAML authentication properties

Before configuring SAML authentication, you must add the following required properties to your configuration.

Standalone installation

Add the properties as environment variables to your owl-env.sh file located in <installation_directory>/owl/config/.
Prefix all properties with the export statement.
Restart the web app.

Cloud native installation

Add the properties as environment variables to your DQ-web ConfigMap.
Recycle the pod.

Required properties

Property Description

SAML_ENABLED

Property	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).

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

Warning Please see CORS_ALLOWED_ORIGINS in the Optional properties section below if you have SAML configured in Collibra DQ, or if the app sits behind a load balancer.

Optional properties: general

You can further configure your SAML setup with the following optional properties.

Property Description

CORS_ALLOWED_ORIGINS=${IDP-BASE-URL},${DQ-BASE-URL}

Add this property to environment variables.

Replace ${IDP-BASE-URL} with the value of the actual IDP URL (For example: https://ping.auth.com)

Replace ${DQ-BASE-URL} with the value of the actual DQ Base URL (For example: https://dq-env.com)

Important The CORS restriction is enforced for SAML and multi-tenancy, which will break SAML unless the IDP is configured as a trusted origin in Collibra DQ. Therefore, you must add this property for DQ and SAML to work properly.

Note When using Azure AD, you should use the User Access URL, which is located under Properties in the Azure SSO configuration.

SAML_ENTITY_BASEURL

The base URL that is provided in the service provider metadata.

Note Set this property when you use DNS.

SAML_LB_EXISTS

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_METADATA_USE_URL

Whether Collibra DQ uses a URL or a file for the identity provider metadata.

The default value is true.

If set to false, the file must be accessible to the owl-web and the path provided in the Meta-Data URL field of the Meta Data Configurations section under Admin Console --> SAML Setup --> Connection.

SAML_ROLES_PROP_NAME

The attribute name that contains role ID/name in the incoming SAML assertion.

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, the variable in which the identity provider stores the tenant name of the user authenticating in the SAML response.

The app will attempt to use the RelayState parameter to identify the tenant and then fall back on this property.

SAML_TENANT_PROP_FROM_URL

If using multi-tenant mode, this property controls where the tenant is set to use for authentication.

The default value is false.

If set to true, the app attempts to use the RelayState property to identify the tenant. If it is set to false, the app attempts to find the tenant in a SAML response attribute, which is defined by the SAML_TENANT_PROP_NAME property (default=tenant).

SAML_KEYSTORE_FILE

The path to the keystore for SSL validation.

The store should contain the keypair of the identity provider for SSL verification.

SAML_KEYSTORE_PASS The password for the keystore provided in SAML_KEYSTORE_FILE.

SAML_KEYSTORE_ALIAS The alias of the keypair (private and public) in the keystore used for SSL verification.

LOCAL_REGISTRATION_ENABLED

An optional property, which 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:

Property	Description
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	Hides the registration link on the sign-in page for local users.

To display or hide the registration link from a K8s config map, select from the following properties:

Property	Description
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.

Note This property must be set globally on deployment.

SAML_MAX_AUTH_AGE

The number of seconds that an IDP authentication is accepted by the application. If the IDP authentication occurred outside this time range, the application considers the value too old to trust and the authentication is not accepted.

The default is 14400 seconds (4 hours).

CSRF_TOKEN_ENABLED Enables the use of Spring CSRF token implementation.

CSRF_TOKEN_IGNORE_URL_PATTERN Requests URL patterns to be ignored for CSRF token validation.

CSRF_TOKEN_IGNORE_REFERER_PATTERN Requests header referer patterns to be ignored for CSRF token validation.

Note While CORS is still an optional configuration, it is required if you have SAML configured in Collibra DQ, or if you have Collibra DQ behind a load balancer.

Note CORS is also enforced for multi-tenancy.

Optional Properties: Meta-Data

When SAML_METADATA_USE_URL is set to true (default), the following additional properties are available.

Property Description

SAML_METADATA_TRUST_CHECK

Property	Description
SAML_METADATA_TRUST_CHECK	Whether to enable Collibra DQ to do trust verification of the identity provider. The default value is `false`.
SAML_METADATA_REQUIRE_SIGNATURE	Whether Collibra DQ signs authentication requests to the identity provider. The default value is `false`.
SAML_INCLUDE_DISCOVERY_EXTENSION	Whether to enable Collibra DQ to indicate in the SAML metadata that it’s able to consume responses from an IDP Discovery Service. The default value is `false`.

Whether to enable Collibra DQ to do trust verification of the identity provider.

The default value is false.

SAML_METADATA_REQUIRE_SIGNATURE

Whether Collibra DQ signs authentication requests to the identity provider.

The default value is false.

SAML_INCLUDE_DISCOVERY_EXTENSION

Whether to enable Collibra DQ to indicate in the SAML metadata that it’s able to consume responses from an IDP Discovery Service.

The default value is false.

Optional Properties: Load Balancer

When SAML_LB_EXISTS is set to true, the following additional properties are available.

Property	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.
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 tenat name
SAML_TENANT_PROP_NAME=tenant

#set the name of the IDP variable to hold the user roles in the response
SAML_ROLES_PROP_NAME=memberOf

#allow login if authenticated to the IDP
SAML_GRANT_ALL_PUBLIC=true

#set the EntityId of the application to be supplied to the IDP
SAML_ENTITY_ID=OwlOneLogin

#optinally set a property that contains the username in the response
SAML_USER_NAME_PROP=""

#optionally use a file for the IDP metadata vs a URL (default is true)
SAML_METADATA_USE_URL=false 

#optional security settings to 
SAML_METADATA_TRUST_CHECK=false
SAML_METADATA_REQUIRE_SIGNATURE=false
SAML_INCLUDE_DISCOVERY_EXTENSION=false

Download service provider metadata for the IDP

Once you have enabled and configured SAML authentication, you can download the service provider metadata that is required by your identity provider.

Steps

Locate the URL of your Collibra DQ environment in the address bar of your browser window.
From the following URL, download the service provider metadata you will need to enable the SAML sign in option:
https://<your_dq_environment_url>/saml/metadata
Follow the steps in Enable the SAML sign in option.

Enable the SAML sign in option

When you are ready with your IDP settings, add the final configuration settings in the Admin Console:

Steps

Sign in as an administrator and select the tenant you want to configure.
In the left navigation pane, click Admin Console.
Click User Management and then click SAML Security.

The SAML Security Settings page opens.

From the SAML Enabled dropdown menu, select Enabled.
Click the to the far right side of the page, under the SAML Enabled dropdown menu.

The Add Meta Data Configuration dialog appears.

Enter the required information.

Input field	Description
Meta-Data URL	The Identity Provider HTTP URL that returns the SAML metadata document.
Meta-Data Label	The unique label to identify the SAML metadata configuration.
IDP_URL*	The URL to be used for SSO initiated from the Collibra DQ login page. Note This is a required field.

Input field

Description

Meta-Data URL

The Identity Provider HTTP URL that returns the SAML metadata document.

Meta-Data Label

The unique label to identify the SAML metadata configuration.

IDP_URL*

The URL to be used for SSO initiated from the Collibra DQ login page.

Note This is a required field.

Click Add.

Tip Once you complete this setup, restart Collibra Data Quality & Observability and sign in using the SAML SSO option.

You can now map SAML Groups to Collibra DQ roles. Go to AD Group to Role Mapping.