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

3 files changed, 183 insertions, 19 deletions

diff --git a/README.rst b/README.rst
index 41d01124..7dfabd84 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::
-
-   export OS_AUTH_URL=<url-to-openstack-identity>
-   export OS_IDENTITY_API_VERSION=3
-   export OS_PROJECT_NAME=<project-name>
-   export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
-   export OS_USERNAME=<username>
-   export OS_USER_DOMAIN_NAME=<user-domain-name>
-   export OS_PASSWORD=<password>  # (optional)
-
-The corresponding command-line options look very similar::
-
-   --os-auth-url <url>
-   --os-identity-api-version 3
-   --os-project-name <project-name>
-   --os-project-domain-name <project-domain-name>
-   --os-username <username>
-   --os-user-domain-name <user-domain-name>
-   [--os-password <password>]
+Authentication using username/password is most commonly used:
+
+- For a local user, your configuration will look like the one below::
+
+    export OS_AUTH_URL=<url-to-openstack-identity>
+    export OS_IDENTITY_API_VERSION=3
+    export OS_PROJECT_NAME=<project-name>
+    export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
+    export OS_USERNAME=<username>
+    export OS_USER_DOMAIN_NAME=<user-domain-name>
+    export OS_PASSWORD=<password>  # (optional)
+
+  The corresponding command-line options look very similar::
+
+    --os-auth-url <url>
+    --os-identity-api-version 3
+    --os-project-name <project-name>
+    --os-project-domain-name <project-domain-name>
+    --os-username <username>
+    --os-user-domain-name <user-domain-name>
+    [--os-password <password>]
+
+- For a federated user, your configuration will look the so::
+
+    export OS_PROJECT_NAME=<project-name>
+    export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
+    export OS_AUTH_URL=<url-to-openstack-identity>
+    export OS_IDENTITY_API_VERSION=3
+    export OS_AUTH_PLUGIN=openid
+    export OS_AUTH_TYPE=v3oidcpassword
+    export OS_USERNAME=<username-in-idp>
+    export OS_PASSWORD=<password-in-idp>
+    export OS_IDENTITY_PROVIDER=<the-desired-idp-in-keystone>
+    export OS_CLIENT_ID=<the-client-id-configured-in-the-idp>
+    export OS_CLIENT_SECRET=<the-client-secred-configured-in-the-idp>
+    export OS_OPENID_SCOPE=<the-scopes-of-desired-attributes-to-claim-from-idp>
+    export OS_PROTOCOL=<the-protocol-used-in-the-apache2-oidc-proxy>
+    export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>
+    export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>
+
+  The corresponding command-line options look very similar::
+
+    --os-project-name <project-name>
+    --os-project-domain-name <project-domain-name>
+    --os-auth-url <url-to-openstack-identity>
+    --os-identity-api-version 3
+    --os-auth-plugin openid
+    --os-auth-type v3oidcpassword
+    --os-username <username-in-idp>
+    --os-password <password-in-idp>
+    --os-identity-provider <the-desired-idp-in-keystone>
+    --os-client-id <the-client-id-configured-in-the-idp>
+    --os-client-secret <the-client-secred-configured-in-the-idp>
+    --os-openid-scope <the-scopes-of-desired-attributes-to-claim-from-idp>
+    --os-protocol <the-protocol-used-in-the-apache2-oidc-proxy>
+    --os-access-token-type <the-access-token-type-used-by-your-idp>
+    --os-discovery-endpoint <the-well-known-endpoint-of-the-idp>
 
 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 3b404bce..2e9148c3 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. <manpage>`
diff --git a/doc/source/cli/man/openstack.rst b/doc/source/cli/man/openstack.rst
index 687e39eb..dc327a66 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=<project-name>
+    export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
+    export OS_AUTH_URL=<url-to-openstack-identity>
+    export OS_IDENTITY_API_VERSION=3
+    export OS_AUTH_PLUGIN=openid
+    export OS_AUTH_TYPE=v3oidcpassword
+    export OS_USERNAME=<username-in-idp>
+    export OS_PASSWORD=<password-in-idp>
+    export OS_IDENTITY_PROVIDER=<the-desired-idp>
+    export OS_CLIENT_ID=<the-client-id-configured-in-the-idp>
+    export OS_CLIENT_SECRET=<the-client-secred-configured-in-the-idp>
+    export OS_OPENID_SCOPE=<the-scopes-of-desired-attributes-to-claim-from-idp>
+    export OS_PROTOCOL=<the-protocol-used-in-the-apache2-oidc-proxy>
+    export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>
+    export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>
+    export OS_ACCESS_TOKEN_ENDPOINT=<the-idp-access-token-url>
+
+
 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