Using the CLI with High Assurance Resources

Overview

High assurance resources require that users authenticate with specific identities or identity providers within a certain period of time.

Globus Auth maintains a session containing the identities and timestamps of authentications to an instance of the CLI. This session is associated with the browser session used for authentication, but is separate from any other sessions used to access high assurance resources.

This doc will go over the CLI commands needed to use the CLI’s session to access high assurance resources, along with errors that will be given by the CLI when a high assurance resource requires re-authentication.

Logging in

The CLI’s session is created on log in, and the identity you use to log in is added to the session.

$ globus login

Logging out

After you have finished using the Globus CLI with high assurance resources you should always log out with the globus logout command.

$ globus logout

This closes the CLI’s session and revokes all tokens used for authorizing the CLI to act on your behalf. If you are ever unsure if your logout was successful you should check the status of the CLI’s consents at https://auth.globus.org/consents and revoke any unwanted consents.

Viewing the CLI’s session

You can view the CLI’s session state with the globus session show command which lists all identities in the CLI’s current session along with each identity’s most recent authentication time.

$ globus session show
For information on your primary identity or full identity set see
  globus whoami

Username          | ID                                   | Auth Time
------------------| ------------------------------------ | --------------------
user@domain1.org  | e8d90b08-9a5f-11e8-914b-9cb6d0d9fd63 | 2018-08-29 14:49 CDT
user@domain2.org  | fac363a4-9a5f-11e8-914b-9cb6d0d9fd63 | 2018-08-29 15:01 CDT

As hinted by the command, this output is similar to the globus whoami command, but will not show identities that are not in session even if they are in your identity set.

If you need your session id for debugging purposes, it can be found in the output of globus session show --format json.

Updating the CLI’s session

You can update the CLI’s session state with the globus session update command.

globus session update takes one or more identities in user@domain or UUID format, and starts an authentication flow that adds or refreshes them in the CLI’s session. These identities must already be in your identity set.

$ globus session update user@domain1.org user@domain2.org
You are running 'globus session update', which should automatically open a
browser window for you to authenticate with specific identities.
If this fails or you experience difficulty, try 'globus session update
--no-local-server'
---
Created new window in existing browser session.

You have successfully updated your CLI session.
Use 'globus session show' to see the updated session.

If you are ever unsure which of your linked identities grant you access to a specific high assurance resource, you can use the --all option to start an authentication flow with each of your linked identities.

Understanding Errors from High Assurance Resources

Whenever an action you attempt is denied because your session state is not sufficient, the service will do its best to determine which of your identities you need to re-authenticate with to gain access.

For example a globus ls that fails because an identity is not in session:

$ globus ls 2b598208-9a6c-11e8-914b-9cb6d0d9fd63
The resource you are trying to access requires you to re-authenticate with specific identities.
message: Session reauthentication required (Globus Transfer)
Please run

    globus session update e8d90b08-9a5f-11e8-914b-9cb6d0d9fd63

to re-authenticate with the required identities

It is possible that the recommended globus session update command will list more identities than required, and if the action touches multiple high assurance resources it is possible that you will get back separate errors from each resource before being able to proceed.

If none of your linked identities would give you access to the resource, you will not receive a recommended globus session update command. If this happens, first check that you are using the correct identity set by running globus whoami --linked-identities, then confirm with the resource owner that one of those identities has been given access to the resource.