UnifiedCLI/Authentication
Note: this page is being deprecated in favor of a new OpenStackClient Authentication page with the correct name.
Contents
OSCLI Authentication
Part of the UnifiedCLI proposal
Note: the versioning of the CLIs shipped with the OpenStack client libraries does not follow that of OpenSTack itself. The distinctions made here regarding release timeframes are for rough comparison purposes.
Essex
Essex mostly conforms to the original CLIAuth document.
Environment vs Option
All of the authentication information can be specified either on the command line with global options or in the environment. Command-line options have the usual option prefix of '--
' and all lower case letters in the option name. They have either '-
' (dash) or '_
' (underscore) characters separating the elements of the name. The corresponding environment variables have the same name but use all upper-case characters and only a '_
' (underscore) to separate the elements.
For example: The URL of the Identity endpoint can be specified with the --os_auth_url option or OS_AUTH_URL environment variable.
Password Flow
Password flow is commonly used for one-off, interactive and initial connections. It requires a tenant (name or ID), username, password and Identity endpoint be .
# Pick one of the following OS_TENANT_ID=<tenant-id> # --os_tenant_id OS_TENANT_NAME=<tenant-name> # --os_tenant_name OS_USERNAME=<username> # --os_username OS_PASSWORD=<password> # --os_password OS_AUTH_URL=<identity-api-endpoint> # --os_auth_url
Notes
- IDs vs NAMEs in Keystone: While both ids and names are meant to be unique, IDs are immutable whereas the name can change
Token Flow
The password flow authentication requires a trip through the Identity API on each invocation of a CLI command. When performing multiple commands together (or in a script) it is more efficient to cache the authentication token and pass it to the CLI command.
The token flow requires a token from the Identity system (OS_TOKEN) and the endpoint to use for the desired service API (OS_URL).
Additional Variables
Some clients have additional variables to control authentication behaviour. Where they exist these should follow the same convention.
OS_REGION_NAME=<region> OS_AUTH_STRATEGY=noauth|keystone # Glance
Folsom
In the Folsom timeframe all existing and new CLIs shall be brought into compliance.
Environment vs Option
All of the authentication information can be specified either on the command line with global options or in the environment. Command-line options have the usual option prefix of '--
' and all lower case letters in the option name. They have only '-
' (dash) characters separating the elements of the name. The corresponding environment variables have the same name but use all upper-case characters and only a '_
' (underscore) to separate the elements.
For example: The URL of the Identity endpoint can be specified with the --os-auth-url option or OS_AUTH_URL environment variable.
Note: The continued use of '_
' (underscore) in CLIs where present in Essex will continue for backward-compatibility, and shall be deprecated in this release, removed in a future release and not appear in help output.
Password Flow
Password flow is commonly used for one-off, interactive and initial connections. It requires a tenant (name or ID), username, password and Identity endpoint be .
# Pick one of the following OS_TENANT_ID=<tenant-id> # --os-tenant-id OS_TENANT_NAME=<tenant-name> # --os-tenant-name OS_USERNAME=<username> # --os-username OS_PASSWORD=<password> # --os-password OS_AUTH_URL=<identity-api-endpoint> # --os-auth-url
Notes
- IDs vs NAMEs in Keystone: While both IDs and names are meant to be unique, IDs are immutable whereas the name can change
Token Flow
The password flow authentication requires a trip through the Identity API on each invocation of a CLI command. When performing multiple commands together (or in a script) it is more efficient to cache the authentication token and pass it to the CLI command.
OS_TOKEN=<token> # --os-token
Overriding the service endpoint
The service endpoint that you'll be communicating with is provided by Keystone's service catalog. If you are providing the token explicitly, then you also need to provide the endpoint with which you are interacting. The use of token flow specifically bypasses the Service Catalog so OS_ENDPOINT needs to point to the ultimate API endpoint.
This can also be used to explicitly set the endpoint, regardless of what the service catalog has provided, if used with password authentication.
OS_ENDPOINT=<api-endpoint> # --os-endpoint