Authentication

To be able to use interfaces such as the Watson Machine Learning REST API and Watson Machine Learning Python client library, you need to authenticate with the Watson Machine Learning repository.

How you authenticate depends on:

As an alternative, you can use the username and apikey combination to authenticate. You can retrieve your API key from UI by going to your profile page, and clicking the API key button.

Example of using a username and apikey combination:

wml_credentials = {
    "username": "<username>",
    "apikey": "<apikey>", 
    "instance_id" : "openshift",
    "url": <web client url>,
    "version": "4.0"
}

Note: For <web client url>, refer to Finding the web client url.

Authenticating from a notebook from within Watson Studio

Watson Machine Learning requires a bearer token to authenticate the user calling the REST APIs. The token expires after 12 hours. To access a token when you create a notebook in Watson Studio, use the predefined variable 'USER_ACCESS_TOKEN':

import os
token = os.environ['USER_ACCESS_TOKEN']

Alternatively, you can retrieve a bearer token from the user management service using an API call:

For information on how to use the token, refer to Using the token to authenticate with the server.

Getting a bearer token with IAM integration disabled

  1. Find your web client url. Refer to Finding the web client url.

You will use the <web client url> in next steps.

  1. Type this command:
curl -k -X POST <web client url>/icp4d-api/v1/authorize -H ‘cache-control: no-cache’ -H ‘content-type: application/json’ -d ‘{"username":"<username>","password":"<password>"}’

Where you specify your username and password for accessing the Cloud Pak for Data cluster.

  1. The call returns a JSON snippet from which the bearer token can be extracted from the access_token field:
{
  "username": "admin",
  "role": "Admin",
  "permissions": [
    "administrator"
  ],
  "sub": "admin",
  "iss": "KNOXSSO",
  "aud": "DSX",
  "uid": "999",
  "authenticator": "default",
  "access_token": "<bearer token>",
  "_messageCode_": "success"
  ....
}
  1. Copy the token to your Python program.

Getting a bearer token with IAM integration enabled

  1. Find the IBM Cloud Pak foundational services URL. Refer to Finding the IBM Cloud Pak foundational services URL.

You will use the <foundational services url> in next steps.

  1. Find your web client url. Refer to Finding the web client url.

You will use the <web client url> in next steps.

  1. Obtain the temporary IAM access token:
curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
-d "grant_type=password&username=<username>&password=<password>&scope=openid" \
<foundational services url>/idprovider/v1/auth/identitytoken
  1. Using the IAM access token, request the bearer token:
curl -k X GET '<web client url>/v1/preauth/validateAuth' \
-H 'username: admin' \
-H 'iam-token: <iam token>'
  1. Copy the token to your Python program.

Using the token to authenticate with the server

  1. Find your web client url. Refer to Finding the web client url.

You will use the <web client url> in next steps.

Use your bearer token to connect to the server. This will mask your user credentials:

wml_credentials = {
"token": "<token>",
"instance_id" : "openshift",
"url": "<web client url>",
"version": "4.0"
}

from ibm_watson_machine_learning import APIClient
client = APIClient(wml_credentials)

For troubleshooting, refer to the Troubleshooting section.

Authenticating the Python client from outside of Watson Studio

If you are not storing your notebook within Watson Studio, you can bypass retrieving a token and authenticate with your Cloud Pak for Data credentials.

  1. Find your web client url. Refer to Finding the web client url.

You will use the <web client url> in next steps.

  1. To authenticate, type the following:
wml_credentials = {
    "instance_id" : "openshift",
    "url"         : "<web client url>",
    "username"    : "<username>",
    "password"    : "<password>",
    "version"     : "4.0"
}

from ibm_watson_machine_learning import APIClient
wml_client = APIClient(wml_credentials)

For an example of using authentication with a notebook, refer to Machine Learning Python samples and examples.

For troubleshooting, refer to the Troubleshooting section.

Troubleshooting

If you receive this message when creating an instance of the client:

Attempt of generating `bedrock_url` automatically failed. If iamintegration=True, please provide `bedrock_url` in wml_credentials. If iamintegration=False, please validate your credentials.

Check the contents of the wml_credentials dictionary for errors. If there are no errors and the issue still appears, check if during CPD installation the iamintegration parameter was set to True

If the iamintegration parameter was set to True, try adding this line of code to the wml_credentials dictionary:

"bedrock_url": "<foundational services url>"

Refer to Finding the IBM Cloud Pak foundational services URL.

Finding the IBM Cloud Pak foundational services URL

The IBM Cloud Pak foundational services URL is the OpenShift route created by IBM Common Services. By default, the IBM Cloud Pak foundational services namespace is ibm-common-services, so you can find the IBM Cloud Pak foundational services URL by typing this command:

oc get routes -n ibm-common-services

The command returns the following output:

NAME                HOST/PORT                     PATH   SERVICES                   PORT    TERMINATION            WILDCARD
<cp-console>        <foundational services url>          <service name>             https   reencrypt/Redirect     None
<cp-proxy>          <proxy URL>                          <service name>             https   passthrough/Redirect   None

Finding the web client url

To find the web client url, view the details for the service instance from the address field in the web client.

For example, if your web browser shows this path when you are logged in to Watson Studio:

https://some-route.apps.your.server.company.com/<xyz>

Then, the web client url parameter must be set to
https://some-route.apps.your.server.company.com

For details, refer to Endpoint URLs

Learn more

For real-life authentication examples, refer to sample notebooks:

Parent topic: Deploying and managing models and functions