.. meta::
  :description: Deploy Keycloak on an Open Telekom Cloud CCE Cluster
  :keywords: keycloak, open telekom cloud, cce, identity federation, cce, kubernetes, github

===========================================
Identity Federation through Keycloak/GitHub
===========================================

.. Overview

Overview
========

Identity Federation in Keycloak refers to the ability to use external identity providers to authenticate users in your
application. In this context, GitHub can be used as an identity provider, allowing users to log in to your
Open Telekom Cloud tenant using their GitHub credentials. Users can choose to log in with their GitHub accounts and
Keycloak takes care of the authentication process, providing a seamless experience for users while ensuring security
and centralized identity management for external accounts that are not actively managed in your tenant's IAM.

.. Main Article

.. Components

Prerequisites
+++++++++++++

For this lab, you are going to need a:

#. **Keycloak** server: You should have a Keycloak server instance set up and running
#. **GitHub** account: You need a GitHub account to register your application and obtain client ID and secret

.. Sections 1..n


Deploy Keycloak
===============

You can follow this blueprint to setup a working instance of Keycloak on CCE:
:ref: `deploy_keycloak`.

Create a new Realm
==================

A realm manages users, credentials, roles, and groups. A user belongs to and logs into the realm he is assigned to.
Realms are isolated from one another and can  manage and authenticate only those users that they belong to them.

Open and login to your Keycloak instance. Create a new realm (let's call it ``otcac_test_company_1`` for the course of
this blueprint) and mark it as enabled:

.. image:: /_static/images/SCR-20231212-mfl.png

|

Create a new Client
===================

Clients are applications, or services, that can request the authentication of a user. Create a new client (let's call it
``otcac_test_company_1_client`` with type ``OpenID Connect`` and in the *Capability config* step of the wizard, activate the following Authentication
flows:

- Standard flow
- Implicit flow
- Direct access grants

.. image:: /_static/images/SCR-20231212-mmx.png

|

Configure Mappers
=================

Open the management console of the Client you just created, and navigate to the *Client scopes* tab. Click on the list
item with the name: ``otcac_test_company_1_client-dedicated``:

.. image:: /_static/images/SCR-20231212-mr5.png

|

Now we need to add some mappers. We will first add one of the predefined ones:

.. image:: /_static/images/SCR-20231212-n1w.png

|

and from the list choose ``email``:

.. image:: /_static/images/SCR-20231212-n0d.png

|

Next we need to add a group membership mapper. Click *Add mapper/By Configuration*:

.. image:: /_static/images/SCR-20231212-n0n.png

and from the list choose ``Group Membership``:

.. image:: /_static/images/SCR-20231212-n15.png

|

Open the configuration of the mapper. Insert a mapper and token name as ``gruppen``. The token name will be used in the
OTC Conversion Rules. Disable the `Full group path` option:

.. image:: /_static/images/SCR-20231212-n8b.png

|

Get OpenID Endpoint Configuration
=================================

Open `Realm Settings` and click on `OpenID Endpoint Configuration`:

.. image:: /_static/images/SCR-20231212-nj4.png

|

You will be redirected to web page rendering, as JSON, all the endpoints and the current configuration of your realm:

.. image:: /_static/images/SCR-20231212-ngd.png

|

.. note:: It is recommended to keep this web page open in a separate tab or screen, because we are going to need to
          grab some values from it, for our the next steps.


Create a new OTC Identity Provider
==================================

For this step we will change to Open Telekom Cloud Console and particularly to IAM and Identity Providers. Create a new
one, and set `Protocol` to ``OpenID Connect``, `SSO Type` to ``Virtual User`` and `Status` to ``Enabled``:

.. image:: /_static/images/SCR-20231212-nq7.png

|

Configure the OTC Identity Provider
===================================

Find your newly created provider in Identity Providers list and click `Modify`:

.. image:: /_static/images/SCR-20231212-nw9.png

|

Set the following values:

- `Access Type`: ``Programmatic access and management console access``
- `Client ID`: The id of your client as defined in Keycloak (in this example is ``otcac_test_company_1_client``)
- `Authorization Endpoint`: copy the value from key **authorization_endpoint** of the `OpenID Endpoint Configuration` JSON output
- `Response Mode`: ``form_post``
- `Signing Key`: open in a new tab the URL address that is value of the key **jwks_uri** of the `OpenID Endpoint Configuration` JSON output. Copy the whole output of the new page and paste it as is in the respective textbox for `Signing Key`.


.. image:: /_static/images/SCR-20231212-o7i.png

|

Save the changes, **but before closing this panel copy the value** of the `Identity Provider URL` because we are going to
need this value in the next step of this blueprint.

Configure Client's Access Settings
==================================

For this step we will switch back to Keycloak Administration Console, and navigate to `Access Settings` for our client:

.. image:: /_static/images/SCR-20231212-och.png

|

Set the following values:

- `Root URL`: The `Identity Provider URL` you copied in the previous step.
- `Home URL`: ``https://auth.otc.t-systems.com``
- `Valid redirect URIs`: ``https://auth.otc.t-systems.com/authui/oidc/post``

Create new GitHub OAuth App
===========================

Add GitHub as Identity Provider to Keycloak
===========================================

.. Next steps & Related Resources

Next Steps
==========

| > *(Expected, but it could be optional if you don't want the article stops here and doesn't connect with other resources)*
| > *Add site-relative links to Architecture Center related articles but NOT to external or third-party resources*
| > *If there are additional resources like Cloud Topology Designer solution or Github repos, list them first with the aforementioned order*

.. seealso::

   `Link1 <https://www.t-systems.com>`_

   `Link2 <https://www.t-systems.com>`_

Resources
=========

.. Resources

| > *If there are additional deployable resources like Cloud Topology Designer solution or Github repos, list them first with the aformentioned order*

.. seealso::

   `Link1 <https://www.t-systems.com>`_

   `Link2 <https://www.t-systems.com>`_


.. References

References
==========

| > *Add site-relative links to Architecture Center articles*
| > *Add links to external or third-party resources*

.. seealso::

   `Link1 <https://www.t-systems.com>`_

   `Link2 <https://www.t-systems.com>`_

| > **REMOVE ALL THE LINES THAT START WITH "| >"**