API Token-Based Authentication

Keycloak enables the use of token-based authentication to access IBM Automatic Data Lineage APIs. To enable the use of token-based authentication you need to:

1. Create a dedicated API client configuration. This client can be shared between Flow Server API and Orchestration API.

2. Request an access token and refresh token, which will then be used for authentication.

Step 1: Create an API Client Configuration

Here is how to set up a client of the Keycloak server to obtain the tokens used when communicating with the Automatic Data Lineage API.

1. Log in to your Keycloak instance.

2. Go to the Clients section.

3. Click Create Client.

   

4. Under Client Type select OpenID Connect.

5. Enter a Client ID (for example, “api-client”). This ID is sent when you obtain the token from the Keycloak server. Your client ID must be unique in the realm.

6. Enter a Name for the client.

7. Click Next.

8. 

   Turn the Client Authentication toggle to On.

9. Next to Authentication Flow, select Service Accounts Roles.

10. Click Next.

    

11. Set Valid Redirect URIs to *, Valid Post Logout Redirect URIs to +, and Web Origins to *.

12. Click Save.

Regenerate Secrets for the New Client

1. Open the client you just created, and go to the Credentials tab.

   

2. Make sure the value next to Client Authenticator says Client Id and Secret.

3. Click Regenerate Secret, and then click Yes in the confirmation dialog.

Configure Account Roles

To enable access to Automatic Data Lineage platform resources, you’ll need to assign roles to the client.

1. Go to the client’s Service Account Roles tab.

   

2. Select the roles that are appropriate for your use case.

   • Check Manta Flow Server Authentication and Authorization and User Roles Used in Manta Admin UI to see which roles are available.

Step 2: Request an Access Token for Authentication

The token needed to access the Automatic Data Lineage API is obtained from the Keycloak server. The following examples will use curl as an HTTP client. But feel free to use any client. This guide assumes that the Keycloak server is accessible at the URL http://localhost:9090/auth. Please adjust the URL according to your setup.

To get the token, you have to send an HTTP POST request to the following endpoint.

http://localhost:9090/auth/realms/manta/protocol/openid-connect/token

The body of the request is formatted as application/x-www-form-urlencoded.

• grant_type=client_credentials

• client_id is selected when creating the client

• client_secret is regenerated during client creation

In cURL syntax, the request can look like this.

curl --location --request POST 'http://localhost:9090/auth/realms/manta/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_secret=0kuGOk0Wma4kdFO1Kqf5E7Ht9ZqxU0cU' \
--data-urlencode 'client_id=api-client'

This request will return JSON, which contains the access token required to access the API in JWT format. The response could look like this.

{
    "access_token": "eyJhbGciOiJSUz.....CuAtGy7Hdw6D-6A",
    "expires_in": 18000,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 1635950040,
    "scope": "email profile"
}

The field access_token contains the actual token needed to access the API. The refresh token is not included by design. For more details see https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.3.

Accessing the Automatic Data Lineage API

To access the Automatic Data Lineage API, set the authorization header in the request to the value Bearer <token> where <token> is the value obtained from Keycloak.

For example, to get a list of workflow templates from the Admin GUI server, you can use the following cURL command.

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI ..." \
http://localhost:8181/manta-admin-gui/public/process-manager/v1/workflow/templates

The access_token obtained from the Keycloak server is used to access the Admin GUI server. In this example, the token is truncated for clarity. In a real use case, the token has to be provided in full.

Token Lifespan

In the example above, you can see that the tokens have different lifespans. Best practice is to keep the lifespan of the access_token relatively short (minutes) and the refresh token lifespan fairly long (hours or even days).

The token lifespan is configured for the whole realm in the Sessions section of Realm Settings.

These are global settings that apply to all clients configured in the realm. Each client can then be further configured under Advanced Settings in the Client Details section.

These settings override the global settings for the whole realm.

Keep in mind that the following rule applies.

The refresh token lifespan will be equal to the smallest value among SSO Session Idle, Client Session Idle, SSO Session Max, and Client Session Max.