Difference between revisions of "UnifiedCLI/Authentication"
Line 3: | Line 3: | ||
''Part of the [[UnifiedCLI]] proposal'' | ''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 == | ||
Line 36: | Line 38: | ||
=== Token Flow === | === Token Flow === | ||
− | The password flow authentication requires a trip through the Identity API on ''each'' invocation of a | + | 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). | The token flow requires a token from the Identity system (OS_TOKEN) and the endpoint to use for the desired service API (OS_URL). | ||
Line 57: | Line 59: | ||
=== Environment vs Option === | === 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 '<code><nowiki>--</nowiki></code>' and all lower case letters in the option name. They have only '<code><nowiki>-</nowiki></code>' (dash) characters separating the elements of the name. The corresponding environment variables | + | 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 '<code><nowiki>--</nowiki></code>' and all lower case letters in the option name. They have only '<code><nowiki>-</nowiki></code>' (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 '<code><nowiki>_</nowiki></code>' (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. | For example: The URL of the Identity endpoint can be specified with the --os-auth-url option or OS_AUTH_URL environment variable. | ||
Line 81: | Line 83: | ||
'''Notes''' | '''Notes''' | ||
− | * IDs vs NAMEs in Keystone: While both | + | * 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 === | === Token Flow === | ||
− | The password flow authentication requires a trip through the Identity API on ''each'' invocation of a | + | 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. |
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | OS_TOKEN=<token> # --os-token | ||
+ | OS_ENDPOINT=<api-endpoint> # --os-endpoint | ||
+ | </nowiki></pre> | ||
+ | |||
− | + | The use of token flow specifically bypasses the Service Catalog so OS_ENDPOINT needs to point to the ultimate API endpoint. |
Revision as of 01:23, 18 September 2012
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 OS_ENDPOINT=<api-endpoint> # --os-endpoint
The use of token flow specifically bypasses the Service Catalog so OS_ENDPOINT needs to point to the ultimate API endpoint.