Configuring Keystone for Federation
###################################

Keystone allows users to be authenticated via identity federation.
This means integrating OpenStack Keystone with an identity provider.
OpenStack supports both OpenID Connect and SAML protocols for federated identity, but for now,
YAOOK supports only OpenID Connect.

For the WebSSO, Horizon needs to assist here because Keystone on its own
is not capable of supporting a browser-based Single Sign-on authentication flow.

For configuration you can also check https://docs.openstack.org/keystone/latest/admin/federation/configure_federation.html.

Configure the KeystoneDeployment for OIDC
=========================================

1. Create OIDC Apache configuration, e.g. ``keystone-api-vhost.conf``:

   .. code-block:: apache

       # OIDC
       LoadModule auth_openidc_module modules/mod_auth_openidc.so
       # Require valid-user
       LoadModule authz_user_module modules/mod_authz_user.so
       # AuthType
       LoadModule authn_core_module modules/mod_authn_core.so

       OIDCXForwardedHeaders "X-Forwarded-Proto"
       OIDCClaimPrefix "OIDC-"
       OIDCClaimDelimiter ";"
       OIDCResponseType "code"
       OIDCScope "openid email profile"

       OIDCCryptoPassphrase <password>
       OIDCProviderMetadataURL <issuer>/.well-known/openid-configuration
       OIDCOAuthVerifyJwksUri <issuer>/protocol/openid-connect/certs
       OIDCClientID <client_id>
       OIDCClientSecret <client_secret>
       OIDCRedirectURI /redirect_uri

       <Location /redirect_uri>
         Require valid-user
         AuthType openid-connect
       </Location>
       <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/openid/auth>
         Require valid-user
         AuthType auth-openidc
       </LocationMatch>
       <Location /v3/auth/OS-FEDERATION/websso/openid>
         Require valid-user
         AuthType openid-connect
       </Location>
       <LocationMatch /v3/auth/OS-FEDERATION/identity_providers/.*?/protocols/openid/websso>
         Require valid-user
         AuthType openid-connect
       </LocationMatch>

   .. note::

       `OIDCMemCacheServers` are automatically configured to the memcached servers used by Keystone itself.
       If you do not want that, add ``UnDefine ENABLE_OIDC_MEMCACHE`` to your Apache configuration.

2. Create Kubernetes Secret:

   .. code-block::

       kubectl -n yaook create secret generic keystone-vhost-conf --from-file keystone-api-vhost.conf

3. Configure KeystoneDeployment:

   .. code-block:: yaml

       apiVersion: yaook.cloud/v1
       kind: KeystoneDeployment
       metadata:
         name: keystone
         namespace: yaook
       spec:
         extraProjected:
           sources:
           - secret:
               name: keystone-vhost-conf # /mnt/projected/keystone-api-vhost.conf
         keystoneConfig:
           auth:
             methods: ["password", "token", "openid", "application_credential"]
           openid:
             # OIDCClaimPrefix "OIDC-"
             remote_id_attribute: HTTP_OIDC_ISS
           federation:
             trusted_dashboard:
             - https://horizon.yaook.cloud/auth/websso/

   .. note::

       The Keystone container includes everything from ``/mnt/projected/*keystone-api-vhost.conf`` files into the
       keystone-api `VirtualHost` section, so Apache configuration should be projected on ``*keystone-api-vhost.conf``.

Configure the HorizonDeployment for WebSSO
==========================================

1. Create additional Horizon settings, e.g. ``_10_websso.py``:

   .. code-block:: python

       from django.utils.translation import gettext_lazy as _

       WEBSSO_ENABLED = True
       WEBSSO_CHOICES = (
           ("credentials", _("Keystone Credentials")),
           ("keycloak_openid", "Keycloak - OpenID Connect"),
       )
       # Identity provider "keycloak" and Federation protocol "openid"
       WEBSSO_IDP_MAPPING = {
           "keycloak_openid": ("keycloak", "openid"),
       }
       WEBSSO_KEYSTONE_URL = "https://keystone.yaook.cloud:443/v3"

       # Use internal endpoint for the Horizon --> Keystone login
       WEBSSO_USE_HTTP_REFERER = False

2. Create Kubernetes ConfigMap:

   .. code-block::

       kubectl -n yaook create configmap horizon-websso --from-file _10_websso.py

3. Configure HorizonDeployment:

   .. code-block:: yaml

       apiVersion: yaook.cloud/v1
       kind: HorizonDeployment
       metadata:
         name: horizon
         namespace: yaook
       spec:
         extraSettings:
           sources:
           - configMap:
               name: horizon-websso # /horizon/openstack_dashboard/local/local_settings.d/_10_websso.py

   .. note::

       `.py` files must start with an underscore and are evaluated alphabetically.