Authentication Configuration

Configuration

Configuration file oidc.properties contains all the entries necessary to configure integration with the authorization server. It contains the following: 

manta.oidc.issuerUri=http\://localhost\:9090/auth/realms/manta
manta.oidc.clientId=manta-service
manta.oidc.clientSecret=843FUfTC3HooV6GRnvoNkaciSJgPIhLK
manta.oidc.scope=roles,profile,openid
manta.oidc.roleClaim=realm_access.roles
manta.oidc.grantType=authorization_code
manta.oidc.publicClientId=manta-admin-gui-fe
Note: The backslashes for escaping the colon (:) are optional. They are generated during installation, but if you are creating the file manually, you can omit them.

Issuer URI

manta.oidc.issuerUri is the URL of the authorization server. You have to provide a full URL including the realm path. Automatic realm resolution for Keycloak is no longer supported. If using bundled Keycloak, the realm name is simply manta, making the final URL http://localhost:9090/auth/realms/manta.

To check if the URL is correct, open it in the browser and add /.well-known/openid-configuration to the end. It should return a JSON file containing the authorization server configuration.

Be careful about the trailing slash. The configuration file should not contain one because the connector adds /.well-known/openid-configuration with a leading slash already included.

When using bundled Keycloak, the URL has to be reachable from the machine where IBM Automatic Data Lineage is installed. This typically means using localhost as the domain name. To enable login via the outside network, please refer to the section on setting up the network, included later in this document.

Client Credentials

manta.oidc.clientId and manta.oidc.clientSecret are the primary client credentials. When using this client, the Automatic Data Lineage application will authenticate itself against the authorization server. These details are found in the Keycloak web console.

manta.oidc.publicClientId is an identifier for the Javascript public client, if the application has one. Currently, only AdminGUI has a Javascript frontend, and thus, it is the only application that requires this value to be set up.

Claim and Scope

The scope identifies which scopes the client is requesting from the authorization server. For the Automatic Data Lineage application, roles,profile,openid are enough. There is no need to change this.

manta.oidc.roleClaim identifies how the user roles are stored in the access token generated by the authorization server. The default value for bundled Keycloak is realm_access.roles and does not need to be changed.

Optional Settings

The following are optional settings required by some Automatic Data Lineage applications.

manta.oidc.grantType identifies which authorization flow the client should use when authenticating itself with the authorization server. By default, client_credentials is used for all applications except Flow Viewer, which requires the authorization code flow. This value is set as the default in the application.

Configuration Location

The configuration files are located in following location in each component.

Accessing Keycloak from Multiple Domains

In a typical production setup, Keycloak has a different URL for the backend than it does for the frontend. This is usually the case when the machine has a public IP address, its own hostname, or there is a proxy server sitting in front of Keycloak.

No alt text provided

In the illustration above, you can see what is happening. There are always two routes to the Keycloak server. We want Automatic Data Lineage to communicate with Keycloak on the private network using localhost. However, the Browser cannot see localhost because it is on the other side of the network boundary, so the Browser must use the public URL of the Keycloak server.

For this, the OIDC configuration supports additional settings. In the oidc.properties for all Automatic Data Lineage components, you have to set up the following.

The manta.oidc.issuerUri is mandatory, and it contains the URL of the Keycloak server, as it is available from inside the machine. In 99.9% of cases, you want to have here just http://localhost:9090/auth/realms/manta.

The manta.oidc.publicIssuerUri on the other side has to contain the URL that allows users to reach the Keycloak server from their browser. This can be the public IP or address of the available URL on the proxy server. In the situation illustrated above, the value would be http://172.30.1.34:9090/auth/realms/manta in the first case and https://example.com/auth/realms/manta in the second case.

The port can be omitted in the second case because the proxy is taking care of it. Always check your setup and adjust the URLs accordingly.

Troubleshooting Tips

To troubleshoot the URI settings, you can perform a few simple tests. To verify the setup, you can try to manually load the configuration from the Keycloak server. The configuration itself is a big JSON file, usually starting like this.

{
  "issuer": "https://keycloak.int.getmanta.com/auth/realms/manta",
  "authorization_endpoint": "https://keycloak.int.getmanta.com/auth/realms/manta/protocol/openid-connect/auth",
  "token_endpoint": "https://keycloak.int.getmanta.com/auth/realms/manta/protocol/openid-connect/token",
  "introspection_endpoint": "https://keycloak.int.getmanta.com/auth/realms/manta/protocol/openid-connect/token/introspect",
  "userinfo_endpoint": "https://keycloak.int.getmanta.com/auth/realms/manta/protocol/openid-connect/userinfo",
  "end_session_endpoint": "https://keycloak.int.getmanta.com/auth/realms/manta/protocol/openid-connect/logout",
  "frontchannel_logout_session_supported": true,
  "frontchannel_logout_supported": true,
  "jwks_uri": "https://keycloak.int.getmanta.com/auth/realms/manta/protocol/openid-connect/certs",
  "check_session_iframe": "https://keycloak.int.getmanta.com/auth/realms/manta/protocol/openid-connect/login-status-iframe.html",
  "grant_types_supported": [
    "authorization_code",
    "implicit",

    ...

Verifying the Issuer URI

  1. Log in to the machine where Automatic Data Lineage is installed.

  2. Open a new terminal window and run the following command, where {manta.oidc.issuerUri} is the actual value put in the oidc.properties file.

    curl {manta.oidc.issuerUri}/.well-known/openid-configuration

  3. It should return a JSON file, similar to the example above.

Verifying the Public Issuer URI

  1. Open a new terminal window on your machine and run the following command, where {manta.oidc.publicIssuerUri} is the actual value put in the oidc.properties file.

    curl {manta.oidc.publicIssuerUri}/.well-known/openid-configuration

  2. It should return a JSON file, similar to the example above.

cURL is part of the Automatic Data Lineage installation. You can find it in {installation root}/utility/curl if your system does not have one installed.

Verifying the Keycloak Frontend URL

When using the public URL, you have to make sure that {manta.oidc.publicIssuerUri} has the same base as the frontend URL property set up in the Keycloak administration console.

No alt text provided

In the picture above, the Frontend URL is set for public IP access. For this to work correctly, you have to include the correct protocol, domain (or IP), and optionally, a port number. The Frontend URL has to end with /auth without the trailing slash.

The matching manta.oidc.publicIssuerUrl will then be {keycloak frontend URL}/realms/manta. So in this example, the final value will be http://172.30.1.210:9090/auth/realms/manta.

If the two values do not match, you will not be able to log in or even start the Automatic Data Lineage applications.

Working with HTTPS

To set up HTTPS for Keycloak Quarkus, edit <mantaflow>/keycloak/conf/manta.conf and apply the following changes.

See also Importing certificates into Java default truststore.