Merge pull request #31 from SD2E/devel

managing multiple credentials

Author: wjallen

docs/01.authorization.md

@@ -53,9 +53,10 @@ new token with:
 % auth-tokens-create -S
 ```
 
-If errors persist, generate a new client:
+If errors persist, generate a new client and a new token:
 ```
 % clients-create -S
+% auth-tokens-create -S
 ```
 
 ---

docs/01.manage_tokens.md

@@ -0,0 +1,148 @@
+---
+layout: page
+title: Manage Multiple Accounts or Tenants
+tagline:
+---
+
+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.
+
+
+<br>
+#### 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`:
+``` json
+% 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
+```
+
+<br>
+#### 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`.
+
+
+<br>
+#### 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.
+
+
+<br>
+#### 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.
+
+<br>
+*Tip: For more information, including how to automatically refresh the token on
+switching credentials, use '`auth-switch -h`'*
+
+---
+Return to the [API Documentation Overview](../index.md)

index.md

@@ -21,7 +21,9 @@ the SD2E platform. Documentation for getting started with the SD2E API is below.
 
     1.4 [Authorize with the SD2E Tenant](docs/01.authorization.md)
 
-    1.5 [SSH Key Pairs](docs/01.ssh_keys.md)
+    1.5 [Manage Multiple Accounts or Tenants](docs/01.manage_tokens.md)
+
+    1.6 [SSH Key Pairs](docs/01.ssh_keys.md)
 
 
   **2 Agave CLI Essentials**