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:
- whether you are using a notebook within Watson Studio or whether you are accessing Watson Machine Learning from outside the cluster
- whether IAM (Identity and Access Management) authentication is enabled or disabled (by default, during CPD installation the
iamintegration
parameter is set toFalse
)
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:
- If IAM integration was disabled during installation (default setting), refer to Geting a bearer token with IAM integration disabled.
- If IAM integration was enabled during installation, refer to Getting a bearer token with IAM integration enabled.
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
- Find your web client url. Refer to Finding the web client url.
You will use the <web client url>
in next steps.
- 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.
- 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"
....
}
- Copy the token to your Python program.
Getting a bearer token with IAM integration enabled
- 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.
- Find your web client url. Refer to Finding the web client url.
You will use the <web client url>
in next steps.
- 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
- 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>'
- Copy the token to your Python program.
Using the token to authenticate with the server
- 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.
- Find your web client url. Refer to Finding the web client url.
You will use the <web client url>
in next steps.
- 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:
- View a full set of Machine Learning python client sample notebooks.
- View a full set of Machine Learning REST API sample notebooks.
Parent topic: Deploying and managing models and functions