chore: add step-by-step guide on how to integrate msentra as idp in keycloak

README.md

@@ -20,6 +20,8 @@ This repository contains documentation, guides, and reference material.
   Documentation and guides related to Keycloak configuration and best practices.  
   - [Enforce OTP 2FA for Internal Users](./keycloak/enforce-otp-internal.md)  
     Step-by-step instructions for enforcing OTP-based two-factor authentication for internal users, while excluding external Microsoft Entra users.
+  - [Integrate MS Entra in Keycloak as IDP](./keycloak/idp-ms-entra.md)
+    Step-by-step instructions for integrating MS Entra as identity-provider.
 
 - **[Microsoft Entra](./ms-entra/)**  
   Documentation and guides related to Microsft Entra configuration and best practices.

keycloak/idp-ms-entra.md

@@ -0,0 +1,81 @@
+# Add Microsoft Entra ID as an Identity Provider in Keycloak
+
+> **Goal:** Connect your Microsoft Entra application (from the previous guide) to Keycloak using OpenID Connect so users can sign in with their Microsoft accounts.
+
+---
+
+## Prerequisites
+From the [Entra guide](../ms-entra/enterprise-app-keycloak.md) you should have:
+- **OpenID Connect metadata document URL** 
+- **Application (client) ID**
+- **Client secret (Value)**
+- (Optional) **Tenant ID** — useful to verify you used the correct discovery URL
+
+You'll also need:
+- Access to the **Keycloak Admin Console**
+- The **realm** where you want to add the provider (e.g., `Digitalboard`)
+- The **alias** you decided on (this must match the alias in the Entra Redirect URI)
+
+---
+
+## Step 1 — Open Identity Providers in your realm
+1. In Keycloak, switch to the target realm (e.g., `Digitalboard`).
+2. Navigate to **Configure → Identity providers**.
+3. Click **Add provider** → **OpenID Connect v1.0**.
+
+![Open “Add provider”](images/idp-ms-entra/step-01-A.png "Add provider → OpenID Connect v1.0")  
+*Figure 1: Adding an OIDC provider.*
+![Open “Add provider”](images/idp-ms-entra/step-01-B.png "Add provider → OpenID Connect v1.0")  
+*Figure 1: Adding an OIDC provider.*
+
+---
+
+## Step 2 — Fill the basic settings
+On the **Add identity provider** form:
+
+1. **Alias**: enter your organization alias (must match the alias used in the Entra Redirect URI).  
+   Example: `test-schule`
+2. **Display name**: a friendly label users will see on the login page.  
+   Example: `Test Schule`
+3. **Use discovery endpoint**: **On**.
+4. **Discovery endpoint**: paste the **OpenID Connect metadata document URL** you copied in Entra (Step 7).  
+   Example: `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`
+5. **Client authentication**: keep **Client secret sent as post**.
+6. **Client ID**: paste the **Application (client) ID** from Entra.
+7. **Client Secret**: paste the **client secret Value** from Entra.
+8. **Client assertion signature algorithm**: leave **Algorithm not specified** (default).
+9. Click **Add** (or **Save**).
+
+> As soon as you set the **Alias**, Keycloak shows the **Redirect URI** at the top (read-only). It must exactly match the Redirect URI you registered in Entra.
+
+![Fill OIDC settings](images/idp-ms-entra/step-02-A.png "OIDC identity provider form in Keycloak")  
+*Figure 2: Basic OIDC settings in Keycloak.*
+
+---
+
+## Step 3 — Set recommended options
+After saving, on the provider's **Settings** tab, adjust:
+
+- **Default Scopes**: `openid profile email`  
+  (ensures Entra returns the claims you added in the [Entra guide](../ms-entra/enterprise-app-keycloak.md))
+- **Trust email**: **On** (lets Keycloak trust verified email from Entra)
+- **Sync Mode**: **Import** (default; copies basic attributes into Keycloak)
+- **Disable User Info**: **Off** (keep it off so Keycloak can fetch claims from the UserInfo endpoint)
+- **Backchannel logout**: **On** (optional but recommended)
+
+Click **Save**.
+
+---
+
+## Step 3 — Check the provider appears on the login page
+Back on **Configure → Identity providers**, you should see your new provider listed.
+
+Open your realm's login page (or log out of the Admin Console and choose **Sign in with <Provider-Display-Name>**). You should be redirected to Microsoft, then back to Keycloak, and end up authenticated.
+
+---
+
+## Troubleshooting
+- **`invalid_redirect_uri` (on Microsoft)**: The Redirect URI in Entra must match exactly what Keycloak shows (including realm name and **alias**).
+- **`AADSTS50105`**: Access to the Enterprise App is restricted. Follow Steps 10-11 in the [Entra guide](../ms-entra/enterprise-app-keycloak.md) to assign the user/group.
+- **No name/email in Keycloak user**: Check **Default Scopes** include `profile email`, verify Entra **Token configuration** (claims) and Keycloak **Mappers**.
+- **Issuer/metadata errors**: Ensure the **Discovery endpoint** uses your real **tenant ID** and is reachable over HTTPS from Keycloak.