Wallaroo MLOps API Essentials Guide

Retrieve Credentials

Through the Wallaroo Administrative Service

Wallaroo comes pre-installed with a confidential OpenID Connect client. The default client is api-client, but other clients may be created and configured.

Confidential clients require its secret to be supplied when requesting a token. Administrators may obtain their API client credentials from from the authentication URL /auth/admin/master/console/#/realms/master/clients.

For example, if the Wallaroo DNS address is https://wallaroo.example.com, then the direct path to the API client credentials is:

https://wallaroo.example.com/auth/admin/master/console/#/realms/master/clients

For this example, we are using the confidential client secret for api-client, which is found in the Wallaroo Authentication Service accessed by users with the role admin through the URL https://$WALLAROO_DOMAIN/auth. For more details, see How to Access the User Authentication Service. For this example, this is the secret for the user api-client. This is retrieved by:

1. Access the Wallaroo Authentication Service URL.
2. Select Administration Console.
3. Logging in with a user with the role admin.
4. Select Clients, then api-client.
5. From the api-client page, select Credentials, then copy the client secret and store it in a safe location.

By default, tokens issued for api-client are valid for up to 60 minutes. Refresh tokens are supported.

Token Types

There are two tokens used with Wallaroo API services:

• MLOps tokens: User tokens are generated with the confidential client credentials and the username/password of the Wallaroo user making the MLOps API request and requires:

  • The Wallaroo instance authentication address.

  • The confidential client, api-client by default. For the examples below, we will refer to it as CONFIDENTIAL_CLIENT.

  • The confidential client secret.

  • The Wallaroo username making the MLOps API request.

  • The Wallaroo user’s password.

    This request return includes the access_token and the refresh_token. The access_token is used to authenticate. The refresh_token can be used to create a new token without submitting the original username and password.

    A sample curl version of that request is:

    eval $(curl "https://$WALLAROO_DOMAIN/auth/realms/master/protocol/openid-connect/token" -u "${CONFIDENTIAL_CLIENT}:${CONFIDENTIAL_CLIENT_SECRET}" -d -d 'grant_type=client_credentials' -s | jq -r '.access_token')
    

    • Tokens can be refreshed via a refresh request and require:

      • The confidential client, api-client by default.

      • The confidential client secret.

      • The refresh token retrieved from the initial access token request. A curl version of that request is:

        TOKEN=$(curl "https://$WALLAROO_DOMAIN/auth/realms/master/protocol/openid-connect/token" -u "${CONFIDENTIAL_CLIENT}:${CONFIDENTIAL_CLIENT_SECRET}" -d "grant_type=refresh_token&refresh_token=${REFRESH}" -s | jq -r '.access_token')
        

• Inference Token: Tokens used as part of a Pipeline Inference URL request. These do not require a Wallaroo user credentials. Inference token request require the following:

  • The Wallaroo instance authentication address.

  • The confidential client, api-client by default.

  • The confidential client secret.

    A curl version of that command is:

    TOKEN=$(curl "https://${WALLAROO_DOMAIN}/auth/realms/master/protocol/openid-connect/token" -u "${CONFIDENTIAL_CLIENT}:${CONFIDENTIAL_CLIENT_SECRET}" -d 'grant_type=client_credentials' -s | jq -r '.access_token')
    

The following examples demonstrate:

• Generating a MLOps API token with the confidential client, client secret, username, and password.
• Refreshing a MLOps API token with the confidential client and client secret (the username and password are not required for refreshing the token).
• Generate a Pipeline Inference URl token with the confidential client and client secret (username and password are not required).

The username and password for the user are stored in the file ./creds.json to prevent them from being displayed in a demonstration.

## Generating token with confidential client, client secret, username, password

TOKENURL=f'https://{WALLAROO_DOMAIN}/auth/realms/master/protocol/openid-connect/token'

USERNAME = login_data["username"]
PASSWORD = login_data["password"]
CONFIDENTIAL_CLIENT=login_data["confidentialClient"]
CONFIDENTIAL_CLIENT_SECRET=login_data["confidentialPassword"]

auth = HTTPBasicAuth(CONFIDENTIAL_CLIENT, CONFIDENTIAL_CLIENT_SECRET)
data = {
    'grant_type': 'password',
    'username': USERNAME,
    'password': PASSWORD
}
response = requests.post(TOKENURL, auth=auth, data=data, verify=True)
access_token = response.json()['access_token']
refresh_token = response.json()['refresh_token']
display(access_token)

'abcdefg'

## Refresh the token

TOKENURL=f'https://{WALLAROO_DOMAIN}/auth/realms/master/protocol/openid-connect/token'

# Retrieving through os environmental variables 
f = open('./creds.json')
login_data = json.load(f)

CONFIDENTIAL_CLIENT=login_data["confidentialClient"]
CONFIDENTIAL_CLIENT_SECRET=login_data["confidentialPassword"]

auth = HTTPBasicAuth(CONFIDENTIAL_CLIENT, CONFIDENTIAL_CLIENT_SECRET)
data = {
    'grant_type': 'refresh_token',
    'refresh_token': refresh_token
}
response = requests.post(TOKENURL, auth=auth, data=data, verify=True)
access_token = response.json()['access_token']
refresh_token = response.json()['refresh_token']
display(access_token)

'abcdefg'

## Pipeline Inference URL token - does not require Wallaroo username/password.

TOKENURL=f'https://{WALLAROO_DOMAIN}/auth/realms/master/protocol/openid-connect/token'

# Retrieving through os environmental variables 
f = open('./creds.json')
login_data = json.load(f)

CONFIDENTIAL_CLIENT=login_data["confidentialClient"]
CLIENT_SECRET=login_data["confidentialPassword"]

auth = HTTPBasicAuth(CONFIDENTIAL_CLIENT, CLIENT_SECRET)
data = {
    'grant_type': 'client_credentials'
}
response = requests.post(TOKENURL, auth=auth, data=data, verify=True)
inference_access_token = response.json()['access_token']
display(inference_access_token)

'abc123'

Through the Wallaroo SDK

The Wallaroo SDK method Wallaroo Client wl.auth.auth_header() method provides the token with the Authorization header.

# Retrieve the token
headers = wl.auth.auth_header()
display(headers)

{'Authorization': 'Bearer abcdefg'}

Connect to Wallaroo

For this example, a connection to the Wallaroo SDK is used. This will be used to retrieve the JWT token for the MLOps API calls.

This example will store the user’s credentials into the file ./creds.json which contains the following:

{
    "username": "{Connecting User's Username}", 
    "password": "{Connecting User's Password}", 
    "email": "{Connecting User's Email Address}"
}

Replace the username, password, and email fields with the user account connecting to the Wallaroo instance. This allows a seamless connection to the Wallaroo instance and bypasses the standard browser based confirmation link. For more information, see the Wallaroo SDK Essentials Guide: Client Connection.

Enter the Wallaroo Domain for your Wallaroo instance, in this code snippet is wallaroo.example.com.

# Retrieve the login credentials.
os.environ["WALLAROO_SDK_CREDENTIALS"] = './creds.json'

WALLAROO_DOMAIN = "wallaroo.example.com"

wl = wallaroo.Client(api_endpoint=f"https://"{WALLAROO_DOMAIN},
                     auth_type="user_password")

API URL

The variable APIURL is used to specify the connection to the Wallaroo instance’s MLOps API URL.

WALLAROO_DOMAIN = "wallaroo.example.com"

APIURL=f"https://{WALLAROO_DOMAIN}/v1/api"

API Request Methods

This tutorial relies on the Python requests library, and the Wallaroo Wallaroo Client wl.auth.auth_header() method.

MLOps API requests are always POST. Most are submitted with the header 'Content-Type':'application/json' unless specified otherwise.