From d688cb58a3a21ce5fbb5edf4e4feaae9998cb21c Mon Sep 17 00:00:00 2001 From: pedro Date: Mon, 4 Nov 2019 19:14:23 -0300 Subject: [PATCH] Add documentation about login with federation The documentation presents the parameters necessary to authenticate via federation (using password) and do a brief description of each parameter used in the process. Change-Id: Iae3b6d0b56ebd2bbbb94f9f3637b5086e75559a7 --- README.rst | 70 ++++++++++++++----- doc/source/cli/authentication.rst | 14 ++++ doc/source/cli/man/openstack.rst | 112 ++++++++++++++++++++++++++++++ 3 files changed, 180 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 41d011242..7dfabd845 100644 --- a/README.rst +++ b/README.rst @@ -76,25 +76,63 @@ Configuration The CLI is configured via environment variables and command-line options as listed in https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html. -Authentication using username/password is most commonly used:: +Authentication using username/password is most commonly used: - export OS_AUTH_URL= - export OS_IDENTITY_API_VERSION=3 - export OS_PROJECT_NAME= - export OS_PROJECT_DOMAIN_NAME= - export OS_USERNAME= - export OS_USER_DOMAIN_NAME= - export OS_PASSWORD= # (optional) +- For a local user, your configuration will look like the one below:: -The corresponding command-line options look very similar:: + export OS_AUTH_URL= + export OS_IDENTITY_API_VERSION=3 + export OS_PROJECT_NAME= + export OS_PROJECT_DOMAIN_NAME= + export OS_USERNAME= + export OS_USER_DOMAIN_NAME= + export OS_PASSWORD= # (optional) - --os-auth-url - --os-identity-api-version 3 - --os-project-name - --os-project-domain-name - --os-username - --os-user-domain-name - [--os-password ] + The corresponding command-line options look very similar:: + + --os-auth-url + --os-identity-api-version 3 + --os-project-name + --os-project-domain-name + --os-username + --os-user-domain-name + [--os-password ] + +- For a federated user, your configuration will look the so:: + + export OS_PROJECT_NAME= + export OS_PROJECT_DOMAIN_NAME= + export OS_AUTH_URL= + export OS_IDENTITY_API_VERSION=3 + export OS_AUTH_PLUGIN=openid + export OS_AUTH_TYPE=v3oidcpassword + export OS_USERNAME= + export OS_PASSWORD= + export OS_IDENTITY_PROVIDER= + export OS_CLIENT_ID= + export OS_CLIENT_SECRET= + export OS_OPENID_SCOPE= + export OS_PROTOCOL= + export OS_ACCESS_TOKEN_TYPE= + export OS_DISCOVERY_ENDPOINT= + + The corresponding command-line options look very similar:: + + --os-project-name + --os-project-domain-name + --os-auth-url + --os-identity-api-version 3 + --os-auth-plugin openid + --os-auth-type v3oidcpassword + --os-username + --os-password + --os-identity-provider + --os-client-id + --os-client-secret + --os-openid-scope + --os-protocol + --os-access-token-type + --os-discovery-endpoint If a password is not provided above (in plaintext), you will be interactively prompted to provide one securely. diff --git a/doc/source/cli/authentication.rst b/doc/source/cli/authentication.rst index 3b404bce5..2e9148c35 100644 --- a/doc/source/cli/authentication.rst +++ b/doc/source/cli/authentication.rst @@ -133,3 +133,17 @@ Thus, a minimal set of environment variables would be: $ export OS_USERNAME=admin $ export OS_PASSWORD=secret $ export OS_PROJECT_NAME=admin + +Federated users support +----------------------- + +The OpenStackClient also allows the use of Federated users to log in. +It enables one to use the identity providers credentials such as Google or +Facebook to log in the OpenStackClient instead of using the Keystone +credentials. + +This is useful in a Federated environment where one credential give access +to many applications/services that the Federation supports. To check how to +configure the OpenStackClient to allow Federated users to log in, please check +the +:ref:`Authentication using federation. ` diff --git a/doc/source/cli/man/openstack.rst b/doc/source/cli/man/openstack.rst index 687e39eb9..dc327a66e 100644 --- a/doc/source/cli/man/openstack.rst +++ b/doc/source/cli/man/openstack.rst @@ -44,6 +44,7 @@ command line. The primary difference is the use of 'project' in the name of the * ``token``: Authentication with a token * ``password``: Authentication with a username and a password +* ``openid`` : Authentication using the protocol OpenID Connect Refer to the keystoneclient library documentation for more details about these plugins and their options, and for a complete list of available plugins. Please bear in mind that some plugins might not support all of the functionalities of :program:`openstack`; for example the v3unscopedsaml plugin can deliver only unscoped tokens, some commands might not be available through this authentication method. @@ -53,6 +54,31 @@ Additionally, it is possible to use Keystone's service token to authenticate, by .. NOTE:: To use the ``v3unscopedsaml`` method, the lxml package will need to be installed. +AUTHENTICATION USING FEDERATION +------------------------------- + +To use federated authentication, your configuration file needs the following: + +:: + + export OS_PROJECT_NAME= + export OS_PROJECT_DOMAIN_NAME= + export OS_AUTH_URL= + export OS_IDENTITY_API_VERSION=3 + export OS_AUTH_PLUGIN=openid + export OS_AUTH_TYPE=v3oidcpassword + export OS_USERNAME= + export OS_PASSWORD= + export OS_IDENTITY_PROVIDER= + export OS_CLIENT_ID= + export OS_CLIENT_SECRET= + export OS_OPENID_SCOPE= + export OS_PROTOCOL= + export OS_ACCESS_TOKEN_TYPE= + export OS_DISCOVERY_ENDPOINT= + export OS_ACCESS_TOKEN_ENDPOINT= + + OPTIONS ======= @@ -356,6 +382,24 @@ Show the detailed information for server ``appweb01``:: --os-auth-url http://localhost:5000:/v2.0 \ server show appweb01 +The same but using openid to authenticate in keystone:: + + openstack \ + --os-project-name ExampleCo \ + --os-auth-url http://localhost:5000:/v2.0 \ + --os-auth-plugin openid \ + --os-auth-type v3oidcpassword \ + --os-username demo-idp \ + --os-password secret-idp \ + --os-identity-provider google \ + --os-client-id the-id-assigned-to-keystone-in-google \ + --os-client-secret 3315162f-2b28-4809-9369-cb54730ac837 \ + --os-openid-scope 'openid email profile'\ + --os-protocol openid \ + --os-access-token-type access_token \ + --os-discovery-endpoint https://accounts.google.com/.well-known/openid-configuration \ + server show appweb01 + The same command if the auth environment variables (:envvar:`OS_AUTH_URL`, :envvar:`OS_PROJECT_NAME`, :envvar:`OS_USERNAME`, :envvar:`OS_PASSWORD`) are set:: @@ -404,6 +448,24 @@ The following environment variables can be set to alter the behaviour of :progra Authentication URL +.. envvar:: OS_AUTH_TYPE + + Define the authentication plugin that will be used to handle the + authentication process. One of the following: + + - ``v2password`` + - ``v2token`` + - ``v3password`` + - ``v3token`` + - ``v3oidcclientcredentials`` + - ``v3oidcpassword`` + - ``v3oidcauthorizationcode`` + - ``v3oidcaccesstoken`` + - ``v3totp`` + - ``v3tokenlessauth`` + - ``v3applicationcredential`` + - ``v3multifactor`` + .. envvar:: OS_URL Service URL (when using the service token) @@ -473,6 +535,56 @@ The following environment variables can be set to alter the behaviour of :progra Interface type. Valid options are `public`, `admin` and `internal`. +.. envvar:: OS_PROTOCOL + + Define the protocol that is used to execute the federated authentication + process. It is used in the Keystone authentication URL generation process. + +.. envvar:: OS_IDENTITY_PROVIDER + + Define the identity provider of your federation that will be used. It is + used by the Keystone authentication URL generation process. The available + Identity Providers can be listed using the + :program:`openstack identity provider list` command + +.. envvar:: OS_CLIENT_ID + + Configure the ``CLIENT_ID`` that the CLI will use to authenticate the + application (OpenStack) in the Identity Provider. This value is defined on + the identity provider side. Do not confuse with the user ID. + +.. envvar:: OS_CLIENT_SECRET + + Configure the OS_CLIENT_SECRET that the CLI will use to authenticate the + CLI (OpenStack secret in the identity provider). + +.. envvar:: OS_OPENID_SCOPE + + Configure the attribute scopes that will be claimed by the Service Provider + (SP), in this case OpenStack, from the identity provider. These scopes and + which attributes each scope contains are defined in the identity provider + side. This parameter can receive multiple values separated by space. + +.. envvar:: OS_ACCESS_TOKEN_TYPE + + Define the type of access token that is used in the token introspection + process. + This variable can assume only one of the states ("access_token" or + "id_token"). + +.. envvar:: OS_DISCOVERY_ENDPOINT + + Configure the identity provider's discovery URL. This URL will provide a + discover document that contains metadata describing the identity provider + endpoints. This variable is optional if the variable + ``OS_ACCESS_TOKEN_ENDPOINT`` is defined. + +.. envvar:: OS_ACCESS_TOKEN_ENDPOINT + + Overrides the value presented in the discovery document retrieved from + ``OS_DISCOVERY_ENDPOINT`` URL request. This variable is optional if the + ``OS_DISCOVERY_ENDPOINT`` is configured. + .. NOTE:: If you switch to openstackclient from project specified clients, like: novaclient, neutronclient and so on, please use `OS_INTERFACE` instead of