chore: add initial structure and ms-entra enterprise application guide

README.md

@@ -1,2 +1,13 @@
-# docs
+# 📚 Documentation Repository
 
+This repository contains documentation, guides, and reference material.
+
+## 📖 Available Documentation
+
+- **[Keycloak](./keycloak/)**  
+  Documentation and guides related to Keycloak configuration and best practices.  
+
+- **[Microsoft Entra](./ms-entra/)**  
+  Documentation and guides related to Microsft Entra configuration and best practices.
+  - [Enterprise App Integration with Keycloak](./ms-entra/enterprise-app-keycloak.md)  
+    Step-by-step instructions for creating an Enterprise Application in Microsoft Entra (Azure AD) as an identity provider for Keycloak.

ms-entra/enterprise-app-keycloak.md

@@ -0,0 +1,189 @@
+# Create an Enterprise Application in Microsoft Entra ID for Keycloak
+
+> **Goal:** Register an Enterprise Application in Microsoft Entra so it can be integrated with Keycloak for authentication.
+
+---
+
+## Prerequisites
+- Admin access to **Microsoft Entra ID** (formerly Azure AD).
+- Access to the **Azure Portal**: [https://entra.microsoft.com](https://entra.microsoft.com).
+- A running **Keycloak** instance (this guide only covers the Entra side).
+- **Organisation alias** given by the keycloak operator.
+
+---
+
+## Steps
+
+### Step 1 — Log in to Microsoft Entra
+1. Open [https://entra.microsoft.com](https://entra.microsoft.com).
+2. Sign in with your administrator account.
+
+---
+
+### Step 2 — Navigate to Enterprise Applications
+1. In the left-hand menu, select **Enterprise applications**.
+2. Click **+ New application**.
+
+![Step 2 — Navigate to Enterprise Applications](images/enterprise-app-keycloak/step-02-A.png "Enterprise applications menu")  
+*Figure 1: Location of 'Enterprise applications' in the Entra menu.*
+
+---
+
+### Step 3 — Create a New Application
+1. In the **Browse Azure AD Gallery** window, select **Create your own application**.
+2. Enter a name (e.g., `Digitalboard`).
+3. Choose **Register an application to integrate with Microsoft Entra ID**.
+4. Click **Create**.
+
+![Step 3 — Create new application](images/enterprise-app-keycloak/step-03-A.png "Microsoft Entra Gallery")  
+*Figure 3A: Microsoft Entra Gallery.*
+
+![Step 3 — Create new application](images/enterprise-app-keycloak/step-03-B.png "Create your own application form")  
+*Figure 3B: Create an application for Keycloak.*
+
+---
+
+### Step 4 — Configure the New Application
+1. You are redirected to a page titled **Register an application**.
+2. Fill in:
+   - **Name**: `Digitalboard` (should be prefilled)  
+   - **Supported account types**: Choose according to your needs:  
+     - Single tenant (only your organization, default for Digitalboard)  
+     - Multitenant (cross-organization)  
+   - **Redirect URI**: Select **Web** and enter  
+     `https://auth.digitalboard.ch/realms/Digitalboard/broker/<your alias>/endpoint`.  
+     `<your alias>` is the alias given by Digitalboard for your organization. If unsure, ask Digitalboard.  
+3. Click **Register**. 
+
+![Step 4 — Application Registration](images/enterprise-app-keycloak/step-04-A.png "Application registration")  
+*Figure 4A: Register the application.*
+
+---
+
+### Step 5 — Collect Application Details
+1. In the left-hand menu, click on **Enterprise applications**.
+2. The new application should now be searchable in the list. Click on it.
+3. Note down:  
+   - **Application (client) ID**  
+   - **Directory (tenant) ID**  
+4. These are needed to configure Keycloak with the identity provider.
+
+![Step 5 — Configure Single Sign-On](images/enterprise-app-keycloak/step-05-A.png "Registered Application")  
+*Figure 5A: Registered application inside Enterprise applications list.*
+
+![Step 5 — App details](images/enterprise-app-keycloak/step-05-B.png "Application overview with IDs")  
+*Figure 5B: Application ID and Tenant ID in the overview page.*
+
+---
+
+### Step 6 — Create a Client Secret
+1. Select **App registrations** in the left-hand menu.
+2. A list of app registrations will open. Search for your newly registered application (e.g., `Digitalboard`) and click on it.
+3. In the left menu, select **Certificates & secrets**.
+4. Under **Client secrets**, click **+ New client secret**.
+5. Add a description (e.g., `Keycloak Secret`, or if it expires annually, `2025`) and set an expiration (e.g., 12 months).
+6. Click **Add**.
+7. Copy and save the generated **Value** immediately (you won’t be able to see it again later). The secret is required to configure Keycloak with the identity provider.
+
+![Step 6 — App registrations list](images/enterprise-app-keycloak/step-06-A.png "App registrations list")  
+*Figure 6A: App registrations list.*
+
+![Step 6 — Client secret](images/enterprise-app-keycloak/step-06-B.png "Generate client secret")  
+*Figure 6B: Creating the client secret.*
+
+![Step 6 — Client secret](images/enterprise-app-keycloak/step-06-C.png "Generate client secret")  
+*Figure 6C: Creating the client secret.*
+
+![Step 6 — Copy Client secret](images/enterprise-app-keycloak/step-06-D.png "Copy client secret")  
+*Figure 6D: Copying the client secret.*
+
+---
+
+### Step 7 — Copy Endpoint
+1. In the left menu, select **Overview**.
+2. Click on the button **Endpoints**.
+3. Copy and save the value of **OpenID Connect metadata document**. This is required to configure Keycloak with the identity provider.
+
+![Step 7 — Endpoint Button](images/enterprise-app-keycloak/step-07-A.png "Endpoint Button")  
+*Figure 7A: The endpoint button.*
+
+![Step 7 — Endpoint List](images/enterprise-app-keycloak/step-07-B.png "Endpoint List")  
+*Figure 7B: The list with endpoints.*
+
+---
+
+### Step 8 — Configure Claims
+1. In the left menu, select **Token configuration**.
+2. Click **Add optional claim**.
+3. Select the following claims:  
+   - `email`  
+   - `family_name`  
+   - `given_name`  
+   - `onprem_sid`  
+4. Click **Add**.
+5. A dialog appears: *Some of these claims require OpenID Connect scopes to be configured…*  
+6. **Check the box** in the dialog and click **Add**. This will automatically add the required scopes to the application.
+
+![Step 8 — Token configuration page](images/enterprise-app-keycloak/step-08-A.png "Token configuration page")  
+*Figure 8A: Token configuration page.*
+
+![Step 8 — Adding claims](images/enterprise-app-keycloak/step-08-B.png "Adding claims")  
+*Figure 8B: Adding claims.*
+
+![Step 8 — Scopes dialog](images/enterprise-app-keycloak/step-08-C.png "Scopes dialog")  
+*Figure 8C: Scopes dialog.*
+
+---
+
+### Step 9 — Grant Admin Consent for Scopes
+1. Go to **API Permissions**.
+2. Click **Grant admin consent for <your-tenant>**.
+3. A confirmation dialog will open. Click **Yes** to grant admin consent.
+
+![Step 9 — API permissions page](images/enterprise-app-keycloak/step-09-A.png "API permissions page")  
+*Figure 9A: API permissions page.*
+
+![Step 9 — Admin consent confirmation dialog](images/enterprise-app-keycloak/step-09-B.png "Admin consent confirmation dialog")  
+*Figure 9B: Admin consent confirmation dialog.*
+
+---
+
+### Step 10 — Limit Access to the Application
+> This step is only needed if you don’t want all directory users to have access.
+
+1. Go back to the created **Enterprise application** (see Step 5).
+2. Click on **Properties** in the left menu. 
+3. Set **Assignment required** to **Yes**.
+4. Click **Save**. Now only the creator of the application has access.
+
+![Step 10 — API permissions page](images/enterprise-app-keycloak/step-10-A.png "API permissions page")  
+*Figure 10A: API permissions page.*
+
+---
+
+### Step 11 — Assign Users or Groups to the Application
+> This step is only needed if you don’t want all directory users to have access. Requires Step 10.
+
+1. Click on **Users and groups** in the left menu.
+2. Click the button **+ Add user/group**.
+3. Under **Users and groups**, click the blue link.
+4. A new dialog opens, where you can select the users/groups that should have access.
+5. Save the assignment by clicking **Select**.
+
+![Step 11 — Users and groups page](images/enterprise-app-keycloak/step-11-A.png "Users and groups page")  
+*Figure 11A: Users and groups page.*
+
+![Step 11 — Users and groups assignment dialog](images/enterprise-app-keycloak/step-11-B.png "Users and groups assignment dialog")  
+*Figure 11B: Users and groups assignment dialog.*
+
+![Step 11 — Assigned groups](images/enterprise-app-keycloak/step-11-C.png "Assigned groups")  
+*Figure 11C: Assigned groups.*
+
+---
+
+## Next Steps
+See the Keycloak Microsoft Entra identity provider guide, or send the following information to your Keycloak operator:
+- **Application (client) ID** (Step 5)
+- **Directory (tenant) ID** (Step 5)
+- **Application (client) Secret** (Step 6)
+- **OpenID Connect metadata document URL** (Step 7)