Konfiguration von Entra ID

Diese Anleitung beschreibt, wie der Identity Provider Entra ID (ehemals Azure AD) konfiguriert werden muss, um eine Integration mit dem CMI STS zu ermöglichen. Benutzende können sich so mit ihrem Entra ID Account bei CMI anmelden. Optional können Claims und Group Claims konfiguriert werden, um ein Feld- und Gruppenmapping einzurichten. Dabei werden Benutzereigenschaften aus Entra ID auf Benutzereigenschaften und Gruppenmitgliedschaften von CMI Benutzern übertragen.

Empfehlung: CMI empfiehlt die Verwendung des OpenID Connect (OIDC) Protokolls für die Anbindung von Entra ID. Die folgende Anleitung beschreibt die Variante mit OpenID Connect.

Hinweis: Die GUI von Entra ID kann sich mit der Zeit verändern. Die Beschreibungen der Schritte im Azure Portal sind daher möglicherweise nicht vollständig aktuell.

Inhaltsverzeichnis

• Konfiguration im Azure Portal
  • App Registration erstellen
  • Application ID URI hinzufügen
  • Client Secret anlegen
  • Informationen an CMI übermitteln
• Optionale Claims konfigurieren
  • Optional Claims (Feldmapping)
  • Group Claims (Gruppenmapping)
  • User-Info-Endpunkt
  • Weitere AD-Attribute als Claims bereitstellen
• CMI STS Konfiguration
  • Minimale Konfiguration (OIDC)
  • User-Info-Endpunkt aktivieren
  • Domain Hint
• Fehlerbehebung

Konfiguration im Azure Portal

In diesem Kapitel werden die grundlegenden Konfigurationsschritte beschrieben, die im Azure Portal vorgenommen werden müssen.

App Registration erstellen

1. Im Azure Portal unter Microsoft Entra ID im linken Menü App registrations (1) auswählen und oben New registration (2) auswählen.

1. Die App Registration wird wie folgt konfiguriert:
2. Name: Ein beliebiger Name (3), z.B. CMI STS
3. Supported Account Types: Für die meisten Anwendungsfälle kann Single Tenant (4) verwendet werden
4. Redirect URI: Eine oder mehrere Redirect URIs (5) eintragen, die von CMI mitgeteilt werden. Für die CMI Cloud lautet die Redirect URI: https://sts3.prod.cmicloud.ch/<tenantId>/identity/signin-oidc Falls die Redirect URIs nicht bekannt sind, können diese beim Projektleiter bzw. der Projektleiterin der CMI angefragt werden.
5. Mit Register (6) die Registrierung abschliessen.

1. Unter Authentication (7) die getätigten Einstellungen kontrollieren und unter Implicit grant and hybrid flows die Checkbox ID tokens (8) aktivieren.

Application ID URI hinzufügen

1. Auf der Hauptseite der App Registration den Link Add an Application ID URI (2) auswählen.

1. Add a scope (3) auswählen.
2. Eine Application ID URI kann von Entra ID generiert werden (Format: api://{GUID}).
3. Folgende Scope-Parameter ausfüllen:

Parameter	Wert
Scope name	CMI-STS-Authentication
Admin consent display name	CMI STS delegierte Anmeldung
Admin consent description	Erlaubt es CMI Benutzer, sich via M365 am CMI STS anzumelden

1. Mit Add scope den Scope speichern.

Optional kann anschliessend die Client ID als autorisierte Client-Applikation hinterlegt werden. Dies führt dazu, dass Benutzende keine Zustimmungsseite (Consent) zur Übermittlung personenbezogener Daten angezeigt bekommen, wenn sie sich bei CMI anmelden:

1. Auf der Hauptseite der App Registration unter Expose an API (7) auf Add a client application (8) klicken.
2. Die Client ID (9) eintragen, den zuvor erstellten Scope auswählen und mit Add application bestätigen.

Client Secret anlegen

Ein Client Secret wird benötigt, um eine sichere Kommunikation zwischen Entra ID und CMI zu etablieren (Authorization Code Flow). Client Secrets sind maximal 2 Jahre gültig.

Achtung: Das Azure Portal zeigt das Secret nur einmal an – nämlich dann, wenn es erzeugt wird. Kopieren Sie das Secret und bewahren Sie es an einem sicheren Ort auf.

Achtung: CMI verfügt über keine Information darüber, wann ein Secret abläuft. Wenn Sie ein Client Secret verwenden, müssen Sie CMI einige Tage vor dem Ablauf des Secrets unaufgefordert ein neues zukommen lassen. Sie können support@cmiag.ch kontaktieren, um einen sicheren Austausch anzufragen. Versenden Sie keine Secrets per E-Mail.

1. Auf der Hauptseite der App Registration zu Certificates & Secrets navigieren.
2. Mit New client secret (1) ein neues Client Secret erzeugen (2).
3. Das Secret kopieren und sicher aufbewahren.

Informationen an CMI übermitteln

Damit der CMI STS konfiguriert werden kann, werden folgende Informationen aus der App Registration benötigt. Der Austausch der Daten muss über einen sicheren Kanal erfolgen.

Auf der Hauptseite der App Registration unter Overview (1) finden sich die relevanten Daten. Der Button Endpoints (3) öffnet ein Menü mit den API-Endpunkten, darunter die URL des OpenID Connect metadata document.

Information	Wo zu finden	Schutzbedarf
OpenID Connect metadata document	Button Endpoints (3) → OpenID Connect metadata document	Unkritisch
Client ID	Application (client) ID (2) unter Essentials	Unkritisch, sollte nicht unnötigerweise öffentlich bekannt sein
Client Secret	Zuvor erzeugt unter Certificates & Secrets	Kritisch – nur über sicheren Kanal übertragen

Optionale Claims konfigurieren

Benutzereigenschaften wie Vor- und Nachname oder die E-Mail-Adresse können an CMI bei der Anmeldung übermittelt werden. CMI kann diese Eigenschaften auf eigene Benutzerobjekte übertragen (Feldmapping). Auch AD-Gruppenmitgliedschaften können als Claims übermittelt werden und auf das Gruppensystem von CMI übertragen werden (Gruppenmapping).

Hinweis: Ob und welche Claims benötigt werden, ist abhängig vom Anwendungsfall. Im Sinne der Datensparsamkeit sollten nur diejenigen Claims konfiguriert werden, die von den Fachpersonen wirklich benötigt werden.

Optional Claims (Feldmapping)

1. Auf der Hauptseite der App Registration zu Token configuration (1) navigieren und Add optional claim (2) auswählen.

1. ID (3) auswählen und die gewünschten Claims hinzufügen (z.B. email, family_name, given_name).
2. Die Checkbox Turn on the Microsoft Graph email, profile permission aktivieren und mit Add (4) bestätigen.

Group Claims (Gruppenmapping)

1. Auf der Hauptseite der App Registration zu Token configuration (1) navigieren und Add groups claim (2) auswählen.

1. Security groups (3) auswählen und unter Customize token properties by type die gewünschten Optionen konfigurieren (z.B. sAMAccountName). Optional Emit groups as role claims aktivieren.

Achtung: Diese Konfiguration fügt standardmässig alle Gruppenmitgliedschaften als Claim dem ID-Token hinzu. Je nach Organisation können Benutzende Teil von hunderten Gruppen sein. Das resultierende ID-Token wird dann so gross, dass es die Limitierungen des HTTP-Protokolls überschreitet. Im Sinne der Datensparsamkeit sollten nur relevante Gruppenmitgliedschaften übermittelt werden. Siehe auch den Abschnitt Fehlerbehebung: 400 Bad Request.

Eine bessere Lösung zum Auslesen der Gruppen eines Users ist die Verwendung des User-Info-Endpunkts.

User-Info-Endpunkt

Der CMI STS bietet die Möglichkeit, automatisch den User-Info-Endpunkt von Entra ID anzufragen, um weitere Claims wie z.B. Gruppen eines Users abzurufen. Damit der STS den User-Info-Endpunkt anfragen kann, muss in der App Registration die Berechtigung User.Read als Delegated Permission für die Microsoft Graph API hinterlegt werden:

1. In der App Registration zu API permissions navigieren.
2. Add a permission → Microsoft Graph → Delegated permissions auswählen.
3. Die Berechtigung User.Read hinzufügen.
4. Mit einem Entra ID Administrator den Admin consent bestätigen.

Weitere AD-Attribute als Claims bereitstellen

Standardmässig bietet Entra ID nur eine Handvoll Claims an, die sich via ID Token übertragen lassen. Für das Feldmapping im CMI sind aber manchmal weitere Attribute wie Telefonnummer, Organisation oder Kurzzeichen notwendig.

Die standardmässig von Entra ID angebotenen Claims sind in der Microsoft-Dokumentation zu Optional Claims beschrieben.

Um weitere AD-Eigenschaften verwenden zu können, müssen folgende Voraussetzungen erfüllt sein:

• Die Eigenschaften müssen vom lokalen AD nach Entra ID synchronisiert werden. Siehe dazu: Syncing extension attributes for Microsoft Entra Application Provisioning.
• Anschliessend kann eine Claims Mapping Policy per PowerShell erstellt werden, die an die App Registration gehängt wird.

Voraussetzungen für die PowerShell-Konfiguration

• Ein Benutzerkonto mit den entsprechenden Rechten (CMI empfiehlt Global Administrator; theoretisch reicht Cloud Application Administrator).
• Grundkenntnisse in PowerShell, da sich diese Konfiguration nicht über das Azure Portal erstellen lässt.
• Das PowerShell-Modul Microsoft.Graph (oder das ältere AzureADPreview-Modul) muss installiert sein.

Beispielskript: Claims Mapping Policy erstellen

Achtung: Dieses Beispielskript muss vor der Anwendung verstanden und an die eigenen Bedürfnisse angepasst werden.

# Claims die gesynct werden sollen: Source ist immer 'user',
# ID entspricht dem AD-Attribut, JwtClaimType der Benennung im ID Token.
# Falls kein Grund dagegenspricht, wird empfohlen fuer ID und JwtClaimType
# denselben String zu verwenden.

$claimsMappingPolicy = @{
    Version = 1
    IncludeBasicClaimSet = $true
    ClaimsSchema = @(
        @{
            Source = "user"
            ID = "telephoneNumber"
            JwtClaimType = "telephoneNumber"
        },
        @{
            Source = "user"
            ID = "department"
            JwtClaimType = "department"
        },
        @{
            Source = "user"
            ID = "JobTitle"
            JwtClaimType = "JobTitle"
        },
        @{
            Source = "user"
            ID = "onpremisessamaccountname"
            JwtClaimType = "onpremisessamaccountname"
        }
    )
}

$policyDefinition = @{
    ClaimsMappingPolicy = $claimsMappingPolicy
} | ConvertTo-Json -Depth 99 -Compress

# Interaktive Anmeldung am Azure AD
Connect-AzureAD

# Definieren der Policy
$policyName = "CMI-STS-ClaimsMappingPolicy"

# Name der App-Registrierung
$servicePrincipalName = "CMI STS"
$servicePrincipal = Get-AzureADServicePrincipal -SearchString $servicePrincipalName

# Vorhandene ClaimsMappingPolicies entfernen
$existingPolicies = Get-AzureADServicePrincipalPolicy -Id $servicePrincipal.ObjectId `
    | Where-Object { $_.Type -eq "ClaimsMappingPolicy" }
if ($existingPolicies) {
    $existingPolicies | Remove-AzureADPolicy
}

# Neue ClaimsMappingPolicy erstellen und zuweisen
$policy = New-AzureADPolicy -Type "ClaimsMappingPolicy" `
    -DisplayName $policyName -Definition $policyDefinition
Add-AzureADServicePrincipalPolicy -Id $servicePrincipal.ObjectId `
    -RefObjectId $policy.Id

Write-Host ("New claims mapping policy '{0}' set for app '{1}'." `
    -f $policy.DisplayName, $servicePrincipal.DisplayName) -ForegroundColor Green

Manifest-Anpassung

Damit die gemappten Claims im ID Token erscheinen, muss im Manifest der App Registration der Wert acceptMappedClaims auf true gesetzt werden:

1. In der App Registration zum Blade Manifest navigieren.
2. Den Wert "acceptMappedClaims" auf true setzen.
3. Speichern.

CMI STS Konfiguration

Nachfolgend wird gezeigt, wie Entra ID im CMI STS als Identity Provider konfiguriert wird. Allgemeine Informationen zur IDP-Konfiguration finden sich unter Identity Provider (IDP).

Minimale Konfiguration (OIDC)

"Tenants": {
    "mandant": {
        "ExternalIdps": {
            "entraid": {
                "Type": "Oidc",
                "ResponseType": "code",
                "Authority": "https://login.microsoftonline.com/{Tenant-ID}/v2.0",
                "ClientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "ClientSecret": "...",
                "CallbackPath": "/signin-oidc-entraid",
                "SignedOutCallbackPath": "/signout-callback-oidc-entraid",
                "Scope": ["openid", "profile", "email"]
            }
        }
    }
}

• Authority: Die URL enthält die Tenant-ID des Entra ID Mandanten.
• ClientId: Die Application (client) ID aus der App Registration.
• ClientSecret: Das zuvor erzeugte Client Secret.
• CallbackPath / SignedOutCallbackPath: Müssen eindeutig sein, wenn mehrere OIDC-IDPs konfiguriert werden.

Hinweis: CMI empfiehlt den Authorization Code Flow (ResponseType: "code") zu verwenden, da dieser sicherer ist als der Implicit Flow.

User-Info-Endpunkt aktivieren

Wenn der User-Info-Endpunkt in Entra ID konfiguriert wurde, muss im CMI STS zusätzlich GetClaimsFromUserInfoEndpoint aktiviert werden:

"entraid": {
    "Type": "Oidc",
    "ResponseType": "code",
    "GetClaimsFromUserInfoEndpoint": "true",
    "Scope": ["openid", "profile", "email"],
    // ... weitere Eigenschaften
}

Domain Hint

Mit dem DomainHint-Parameter kann der E-Mail-basierte Identifizierungsprozess bei Entra ID übersprungen werden. Der Benutzer wird direkt an den richtigen Tenant weitergeleitet:

"entraid": {
    "Type": "Oidc",
    "DomainHint": "beispiel.ch"
    // ... weitere Eigenschaften
}

Fehlerbehebung

STS meldet 400 Bad Request - Request Header or Cookie too Large

Sollte beim Login am STS die Meldung 400 Bad Request - Request Header or Cookie too Large erscheinen, ist sehr wahrscheinlich der HTTP-Header wegen des Entra ID Tokens zu gross.

Eine mögliche Ursache: In der App Registration unter Token configuration wurden Groups als Claim hinzugefügt. Bei Benutzern, die in vielen AD-Gruppen Mitglied sind, wird der Token dann sehr gross.

Lösung: Nur bestimmte Gruppen im Claim inkludieren:

1. Den bestehenden Group Claim unter Token configuration löschen.
2. Einen neuen Group Claim hinzufügen und die Option Groups assigned to the application auswählen.
3. In der zugehörigen Enterprise Application unter Users and groups nur die benötigten Gruppen zuweisen.

Weitere Informationen: Microsoft-Dokumentation: Configure group claims