docs/ms-entra/enterprise-app-keycloak.md

# 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)