Skip to content
This repository has been archived by the owner on Mar 29, 2022. It is now read-only.

Latest commit

 

History

History
148 lines (120 loc) · 4.42 KB

01.manage_tokens.md

File metadata and controls

148 lines (120 loc) · 4.42 KB
layout title tagline
page
Manage Multiple Accounts or Tenants

You may find yourself in a situation where you need to switch between different accounts and/or tenants. The Agave CLI has a tool called auth-switch to help manage multiple configuration files.


#### List current API configuration

API configurations are stored in json-formatted files in the ~/.agave/ directory. You can list and examine the contents of your configurations with simple Linux commands. If you have been following along with this user guide, you likely only have one configuration file called current:

% ls ~/.agave/
current

% cat ~/.agave/current | jq
{
  "tenantid": "sd2e",
  "baseurl": "https://api.sd2e.org",
  "devurl": "",
  "apisecret": "4q5qBcWoTXi72f9QsaU8xyNuXtIP",
  "apikey": "0WKfV1TkjuoAr8s5RWOV0Y9QTv0Q",
  "username": "username",
  "access_token": "a249cc980b50dd541a82b1c55d0",
  "refresh_token": "97d84c757b01a68d0cc30b285a8",
  "created_at": "1530890375",
  "expires_in": "14400",
  "expires_at": "Fri Jul  6 14:19:35 CDT 2018"
}

Running the command auth-switch without any options will display a table of known API configurations, and in this case, it will make a copy of the configuration with a slightly different name::

% auth-switch
| tenant | username | active |
| ------ | -------- | ------ |
| sd2e   | username | true   |

% ls ~/.agave/
current       current#sd2e#username

#### Initialize with another tenant

Now, in order to have multiple configurations to switch back and forth, we will set up a new API configuration to interact with the TACC Production tenant. A user may need to do this if they are working on multiple projects that both use the Agave API:

# Initialize with the tenant
% tenants-init -t tacc.prod

Your CLI is now configured to interact with APIs owned by 'tacc.prod'.
Use 'clients-create' to set up a new API client or 'auth-tokens-create' to re-use an existing API key and secret.

# Create a new client for interacting with the tenant
% clients-create -S
The name of the client application : my_client
API username : username
API password:
Successfully created client my_client

# Create a new authorization token
% auth-tokens-create -S
API password:
Token for tacc.prod:username successfully refreshed and cached for 14400 seconds
57a301c948a562cc810bb40d09a2c713

Behind the scenes, the contents of ~/.agave/current have been replaced with a new configuration. The former SD2E configuration was stored in ~/.agave/current#sd2e#username.


#### Switch between configurations

Finally, use auth-switch one more time to switch from the TACC Production tenant back to the SD2E tenant:

% auth-switch -t sd2e
Active config now sd2e/username

% auth-switch
| tenant    | username | active |
| ------    | -------- | ------ |
| sd2e      | username | true   |
| tacc.prod | username | false  |

% ls ~/.agave/
current            current#sd2e#username            current#tacc.prod#username

Switching back to the SD2E tenant has also triggered the creation of current#tacc.prod#username, so both tenants are backed up and the user can easily switch between them. Agave uses only the contents of ~/.agave/current and ignores the other files.


#### Initialize with another username

In this final example, we will initialize with a second username on the SD2E tenant. This situation may arise if you manage a community account, if you share a workstation with another user, or if you are pair programming with another user. Having multiple API configurations on the same machine is acceptable, but please never share your TACC password with anyone.

# Authenticate as a new user
% tenants-init -t sd2e
% clients-create -S -u user2
% auth-tokens-create -S

# Switch to original user
% auth-switch -t sd2e -u username

# List all configurations
% auth-switch
| tenant    | username | active |
| ------    | -------- | ------ |
| sd2e      | user2    | false  |
| sd2e      | username | true   |
| tacc.prod | username | false  |

% ls ~/.agave/
current                         current#sd2e#username
current#sd2e#user2              current#tacc.prod#username

Notice that since multiple credentials were available for the SD2E tenant, the username also had to be specified with -u on the command line.


*Tip: For more information, including how to automatically refresh the token on switching credentials, use '`auth-switch -h`'*

Return to the API Documentation Overview