User Authentication

Grant access to users and identify and filter activity by user

Sharing access to training sessions and shared models in a simple and secure manner is a key requirement for many data custodians. integrate.ai provides a secure method of authenticating end users with limited permissions through the SDK to enable privileged access.

As the user responsible for managing access through the integrate.ai platform, you have the ability to generate an unscoped API token through the integrate.ai UI. Unscoped API tokens provide full access to the integrate.ai SDK. You can run client training tasks locally, or on remote data.

In the case that you want to create a token that has limited access, to enforce governance standards or provide an end user of your platform with limited access to the integrate.ai SDK, you can create scoped API tokens. Scoped tokens grant limited permissions, which enables you to control the level of access to trained sessions and models.

In the UI, you can view your personal API tokens as well as all scoped API tokens created in your organization's workspace through the SDK. These scoped user tokens are designed for use with the integrate.ai SDK. Tokens are tied to user identities through a unique ID, which is logged with each user action.

Limiting user access by token greatly reduces the security risk of leaked credentials. For example, with an unscoped API token, a user could run tasks on a remote machine, where there is a risk that it could be leaked or exposed because it is shared in an outside (non-local) environment. To mitigate that risk, you can instead provide the user with a scoped token that has limited permissions and a short lifespan (maximum 30 days).

Create an unscoped token

As the user who manages other users' access, you must first create your own unscoped token.

1. Log in to your integrate.ai account on the web.

2. On the Dashboard, click Generate Access Token.

3. Copy the access token and save it to a secure location.

This is the only time that the API token can be viewed or downloaded. If you lose or forget your API token, you cannot retrieve it. Instead, create a new API token and revoke the old one. You can manage API tokens through the web portal.

Treat your API tokens like passwords and keep them secret. When working with the API, use the token as an environment variable instead of hardcoding it into your programs. In this documentation, the token is referenced as <IAI_TOKEN>.

Install components

Install the integrate.ai command-line tool (CLI), the SDK, and the client.

Open sample notebook

Open the Authentication sample notebook (integrateai_auth.ipynb) located in the SDK package.

..integrate_ai_sdk/src/integrate_ai_sdk/sample_packages/sample_notebook/

The notebook provides sample code that demonstrates how to use the SDK to generate users and tokens.

Managing User Access through the SDK

Create a connection to the auth client with your unscoped token.

from integrate_ai_sdk.auth import connect_to_auth_client
from integrate_ai_sdk.auth.scopes import Scope
import os
IAI_TOKEN = os.environ.get("IAI_TOKEN")
auth_client = connect_to_auth_client(token=IAI_TOKEN)

Create a user

Create a user. Specify a user name (for example, demo-user, or [e-mail]).

user_name = '{user_name}'
user = auth_client.create_user(user_name)

The SDK generates a unique ID for the user in the integrate.ai platform.

Example output:

01/27/2023 11:20:24:INFO:Machine user demo-user([e-mail]) created by <your-email>.
01/27/2023 11:20:24:INFO:User activated.

Create a scoped user token

Create a scoped token for the user.

Include only the scopes that the user requires to work with the system and their data.

token = auth_client.create_token(user_id=user_name, scopes=[Scope.create_session, Scope.read_user_session])
print(token)p

This request returns the unique user ID (the generated email), a list of the granted scopes, and the token, as well as the token ID and the user name.

Copy and save the token somewhere secure to share with the user.

Available Scopes

Scope name	Definition
create_session	Allows a user to create a training session.
start_session	Allows a user to start a training session that they have created.
custom_model	Allows a user to upload and use a custom model.
model_download	Allows a user to download a trained model.
cancel_user_session	Allows a user to cancel a session that they have created. This scope does not allow a user to cancel any other user's sessions.
delete_user_session	Allows a user to delete a session that they have created. This scope does not allow a user to delete any other user's sessions.
read_user_session	Allows a user to read a session that they have created. This scope does not allow a user to read any other user's sessions.
read_all_session	Allows a user to read a session created by any user.
cli	Allows a user to list versions and install the integrate_ai_sdk and docker images through the IAI cli. Required if the user is going to work with the IAI SDK directly.
revoke_user_token	Allows a user to revoke a token they have created.

User and token management

Verify user and token through the SDK

The token_info command allows you to inspect the details of a token. You must specify the token to inspect.

auth_client.token_info(token['token'])

Example output:

{'customer': 'your-environment-name',
 'email': '[e-mail]',
 'realm': 'ifl',
 'role': 'admin',
 'env': 'prod',
 'token_id': '55a19b5d077d40a798aa51ace57168c3',
 'iss': 'integrate.ai',
 'iat': 1674832855,
 'renewable': True,
 'scope': 'create_session read_model read_session read_user_session',
 'user_id': 'demo-user',
 'user_type': 'generated',  //Indicates whether the user was created through the SDK
 'active': True}

Verify user and token through the UI

To confirm that the user and token were created successfully, you can also view them in the web dashboard.

1. Log in to the web dashboard.

2. Click Token Management.

3. Click User Scoped Tokens.

4. Locate the user name for the user you created.

Revoke a scoped token

User scoped tokens have a default lifespan of thirty (30) days. To revoke a token before it expires, use the revoke_token command in the SDK.

You must provide the token_id for the token that you want to revoke.

auth_client.revoke_token(token['token_id'])

Delete a user

Users that you create through the SDK can be deleted through the SDK.

Specify the name of the user that you want to delete.

auth_client.delete_user(user_name)