Merge "Add support to OpenID Connect Authentication flow"

3 files changed, 432 insertions, 0 deletions

diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 9681dc966..fb61fccfd 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -21,3 +21,4 @@ We welcome everyone to join our project!
    bug-triage
    ptl-guide
    release-management
+   setup-identity-provider
diff --git a/doc/source/contributor/setup-identity-provider.rst b/doc/source/contributor/setup-identity-provider.rst
new file mode 100644
index 000000000..99e5ae780
--- /dev/null
+++ b/doc/source/contributor/setup-identity-provider.rst
@@ -0,0 +1,193 @@
+.. _setup-identity-provider:
+
+============================
+Test Identity Provider setup
+============================
+
+This guide shows how to create an Identity Provider that handles the OpenID
+Connect protocol to authenticate users when
+:keystone-doc:`using Federation with OpenStack
+</admin/federation/configure_federation.html>` (these configurations must not
+be used in a production environment).
+
+Keycloak
+========
+
+Keycloak is a Java application that implements an Identity Provider handling
+both OpenID Connect and SAML protocols.
+
+To setup a Keycloak instance for testing is pretty simple with Docker.
+
+Creating the Docker Keycloak instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run the docker command:
+
+.. code-block:: console
+
+    docker run -p 8080:8080 -p 8443:8443 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:latest
+
+This will create a Keycloak instance that has the admin credentials as
+admin/admin and is listening on port 8080.
+
+After creating the instance, you will need to log in to the Keycloak as
+administrator and setup the first Identity Provider.
+
+Creating an Identity Provider with Keycloak
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following guide assumes that the steps are executed from the same machine
+(localhost), but you can change the hostname if you want to run it from
+elsewhere.
+
+In this guide, we will use the 'new_realm' as the realm name in Keycloak, so,
+if you want to use any other realm name, you must to change 'new_realm' in the
+URIs used in the guide and replace the 'new_realm' with the realm name that you
+are using.
+
+- Access the admin console on http://localhost:8080/auth/ in the Administration Console option.
+- Authenticate using the credentials defined in the creation step.
+- Create a new realm in the http://localhost:8080/auth/admin/master/console/#/create/realm page.
+- After creating a realm, you will need to create a client to be used by Keystone; to do it, just access http://localhost:8080/auth/admin/master/console/#/create/client/new_realm.
+- To create a client, you will need to set the client_id (just choose anyone),
+  the protocol (must be openid-connect) and the Root Url (you can leave it
+  blank)
+- After creating the client, you will need to update some client's attributes
+  like:
+
+  - Enable the Implicit flow (this one allows you to use the OpenStack CLI with
+    oidcv3 plugin)
+  - Set Access Type to confidential
+  - Add the Horizon and Keystone URIs to the Valid Redirect URIs. Keystone should be within the '/redirect_uri' path, for example: https://horizon.com/ and https://keystone.com/redirect_uri
+  - Save the changes
+  - Access the client's Mappers tab to add the user's attributes that will be
+    shared with the client (Keystone):
+
+    - In this guide, we will need the following attribute mappers in Keycloak:
+
+      ==================================== ==============
+      name/user attribute/token claim name mapper type
+      ==================================== ==============
+      openstack-user-domain                user attribute
+      openstack-default-project            user attribute
+      ==================================== ==============
+
+- After creating the client, you will need to create a user in that realm to
+  log in OpenStack via identity federation
+- To create a user, access http://localhost:8080/auth/admin/master/console/#/create/user/new_realm and fill the form with the user's data
+- After creating the user, you can access the tab "Credentials" to set the
+  user's password
+- Then, in the tab "Attributes", you must set the authorization attributes to
+  be used by Keystone, these attributes are defined in the :ref:`attribute
+  mapping <attribute_mapping>` in Keystone
+
+After you create the Identity provider, you will need to get some data from the
+Identity Provider to configure in Kolla-Ansible
+
+Configuring Kolla Ansible to use the Identity Provider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section is about how one can get the data needed in
+:ref:`Setup OIDC via Kolla Ansible <setup-oidc-kolla-ansible>`.
+
+- name: The realm name, in this case it will be "new_realm"
+- identifier: http://localhost:8080/auth/realms/new_realm/ (again, the "new_realm" is the name of the realm)
+- certificate_file: This one can be downloaded from http://localhost:8080/auth/admin/master/console/#/realms/new_realm/keys
+- metadata_folder:
+
+  - localhost%3A8080%2Fauth%2Frealms%2Fnew_realm.client:
+
+    - client_id: Access http://localhost:8080/auth/admin/master/console/#/realms/new_realm/clients , and access the client you created for Keystone, copy the Client ID displayed in the page
+    - client_secret: In the same page you got the client_id, access the tab
+      "Credentials" and copy the secret value
+  - localhost%3A8080%2Fauth%2Frealms%2Fnew_realm.provider: Copy the json from http://localhost:8080/auth/realms/new_realm/.well-known/openid-configuration (the "new_realm" is the realm name)
+  - localhost%3A8080%2Fauth%2Frealms%2Fnew_realm.conf: You can leave this file
+    as an empty json "{}"
+
+
+After you finished the configuration of the Identity Provider, your main
+configuration should look something like the following:
+
+.. code-block::
+
+    keystone_identity_providers:
+      - name: "new_realm"
+        openstack_domain: "new_domain"
+        protocol: "openid"
+        identifier: "http://localhost:8080/auth/realms/new_realm"
+        public_name: "Authenticate via new_realm"
+        attribute_mapping: "attribute_mapping_keycloak_new_realm"
+        metadata_folder: "/root/inDev/meta-idp"
+        certificate_file: "/root/inDev/certs/LRVweuT51StjMdsna59jKfB3xw0r8Iz1d1J1HeAbmlw.pem"
+    keystone_identity_mappings:
+      - name: "attribute_mapping_keycloak_new_realm"
+        file: "/root/inDev/attr_map/attribute_mapping.json"
+
+Then, after deploying OpenStack, you should be able to log in Horizon
+using the "Authenticate using" -> "Authenticate via new_realm", and writing
+"new_realm.com" in the "E-mail or domain name" field. After that, you will be
+redirected to a new page to choose the Identity Provider in Keystone. Just click in the link
+"localhost:8080/auth/realms/new_realm"; this will redirect you to Keycloak (idP) where
+you will need to log in with the user that you created. If the user's
+attributes in Keycloak are ok, the user will be created in OpenStack and you will
+be able to log in Horizon.
+
+.. _attribute_mapping:
+
+Attribute mapping
+~~~~~~~~~~~~~~~~~
+This section shows how to create the attribute mapping to map an Identity
+Provider user to a Keystone user (ephemeral).
+
+The 'OIDC-' prefix in the remote types is defined in the 'OIDCClaimPrefix'
+configuration in the wsgi-keystone.conf file; this prefix must be in the
+attribute mapping as the mod-oidc-wsgi is adding the prefix in the user's
+attributes before sending it to Keystone. The attribute 'openstack-user-domain'
+will define the user's domain in OpenStack and the attribute
+'openstack-default-project' will define the user's project in the OpenStack
+(the user will be assigned with the role 'member' in the project)
+
+.. code-block:: json
+
+    [
+        {
+            "local": [
+                {
+                    "user": {
+                        "name": "{0}",
+                        "email": "{1}",
+                        "domain": {
+                            "name": "{2}"
+                        }
+                    },
+                    "domain": {
+                            "name": "{2}"
+                        },
+                    "projects": [
+                        {
+                            "name": "{3}",
+                            "roles": [
+                                {
+                                    "name": "member"
+                                }
+                            ]
+                        }
+                    ]
+                }
+            ],
+            "remote": [
+                {
+                    "type": "OIDC-preferred_username"
+                },
+                {
+                    "type": "OIDC-email"
+                },
+                {
+                    "type": "OIDC-openstack-user-domain"
+                },
+                {
+                    "type": "OIDC-openstack-default-project"
+                }
+            ]
+        }
+    ]
diff --git a/doc/source/reference/shared-services/keystone-guide.rst b/doc/source/reference/shared-services/keystone-guide.rst
index 2012b868f..126e53c3d 100644
--- a/doc/source/reference/shared-services/keystone-guide.rst
+++ b/doc/source/reference/shared-services/keystone-guide.rst
@@ -40,3 +40,241 @@ be configured in Keystone as necessary.
 
 Further infomation on Fernet tokens is available in the :keystone-doc:`Keystone
 documentation <admin/fernet-token-faq.html>`.
+
+Federated identity
+------------------
+
+Keystone allows users to be authenticated via identity federation. This means
+integrating OpenStack Keystone with an identity provider. The use of identity
+federation allows users to access OpenStack services without the necessity of
+an account in the OpenStack environment per se. The authentication is then
+off-loaded to the identity provider of the federation.
+
+To enable identity federation, you will need to execute a set of configurations
+in multiple OpenStack systems. Therefore, it is easier to use Kolla Ansible
+to execute this process for operators.
+
+For upstream documentations, please see
+:keystone-doc:`Configuring Keystone for Federation
+<admin/federation/configure_federation.html>`
+
+Supported protocols
+~~~~~~~~~~~~~~~~~~~
+
+OpenStack supports both OpenID Connect and SAML protocols for federated
+identity, but for now, kolla Ansible supports only OpenID Connect.
+Therefore, if you desire to use SAML in your environment, you will need
+to set it up manually or extend Kolla Ansible to also support it.
+
+.. _setup-oidc-kolla-ansible:
+
+Setting up OpenID Connect via Kolla Ansible
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First, you will need to register the OpenStack (Keystone) in your Identity
+provider as a Service Provider.
+
+After registering Keystone, you will need to add the Identity Provider
+configurations in your kolla-ansible globals configuration as the example
+below:
+
+.. code-block:: yaml
+
+    keystone_identity_providers:
+      - name: "myidp1"
+        openstack_domain: "my-domain"
+        protocol: "openid"
+        identifier: "https://accounts.google.com"
+        public_name: "Authenticate via myidp1"
+        attribute_mapping: "mappingId1"
+        metadata_folder: "path/to/metadata/folder"
+        certificate_file: "path/to/certificate/file.pem"
+
+    keystone_identity_mappings:
+      - name: "mappingId1"
+        file: "/full/qualified/path/to/mapping/json/file/to/mappingId1"
+
+Identity providers configurations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+name
+****
+
+The internal name of the Identity provider in OpenStack.
+
+openstack_domain
+****************
+
+The OpenStack domain that the Identity Provider belongs.
+
+protocol
+********
+
+The federated protocol used by the IdP; e.g. openid or saml. We support only
+OpenID connect right now.
+
+identifier
+**********
+
+The Identity provider URL; e.g. https://accounts.google.com .
+
+public_name
+***********
+
+The Identity provider public name that will be shown for users in the Horizon
+login page.
+
+attribute_mapping
+*****************
+
+The attribute mapping to be used for the Identity Provider. This mapping is
+expected to already exist in OpenStack or be configured in the
+`keystone_identity_mappings` property.
+
+metadata_folder
+***************
+
+Path to the folder containing all of the identity provider metadata as JSON
+files.
+
+The metadata folder must have all your Identity Providers configurations,
+the name of the files will be the name (with path) of the Issuer configuration.
+Such as:
+
+.. code-block::
+
+    - <IDP metadata directory>
+      - keycloak.example.org%2Fauth%2Frealms%2Fidp.client
+      |
+      - keycloak.example.org%2Fauth%2Frealms%2Fidp.conf
+      |
+      - keycloak.example.org%2Fauth%2Frealms%2Fidp.provider
+
+.. note::
+
+  The name of the file must be URL-encoded if needed. For example, if you have
+  an Issuer with ``/`` in the URL, then you need to escape it to ``%2F`` by
+  applying a URL escape in the file name.
+
+The content of these files must be a JSON
+
+``client``:
+
+The ``.client`` file handles the Service Provider credentials in the Issuer.
+
+During the first step, when you registered the OpenStack as a
+Service Provider in the Identity Provider, you submitted a `cliend_id` and
+generated a `client_secret`, so these are the values you must use in this
+JSON file.
+
+.. code-block:: json
+
+    {
+      "client_id":"<openid_client_id>",
+      "client_secret":"<openid_client_secret>"
+    }
+
+``conf``:
+
+This file will be a JSON that overrides some of the OpenID Connect options. The
+options that can be overridden are listed in the
+`OpenID Connect Apache2 plugin documentation`_.
+.. _`OpenID Connect Apache2 plugin documentation`: https://github.com/zmartzone/mod_auth_openidc/wiki/Multiple-Providers#opclient-configuration
+
+If you do not want to override the config values, you can leave this file as
+an empty JSON file such as ``{}``.
+
+``provider``:
+
+This file will contain all specifications about the IdentityProvider. To
+simplify, you can just use the JSON returned in the ``.well-known``
+Identity provider's endpoint:
+
+.. code-block:: json
+
+  {
+    "issuer": "https://accounts.google.com",
+    "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
+    "token_endpoint": "https://oauth2.googleapis.com/token",
+    "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
+    "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
+    "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
+    "response_types_supported": [
+     "code",
+     "token",
+     "id_token",
+     "code token",
+     "code id_token",
+     "token id_token",
+     "code token id_token",
+     "none"
+    ],
+    "subject_types_supported": [
+     "public"
+    ],
+    "id_token_signing_alg_values_supported": [
+     "RS256"
+    ],
+    "scopes_supported": [
+     "openid",
+     "email",
+     "profile"
+    ],
+    "token_endpoint_auth_methods_supported": [
+     "client_secret_post",
+     "client_secret_basic"
+    ],
+    "claims_supported": [
+     "aud",
+     "email",
+     "email_verified",
+     "exp",
+     "family_name",
+     "given_name",
+     "iat",
+     "iss",
+     "locale",
+     "name",
+     "picture",
+     "sub"
+    ],
+    "code_challenge_methods_supported": [
+     "plain",
+     "S256"
+    ]
+  }
+
+certificate_file
+****************
+
+Path to the Identity Provider certificate file, the file must be named as
+'certificate-key-id.pem'. E.g.
+
+.. code-block::
+
+    - fb8ca5b7d8d9a5c6c6788071e866c6c40f3fc1f9.pem
+
+You can find the key-id in the Identity provider
+`.well-known/openid-configuration` `jwks_uri` like in
+`https://www.googleapis.com/oauth2/v3/certs` :
+
+.. code-block:: json
+
+    {
+      "keys": [
+        {
+          "e": "AQAB",
+          "use": "sig",
+          "n": "zK8PHf_6V3G5rU-viUOL1HvAYn7q--dxMoU...",
+          "kty": "RSA",
+          "kid": "fb8ca5b7d8d9a5c6c6788071e866c6c40f3fc1f9",
+          "alg": "RS256"
+        }
+      ]
+    }
+
+.. note::
+
+    The public key is different from the certificate, the file in this
+    configuration must be the Identity provider's certificate and not the
+    Identity provider's public key.