Authentication (Cloud Pak for Data)

To authenticate to the Master Data Connect API, you must pass an IBM Cloud Pak® for Data service instance token in an Authorization header.

You can retrieve a Master Data Connect instance token by viewing the service instance details in the Cloud Pak for Data web interface or using the /zen-data/v2/serviceInstance/users API.

Tip: Service instance tokens expire 20 minutes after creation.

To obtain a service instance token and authorize your Master Data Connect API calls, complete the following steps.

Grant users access to Master Data Connect.
Retrieve the platform token.
Retrieve the service instances associated with the platform token.
Obtain a service instance token by providing your service instance ID.
Use the service instance token to authorize your Master Data Connect API calls.

Granting users access to Master Data Connect

You can grant users access to Master Data Connect in two ways:

With the Cloud Pak for Data web interface.
With the /zen-data/v2/serviceInstance/users API.

Users must be assigned one of the following roles:

MDC-Manager - Perform manager operations such as creating traversal templates, and updating the logical model. The MDC-Manager role also includes the same privileges as the MDC-Writer role.
MDC-Writer - Perform write operations such as loading data. The MDC-Writer role also includes the same privileges as the MDC-Reader role.
MDC-Reader - Perform read operations such as running searches or running graph queries by using traversal templates.

Granting access to users with the Cloud Pak for Data web interface

To grant access to users by using the Cloud Pak for Data web interface:

Log into the Cloud Pak for Data web interface.
Navigate to My Instances, then select the specified instance.
Click the Manage access option.
If the user is not listed on the manage access page:
1. Select the Add users option.
2. Select the specified users and select the role of MDC-Reader, MDC-Writer, or MDC-Manager.
3. Click Add to complete the role assignment.
If the user is already listed on the manage access page:
1. Hover over the specified user and select the Edit option.
2. Select the role of MDC-Reader, MDC-Writer, or MDC-Manager.
3. Click Save to complete the role assignment.

After access has been granted to users, service instance tokens will be accepted by Master Data Connect.

Granting access to users with the Cloud Pak for Data API

To grant access to users by using the /zen-data/v2/serviceInstance/users API, first run the following cURL command to get all users present in Cloud Pak for Data:

curl -k -X GET https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/users -H 'authorization: Bearer <PLATFORM_TOKEN>'

Then use the /zen-data/v2/serviceInstance/users API to assign the users roles while granting them access by running the following cURL command:

curl -k -X POST \
  https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/users/ \
  -H 'Authorization: Bearer <PLATFORM_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
   "serviceInstanceID":"<PROVISIONED_INSTANCE_ID>",
   "users":[
      {
         "display_name":"<DISPLAY_NAME>",
         "role":"<MDC_ROLE>",
         "uid":"<USER_ID>",
         "username":"<USER_NAME>"
      }
   ]
}'

Replace the following values in the above cURL command:

<CPD_CLUSTER_HOST>:<PORT> - Your Cloud Pak for Data cluster host and port.
<PLATFORM_TOKEN> - The user platform token.
<PROVISIONED_INSTANCE_ID> - The instance ID of your provisioned instance.
<DISPLAY_NAME>, <USER_ID>, and <USER_NAME> - The user display name, user ID, and user name obtained from the /zen-data/v2/serviceInstance/users API.
<MDC_ROLE> - The desired Master Data Connect role: MDC-Reader, MDC-Writer, or MDC-Manager.

After access has been granted to users, service instance tokens will be accepted by Master Data Connect.

In the following API example, the user user1 is granted MDC-Manager access to the sample-0 (1582510653894) instance.

curl -k -X POST   https://ibm-nginx-svc-lite.apps.cpd-lb.ibm.com/zen-data/v2/serviceInstance/users/   -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwic3ViIjoiYWRtaW4iLCJpc3MiOiJLTk9YU1NPIiwiYXVkIjoiRFNYIiwicm9sZSI6IkFkbWluIiwicGVybWlzc2lvbnMiOlsiYWRtaW5pc3RyYXRvciIsImNhbl9wcm92aXNpb24iXSwidWlkIjoiMTAwMDMzMDk5OSIsImF1dGhlbnRpY2F0b3IiOiJkZWZhdWx0IiwiZGlzcGxheV9uYW1lIjoiYWRtaW4iLCJpYXQiOjE1NzQzNjI2MDksImV4cCI6MTU3NDQwNTgwOX0.olm53bABcdVE6J9vi-VbRU13cr3B0MKRMVq6D4H-W7tXPZOLDvdsIKhCpW0aBi_iryE1sSgIdIb663RmW_nws2wxlpYWHtvigPwY5OVsr8dIA_wRlsCC96JnVa0GB0adM7U-qSfEruTTWZTLxL-gr4EucUXSZ84aii9ukMtN4VUDTvKsa9xJtnQY4W3owdezRzbG_6UkcvjtWzTLTUGIQisCBTkKZsoroGQuDkiiBTtJdNT8T_rZ6nqNQ6y-wsgZ6LMSCKJA_TC65jTJvu8903UoNzW2wnK7Z_Dt_oob9TYOOzNlkaa1YSQewmBhixV08wr8tmLOOzwtOxwCf5Ya-A'   -H 'Content-Type: application/json'   -d '{
   "serviceInstanceID":"1582510653894",
   "users":[
      {
         "display_name":"user1",
         "role":"MDC-Manager",
         "uid":"1000331001",
         "username":"user1"
      }
   ]
}'

Retrieving the platform token

To retrieve the platform token by using the /icp4d-api/v1/authorize API, run the following cURL command:

curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/authorize' -H 'Content-type: application/json' -d '{ "username": "<USER_NAME>", "password": "<PASSWORD>" }'

Replace the following values in the cURL command:

<CPD_CLUSTER_HOST>:<PORT> - Your Cloud Pak for Data cluster host and port.
<USER_NAME> - Your Cloud Pak for Data user name.
<PASSWORD> - Your Cloud Pak for Data password.

Retrieving the service instances associated with the platform token

To retrieve the service instance ID with the /zen-data/v3/service_instances API, run the following cURL command:

curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v3/service_instances?add_on_type=mdc-app' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

Replace the following values in the cURL command:

<CPD_CLUSTER_HOST>:<PORT> - Your Cloud Pak for Data cluster host and port.
<PLATFORM_TOKEN> - The user platform token.

This command produces the following JSON response:

{
   "limit":20,
   "offset":0,
   "service_instances":[
      {
         "addon_type":"mdc-app",
         "addon_version":"1.0.0",
         "created_at":"2020-05-10T22:15:55.557740Z",
         "description":"string",
         "display_name":"MDC1",
         "id":"1583878225057"
         ...
      }
   ],
   "total_count":1
}

The service instance ID will be returned in the id property of the response.

Obtaining a service instance token by providing your service instance ID

After you have your service instance ID, you can obtain a service instance token in one of two ways:

With the Cloud Pak for Data web interface.
With the Cloud Pak for Data API.

Tip: Service instance tokens expire 20 minutes after creation.

Retrieving the service instance token with the Cloud Pak for Data web interface

To retrieve the service instance token by using the Cloud Pak for Data web interface:

Log into the Cloud Pak for Data web interface.
Navigate to My Instances, then select the appropriate Master Data Connect instance.
Click View details.

The service instance token is displayed in the Access Information section.

Retrieving the service instance token with the Cloud Pak for Data API

To retrieve the service instance token by using the /zen-data/v2/serviceInstance/token API, run the following cURL command:

curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/token' -H 'Authorization: Bearer <PLATFORM_TOKEN> \
-d '{ 
   "serviceInstanceID": "<PROVISIONED_INSTANCE_ID>",
   "expiryTime:" <EXPIRY_TIME>
}'

Replace the following values in the cURL command:

<CPD_CLUSTER_HOST>:<PORT> - Your Cloud Pak for Data cluster host and port.
<PLATFORM_TOKEN> - The user platform token.
<PROVISIONED_INSTANCE_ID> - The instance ID of your provisioned instance.
<EXPIRY_TIME> - The token expiry time in minutes.

The expiryTime field is optional. If it is not provided, the default expiry time is 20 minutes.

This command produces the following the following JSON response:

{
   "AccessToken":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b20iOnsiTW9kdWxlTmFtZSI6ImV6LWhlbG0tYXBwIiwiUm9sZSI6IkFkbWluIiwiU2VydmljZUluc3RhbmNlRGlzcGxheU5hbWUiOiJzYW1wbGUtMCIsIlNlcnZpY2VJbnN0YW5jZUlEIjoiMTU4MjUxMDY1Mzg5NCIsIlNlcnZpY2VJbnN0YW5jZVVzZXJOYW1lIjoiYWRtaW4iLCJaZW5EaXNwbGF5TmFtZSI6ImFkbWluIiwiWmVuVUlEIjoiMTAwMDMzMDk5OSIsIlplblVzZXJuYW1lIjoiYWRtaW4ifSwiZXhwIjoxNTgyNTE0NDQxLCJpYXQiOjE1ODI1MTMyNDEsImlzcyI6IklDUEQiLCJzdWIiOiJhZG1pbiIsInVpZCI6IjEwMDAzMzA5OTkifQ.FvtYQKkmIP5vguYGd7TVd-iD7Y4Z-KoTM1p-YlSCDzCzU7rnjogkOfF_0WCblUQQscliTzkV-YcjtfUxgXzObbKpu27oR1F85Z5PcBkMMhtVoxPw41Y9UeEpOy_2uYOr8aK8aJALHuG1W8VuOXoPI4oKh3cJM0M225xn0BK0_dTaVAioDVWiC8o0MDDn6uFDLEymM_U8JzZTFJbqzHUIlbmDphO4GbX28KduZvlrUVDzZ3hQPThUn-YnToLtYcKFWsdULWJHr4CCpPm5ZXGDAvjzTSonk8ktrMhHSgRV3loRhvtftXEZYfKQDGzhvAiKi7Ilv7OX85gJau_LgWv0iA",
   "TokenPayload":{
      "ModuleName":"mdc-app",
      "Role":"MDC-Manager",
      "ServiceInstanceDisplayName":"mdc-app-1",
      "ServiceInstanceID":"1582510653894",
      "ServiceInstanceUserName":"jsmith",
      "ZenDisplayName":"john smith",
      "ZenUID":"1000330999",
      "ZenUsername":"jsmith"
   }
}

The access token will be returned in the AccessToken property of the JSON response.

Note: Access tokens are only valid for a particular instance of Master Data Connect.

Using the service instance token to authorize your Master Data Connect API calls

You can pass the service instance token to authorize your Master Data Connect API calls in two ways:

Using the Authorize feature of the API Explorer user interface.
In the Authorization header of an API request.

Providing the service instance token with the Authorize feature of API Explorer

Navigate to the Swagger UI API Explorer by browsing to https://<CPD_CLUSTER_HOST>:<PORT>/api-cache/explorer

Replace the <CPD_CLUSTER_HOST>:<PORT> values in the above URL with your Cloud Pak for Data cluster host and port.

In the API Explorer, complete the following steps:

Click Authorize at the top of the page
Enter the instance token obtained from the Obtaining a service instance token section of this page.
Click Authorize and then click Close.

The API Explorer passes your service instance token automatically for every API invoked from the API Explorer page.

Providing the service instance token in an Authorization header of an API request

To provide the service instance token in an Authorization header of an API request, run the following cURL command:

curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/<API_PATH>' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

Replace the following values in the cURL command:

<CPD_CLUSTER_HOST>:<PORT> - Your Cloud Pak for Data cluster host and port.
<API_PATH> - The path of your desired API (such as /mdm/cache/v1/jobs).
<PLATFORM_TOKEN> - The user platform token.