Configuring SAML authentication

You can integrate Data Quality & Observability Classic 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.

  1. Add the properties as environment variables to your owl-env.sh file.
  2. Prefix all properties with the export statement.
  3. Restart the DQ Web app.
  1. Add the properties as environment variables to your DQ-web ConfigMap.
  2. Recycle the pod.

Required properties

Kubernetes ConfigMap Metadata Property Helm Upgrade Command Argument Configuration Description
SAML_ENABLED --set global.web.security.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 --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://<your_dq_environment_url>/saml/metadata/SSO.

Important If you use Data Quality & Observability Classic with a Java version older than 17, such as Java 11, download your service provider metadata from https://<your_dq_environment_url>/saml/metadata instead.

Warning  If you have SAML configured in Collibra DQ, or if the app sits behind a load balancer, see the CORS_ALLOWED_ORIGINS property below.

Optional properties: general

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

Kubernetes ConfigMap Metadata Property Helm Upgrade Command Argument Configuration Description
CORS_ALLOWED_ORIGINS=${IDP-BASE-URL},${DQ-BASE-URL} --set global.web.security.cors.allowedOrigins Allows cross-origin requests between Collibra DQ and SAML.

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.
SAML_LB_EXISTS --set global.web.security.saml.loadBalancerExist

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.

Note 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.
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, 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 --set global.web.security.saml.tenantPropFromUrl

If using multi-tenant mode, this property controls where the tenant is set to use for authentication. In multi-tenant environments, you can route SSO to the proper tenant with the SAML provided RelayState or SAML_TENANT_PROP_FROM_URL properties.

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

You can set the RelayState property on the SAML Security page of the Admin Console.
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 Classic) and the IdP. For example: file:///etc/ssl/server.p12

Tip 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
SAML_KEYSTORE_PASS --set global.web.security.saml.keyStorePass The password for the keystore provided in SAML_KEYSTORE_FILE.
SAML_KEYSTORE_ALIAS --set global.web.security.saml.keyStoreAlias

The alias of the keypair (private and public) in the keystore used for SAML SSO.
SAML_METADATA_URL --set global.web.security.saml.metaDataUrl The URL of the identity provider metadata XML file.
SAML_METADATA_USE_URL --set global.web.security.saml.metadataUseUrl

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 --set global.web.security.saml.maxAuthAge Deprecated.
LOCAL_REGISTRATION_ENABLED --set global.web.security.localUserRegistration.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:

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=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:

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.
CSRF_TOKEN_ENABLED --set global.web.security.csrfToken.enabled Enables the use of Spring CSRF token implementation.
CSRF_TOKEN_IGNORE_URL_PATTERN --set global.web.security.csrfToken.ignorePattern Requests URL patterns to be ignored for CSRF token validation.
CSRF_TOKEN_IGNORE_REFERER_PATTERN --set global.web.security.csrfToken.ignoreRefererPattern 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.

CORS is also enforced for multi-tenancy.

Optional properties: load balancer

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

Kubernetes ConfigMap Metadata Property Helm Upgrade Command Argument Configuration Description
SAML_LB_INCLUDE_PORT_IN_REQUEST --set global.web.security.saml.loadBalancerIncludePortInRequest

Whether to include the port number in the request.

The default value is false.
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.
SAML_LB_CONTEXT_PATH --set global.web.security.saml.loadBalancerContextPath 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=""
Tip 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.

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.

Otherwise, if using the built-in keystore, configure the following variable:

  • Standalone: SAML_KEYSTORE_PASS

  • Cloud native: global.web.security.saml.keyStorePass

Note You can find more information on setting up SSL in the topic, Setting up SSL (HTTPS). In addition, example helm commands are provided in the section "Install with SAML enabled" in Deploy on self-hosted Kubernetes.

Update settings in Admin Console

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

  1. Sign in to Data Quality & Observability Classic as an administrator with a username and password to the tenant you want to configure.
  2. Click Admin Console.
  3. Click User Management, then click SAML Security.
    4. The SAML Security Settings page opens.
  4. Click the SAML Enabled dropdown menu, then select Enabled.
  5. Under the SAML Enabled dropdown menu, to the far right side of the page, click Plus icon.
    6. The Add Meta Data Configuration dialog box appears.
  6. Enter the required information.
    7. Option Description
    Meta-Data URL

    The URL of the identity provider metadata XML file or the location of the downloaded XML file.

    Important The name of the XML file must begin with the prefix file: and typically uses file:/opt/owl/config/idp-metadata.xml format.
    Meta-Data Label The name for this specific configuration.
    IDP URL The URL of the Collibra DQ application that is provisioned by the identity provider.
    Note The IDP_URL is the IdP Initiated SSO login URL. For Example, in Azure, it would be https://myapps.microsoft.com/signin/<sp-app-id>?tenantId=<sp-tenant-id>. In multi-tenant mode, this URL should contain a RelayState for DQ to set the tenant on completing the SSO.
  7. Click Add.
  8. Restart the application and sign in using the SAML SSO option.

    9. Note SAML SSO authentication via the /v3/auth/signin API is not supported.

    Note SAML authentication is only supported for IdP-initiated requests.

  9. The user account has only public access. To map user roles from AD to DQ roles, follow the instructions provided in AD Group to Role Mapping.