diff --git a/doc/source/best-practices/security/deploy_keycloak.rst b/doc/source/best-practices/security/deploy_keycloak.rst
index 0d607db..ed45959 100755
--- a/doc/source/best-practices/security/deploy_keycloak.rst
+++ b/doc/source/best-practices/security/deploy_keycloak.rst
@@ -588,5 +588,4 @@ Resources
 .. seealso::
 
    - `GitHub repo <https://www.t-systems.com>`_
-   - `Link2 <https://www.t-systems.com>`_
 
diff --git a/doc/source/best-practices/security/keycloak_github.rst b/doc/source/best-practices/security/keycloak_github.rst
index 55c04db..ea9379e 100755
--- a/doc/source/best-practices/security/keycloak_github.rst
+++ b/doc/source/best-practices/security/keycloak_github.rst
@@ -183,57 +183,109 @@ GitHub Integration
 Add GitHub as Identity Provider
 +++++++++++++++++++++++++++++++
 
+Then we have to add a new Identity Provider that will allow users to authenticate using their GitHub accounts:
+
+.. image:: /_static/images/SCR-20240122-k3x.png
+
+Enable the provider and copy the `Redirect URI` because we are going to need in the next step, that will interconnect
+this Keycloak realm with a GitHub OAuth application.
+
+.. image:: /_static/images/SCR-20240201-k76.png
+
 Create new GitHub OAuth App
 +++++++++++++++++++++++++++
 
+Open your GitHub account and find *OAuth Apps* under *Settings/Developer Settings* and create a new app:
+
+.. image:: /_static/images/SCR-20240122-k0w.png
+
+and set the following values:
+
+- `Homepage URL`: ``https://auth.otc.t-systems.com``
+- `Authorization call back URL`: the **Redirect URI** we picked up from the previous step
+
+.. image:: /_static/images/SCR-20240122-k68.png
+
+|
+
+Last piece of creating an OAuth App is to generate a client secret:
+
+.. image:: /_static/images/SCR-20240122-k76.png
+
+.. note:: Make immediately a copy of the client secret value. We are going to need it (along with the *Client ID* of the app)
+          during our next step and additionally that is the last time that it will be visible on the GitHub console.
+
 Configure GitHub Identity Provider
 ++++++++++++++++++++++++++++++++++
 
+Next, let's return back to the configuration panel of our newly created GitHub Identity Provider in Keycloak, and set
+the following values:
+
+.. image:: /_static/images/SCR-20240122-k1y.png
+
+|
+
+- `Client ID`: the **Client ID** of the GitHub OAUth app we just created
+- `Client Secret`: the **Client Secret** of the GitHub OAUth app
+
 Configure the IAM Identity Provider Conversion Rules
 ====================================================
 
+By default federated users are named *FederationUser* in the Open Telekom Cloud platform. These users can only log in to
+the cloud platform and they do not have **any** other permissions. You can configure identity conversion rules on the
+IAM console to achieve the following:
 
-.. Next steps & Related Resources
+- Display enterprise users with different names in the cloud platform.
+- Assign permissions to enterprise users to use the cloud platform resources by mapping these users to IAM user groups.
+  Ensure that you have created the required user groups.
 
-Next Steps
-==========
+This can be achieved by editing the Identity Conversion Rules under IAM/Identity Providers:
 
-| > *(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*
+.. image:: /_static/images/SCR-20240201-erg.png
 
-.. seealso::
+|
 
-   `Link1 <https://www.t-systems.com>`_
+Paste the following conversion rule in the *Edit Rule* panel:
 
-   `Link2 <https://www.t-systems.com>`_
+.. code-block:: json
+  :linenos:
+
+    [
+      {
+        "remote": [
+        {
+          "type": "email"
+        },
+        {
+          "type": "gruppen"
+        }],
+        "local": [
+        {
+          "user": {
+            "name": "{0}"
+          }
+        },
+        {
+          "groups": "{1}"
+        }]
+      }
+    ]
+
+The *remote* part describes the *Predefined Mappers* (``email`` and ``gruppen``) we created in KeyCloak Client's configuration.
+The *local* part defines the mapping between the remote properties and the OTC account. The user will get as ``name``
+the the value of ``remote.email`` and will automatically belong to the ``groups`` defined in ``remote.gruppen``.
+
+.. warning:: Bear in mind, that we have to create those OTC groups on before hands so they match 1-1 name-wise in order
+             the mapping to work and our federated user to get the desired permissions.
 
 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>`_
+   - `Configure Identity Conversion Rules <https://docs.otc.t-systems.com/identity-access-management/umn/user_guide/identity_providers/virtual_user_sso_via_openid_connect/step_2_configure_identity_conversion_rules.html>`_
+   - `Syntax of Identity Conversion Rules <https://docs.otc.t-systems.com/identity-access-management/umn/user_guide/identity_providers/syntax_of_identity_conversion_rules.html#en-us-topic-0079620340>`_
 
 
-.. 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 "| >"**