Managing Toolbelt Sessions¶

Toolbelt provides a client-side tool for access to the Aunsight platform. As part of its communication with the Aunsight platform services, Toolbelt manages access tokens obtained from the Aunsight identity service. These tokens serve as the authentication mechanism for requests to the platform, and can be obtained, stored, and renewed using specific Toolbelt commands. The present article describes how to manage Toolbelt sessions by logging in, viewing and renewing a token, and logging out. After reading this article, Toolbelt users will be able to authenticate and manage Toolbelt sessions using the command line interface.

Logging In¶

To initiate a session in the Toolbelt, type au2 login at the terminal and enter your username and password when prompted.

$ au2 login
email: [email protected]
password:

Upon successful log-on, the Toolbelt will acquire a session token from the Aunsight platform services and display it in the terminal. Users do not need to do anything with this token, since it is automatically stored in the file location specified in the Toolbelt configuration. This token will provides access to the Aunsight platform for twenty-four hours or the user logs off. Users can either also extend the length of their session by renewing their token.

Displaying Information about the Current Session Token¶

Logging in to Aunsight obtains a token that is used to authenticate requests to the platform services. The au2 context token-info command displays information about this token and its expiration

$ au2 context token-info
Issued at Mon Feb 03 2020 10:58:44 GMT-0500 (EST)
Expires at Mon Feb 03 2020 10:58:44 GMT-0500 (EST)
Orginally issued at Mon Feb 03 2020 10:58:44 GMT-0500 (EST)
Expires in a day

Displaying the Current User's information¶

Once a session has been initiated, au2 context whoami will display information about the user associated with the current session.

$ au2 context whoami
┌───────────┬─────────────────────────────────────────┐
│ firstname │ Benjamin                                │
├───────────┼─────────────────────────────────────────┤
│ lastname  │ Wright                                  │
├───────────┼─────────────────────────────────────────┤
│ email     │ [email protected]          │
├───────────┼─────────────────────────────────────────┤
│ id        │ 0221668b-58f1-4102-a8c5-3ad228edf54d    │
├───────────┼─────────────────────────────────────────┤
│ active    │ true                                    │
└───────────┴─────────────────────────────────────────┘

Renewing a Token¶

Session tokens expire twenty-four hours after their issue. After this, the Aunsight services will no longer respond to calls using the expired token, and users will need to acquire a new token by logging in again.

As a convenience, users can renew their token without re-entering credentials with the following command:

au2 context renew-token

This command will request a new token from the Aunsight platform services, granting an additional twenty-four hours to the current session time-out. This command can be used to keep alive a session that is about to expire.

Logging Out¶

If you wish to end a session before a token expires, simply log out of the current session.

au2 logout

This deletes the token stored in a temporary file (by default, /tmp/aunsight-token.json) requiring a new token before further API calls can be issued by the Toolbelt.

Setting Up A Persistent Token¶

In addition to the interactive login process, Toolbelt can be configured to use a managed token to mediate access to the Aunsight API. There are many reasons why you might want to use a managed token in place of username/password credentials:

In non-interactive contexts (e.g. Aunsight process images)
In a local script designed to executed without user interaction.
Because it's easier than having to enter a username and password every day.

Step 1: Create a New Token¶

To configure Toolbelt to use a managed token, you must first create a managed token using the Aunsight Web Interface.

It is a general best practice for a unique managed token to be created for each use case and clearly named it for its intended purpose. For example, My_Macbook_Login_Token or ClientX_SmartFeature_Scoring_Process. Following this practice, if a token is compromised (e.g. it is stolen out of a container image, a source code repository, or from a compromised workstation filesystem) that token can be deactivated without interrupting other uses.

Tip

It's a good practice to create a separate token for each use case so that token access can be monitored and deactivated individually.

Once you have created a token for your intended use case, copy down its GUID for use in the configuration object.

Step 2: Create a Configuration Object¶

When Toolbelt passes a request onto the Aunsight API, the authentication token it passes in the body of the request is copied from the local environment's filesystem at /tmp/aunsight-token.json.

Whatever environment you are using (MacOS workstation, a Docker Linux base image, etc.), this file can be overwritten to "mimic" the effect of issuing the au2 login command.

To do this, open a text editor and edit the contents of /tmp/aunsight-token.json to the following:

{
  "token": "<MANAGED-TOKEN-GUID>"
}

Replace <MANAGED-TOKEN-GUID> in the above example to the GUID you copied down in step one and save the file.

From this point on, Toolbelt will pass a managed token rather than the default, 24-hour token created when you issue the au2 login command.

Keep in mind that /tmp/aunsight-token.json gets overwritten periodically either when the you issue the au2 login or au2 logout commands or for some other reason (e.g. environment/filesystem cleanup utilities that purge directories like /tmp/ and /var/).