Chapter 3. Authentication

3.1. Authorization Tokens

3.1.1. Introduction to Authorization Tokens

An authorization token is a secret value that is used to automatically log in to an OpenShift Online account without entering login information each time. A token is also used to grant another user full or partial access to an account, determined by the scope of the token. The following table describes the different types of scopes available with authorization tokens.

Table 3.1. Authorization Token Scopes

Scope Description Validity
session Access to all API functions against an account. 1 day
read Read-only access to account resources, but cannot view authorization tokens. 1 month
userinfo Access to login name, unique id, and user capabilities. 1 month
When the client tools are installed and the rhc setup command is initially run to configure the client tools, the setup wizard prompts you to create an authorization token. If you answer YES, the wizard creates a session token in the ~/.openshift directory. With this token, all client tool commands can be run without entering your login credentials each time. When the token expires you are automatically prompted to reenter login information to renew the existing token. See the OpenShift Online Client Tools Installation Guide for more information on installing and configuring the client tools.
If an authorization token was not created when the client tools were installed, run the setup wizard again with the rhc setup command to create one.
If an existing authorization token is no longer required and you do not wish to be prompted for token renewal, run the rhc logout command to delete the token.

3.1.2. Creating Authorization Tokens

Create a new authorization token with the following command:
$ rhc authorization add --scopes Scope --note Name
Specify the scope for the token with the --scopes option, and a name for the token with the --note option.

Example 3.1. Creating an Authorization Token

rhc authorization add --scopes session --note My_Token
Adding authorization ... done

My_token
--------
  Token:      787a57211d42f251204136b05d490038830d9b7057f54f816c2a9fcd0c8333b8
  Scopes:     session
  Created:    4:40 PM
  Expires In: about 1 day
After creating a new authorization token, use the --token token_string global option to run rhc commands as the user associated with the authorization token that was provided.

3.1.3. Viewing Authorization Tokens

View the tokens associated with your account with the following command:
$ rhc authorization list

Example 3.2. Viewing Authorization Tokens

$ rhc authorization list
My_token
--------
  Token:      787a57211d42f251204136b05d490038830d9b7057f54f816c2a9fcd0c8333b8
  Scopes:     session
  Created:    4:40 PM
  Expires In: about 23 hours

RHC/1.8.0 (from laptop.example.com on x86_64-linux)
---------------------------------------------------
  Token:      28f6e375dc7ea57b0dcabb3850d08ee9bc023f7df5dbfa4958afe7ad71d33e37
  Scopes:     session
  Created:    12:58 PM
  Expires In: about 19 hours

3.1.4. Deleting Authorization Tokens

Delete authorization tokens when they are no longer required, or to end access to your account by other users:
Delete Specific Authorization Tokens
Delete one or more tokens with the following command, separating multiple tokens with commas:
$ rhc authorization delete token_1, token_2
Delete All Authorization Tokens
Delete all tokens associated with your account with the following command:
$ rhc authorization delete-all