SSO-Konfigurationsbeispiel des Identitäsanbieters Microsoft Entra External ID

Schritt 1: External Tenant erstellen

Es wird ein Microsoft Entra External ID Tenant benötigt – nicht nur ein normaler Workforce-Tenant, wenn es um CIAM-/Kundenidentitäten geht. External ID nutzt einen separaten externen Tenant für Kundenkonten, App-Registrierungen, User Flows und Sign-in-Methoden (s. Microsoft Learn).

1. Microsoft Entra Admin Center öffnen.

2. Manage tenants aufrufen.

3. Create klicken.

4. External auswählen.

 

1. Continue klicken.
2. Schritt Basics:

   Tenant Name: external-identities-for-digital-services
   
   Domain Name: customXDigitalServices
   
   Contry/Region: Germany 

   
   

3. Next klicken.
4. Schritt Add a subscription.
   
   
5. Next klicken.
6. Schritt Review + create.
7. Create klicken.
   
   
8. Manage tenants aufrufen.
   
   
9. External ID Tenant wechseln (switch directory).

Schritt 2: Testbenutzer für den Login anlegen

In der Admin Console:

1. In der Navigation auf Users klicken.
2. New user klicken.

3. Create new external user klicken.

   

4. Schritt Basics:

   Identities User Name: r_zufall
   Identities Email: rainer.zufall@muster.com
   Display name: Rainer Zufall 

    

   

5. Next klicken.

6. Schritt Properties.

   First name: Rainer
   Last name: Zufall
   User type: Member

   

7. Next klicken.

8. Next klicken.

9. Schritt Review + create.

10. Create klicken.
    

    

Konfigurator mit Endkunden-Accounts

Für den Konfigurator mit Endkunden-Accounts ist Create new external user vermutlich die korrekte Wahl.

Die drei Optionen haben unterschiedliche Zielgruppen:

Option 1: Create new user

Erstellt einen lokalen Benutzer im Tenant (Workforce-/interner Benutzer). Das sind typischerweise Administratoren, Entwickler oder Mitarbeiter, die den Tenant verwalten. Diese Benutzer erscheinen üblicherweise als normale Mitgliedskonten des Tenants.

Beispiele:

admin@firma.onmicrosoft.com
support@firma.de
interner Servicemitarbeiter 

Option 2: Invite external user

Erstellt einen B2B-Gastbenutzer durch Einladung eines Benutzers aus einem anderen Tenant oder einem Microsoft-Konto. Der Benutzer meldet sich weiterhin mit seiner eigenen Identität an.

Beispiele:

Lieferant
Externer Berater
Partnerunternehmen  

Option 3: Create new external user

Das ist die für External ID / CIAM gedachte Variante. Hier werden Kunden direkt im External Tenant angelegt. Dieser Benutzer gehört nicht zu der internen Workforce, sondern ist ein Customer Account.

Beispiele:

kunde1@beispiel.de
kunde2@beispiel.de
testkunde@firma.de 

Empfehlung für Konfigurator

Kunden können zunächst händisch angelegt und später auf Selbstregistrierung umgestellt werden, ohne die Architektur zu ändern.

User type

Für Endkunden im External-ID-Tenant empfiehlt es sich, in aller Regel den Type Member zu wählen.

Member:

1. Kunden, die du im External-ID-Tenant verwaltet werden.
2. Kunden, die sich an deinem Konfigurator anmelden.
3. Lokale Customer-Konten (CIAM-Szenario).
4. Benutzer, die über Sign-up/User Flows angelegt werden oder von Admins als Customer erstellt werden.

Guest:

1. B2B-Kollaborationsszenarien.
2. Benutzer aus anderen Unternehmen/Tenants.
3. Externe Partner, Lieferanten oder Berater, die auf Ressourcen zugreifen sollen.

Beispiele:

Für einen klassischen SaaS-/Kundenportal-/Konfigurator-Anwendungsfall empfiehlt es sich Create new external user + Member zu verwenden. Das entspricht am ehesten dem CIAM-Modell von Entra External ID, bei dem Kunden eigenständige Kundenkonten im External Tenant sind.

Schritt 3: Web-Client anlegen

In der Admin Console:

1. In der Navigation auf App registrations klicken.
2. New registration klicken.
3. Beispiel:

   Name: customX Web
   Supported account types: Single tenant only
   Redirect URI Plattform: Single-page application (SPA)
   Redirect URI: http://localhost/CustomXApp/Start.html 

   

4. Register klicken.
   
   

   

5. Application (client) ID notieren (Format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).

Schritt 4: API-Client anlegen

In der Admin Console:

1. In der Navigation auf App registrations klicken.

2. New registration klicken.

3. Beispiel:

   Name: customX API
   Supported account types: Single tenant only  

   

4. Register klicken.
   
   

   

5. Application (client) ID notieren (Format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).

6. Directory (tenant) ID notieren (Format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).

Schritt 5: (API-) Client Scope anlegen

In der Admin Console:

1. In der Navigation auf App registrations klicken.
2. Den Tab All applications wechseln.
3. customX API klicken.
4. In der Sub-Navigation auf Expose an API klicken.
5. Application ID URI Add klicken.
   
   
6. Den vorgeschlagenen Wert (api://<api-client-id>) übernehmen.
   
   
7. Save klicken.
8. Add a scope klicken.
9. Beispiel:
   

   Scope name: customx-user-access
   Who can consent: Admins and users
   Admin consent display name: Access customX API
   Admin consent description: Allows access to the customX API.
   User consent display name: Access digital-services
   User consent description: Allows the application access to our digital services.
   State: Enabled 

    

   

10. Add scope klicken.

11. Scopes (hier: api://<api-client-id>/customx-user-access) notieren.
    
    

Who can consent?

Für deinen Konfigurator mit Entra External ID ist die Einstellung meistens nicht kritisch, aber es ist gut zu verstehen, was sie bewirkt.

Wenn bei einem Scope (Expose an API → Add scope) die Option "Who can consent?" definiert wird, geht es darum, wer die Berechtigung für diesen Scope erteilen darf.

Admins and users

Jeder Benutzer kann selbst der Anwendung die Berechtigung für diesen Scope geben.

Beispiel:

1. Konfigurator fordert den Scope konfigurator.read.

2. Ein Benutzer meldet sich an.

3. Falls noch keine Zustimmung vorliegt, kann der Benutzer selbst auf Accept klicken.

4. Danach darf die Anwendung den Scope verwenden.

Das ist typisch für wenig kritische Berechtigungen wie:

1. Profil lesen

2. Eigene Daten lesen

3. Eigene Aufträge verwalten

Admins only

Nur ein Administrator des Tenants darf die Zustimmung erteilen.

Beispiel:

1. Der Scope gewährt Zugriff auf sensible Daten.

2. Ein normaler Kunde kann die Zustimmung nicht selbst erteilen.

3. Ein Admin muss einmalig Tenant-weite Zustimmung geben.

Das wird häufig verwendet für:

1. Administrative APIs

2. Zugriff auf Unternehmensdaten

3. Hochprivilegierte Berechtigungen

Entscheidungshilfe

Kunden melden sich an, um:

1. ihre Konfigurationsprojekte anzusehen

2. ihre Konfigurationsprojekte zu bearbeiten

dann wird üblicherweise Admins and users verwendet. Der Scope repräsentiert nur den Zugriff auf die eigene Konfigurator-API. Die Kunden geben diesem Scope einmal ihre Zustimmung.

Schritt 6: Client Scope dem Web-Client zuordnen

In der Admin Console:

1. In der Navigation auf App registrations klicken.

2. Den Tab All applications wechseln.

3. customX Web klicken.

4. In der Sub-Navigation auf API permissions klicken.

5. Add a permission klicken.

6. Den Tab APIs my organization uses wechseln.

7. customX API auswählen.
   
   

8. Berechtigung vergeben.

   Delegated permission: ausgewählt
   Permissions: customx-user-access auswählen

   
   

9. Add permissions klicken.

Admin consent required

Für Konfiguratoren mit externen Kunden wird Admin consent required normalerweise nicht aktiviert.

Wenn diese Option aktiviert ist, kann ein Benutzer den Scope nicht selbst freigeben. Stattdessen muss ein Administrator des Tenants die Zustimmung erteilen. Das wird typischerweise für höher privilegierte Berechtigungen verwendet.

Aktuelle Architektur:

External ID Tenant
├─ Web Client
├─ API Client
└─ Externe Kunden (Member)

Der Web Client ruft die eigene API mit dem Scope customx-user-access auf. Der Benutzer greift lediglich auf die eigene Anwendung zu. Er beantragt keine Microsoft Graph-Rechte und keine administrativen Berechtigungen.

In diesem Fall ist es üblich:

Scope: customx-user-access
Who can consent: Admins and users
Admin consent required: Nein 

Ist die Option aktiviert, müssen alle Zugriffe auf diesen Scope zuvor administrativ genehmigt werden.

Das kann dazu führen, dass:

1. Logins fehlschlagen,

2. Consent-Meldungen erscheinen,

3. zusätzliche Freigaben im Tenant ohne einen echten Sicherheitsgewinn vorgenommen werden müssen.

Die Option ist für gedacht für Szenarien wie:

1. Backend-Admin-API

2. Zugriff auf besonders sensible Daten

3. Multi-Tenant-Anwendungen für fremde Unternehmen

4. Scopes, die normale Benutzer niemals eigenständig freigeben sollen

Schritt 7: User Flow erstellen

Entra External ID braucht zusätzlich einen Sign-up and sign-in User Flow. Ein User Flow definiert, wie sich Kunden anmelden bzw. registrieren und welche Attribute bei der Registrierung gesammelt werden.

In der Admin Console:

1. In der Navigation auf External identities klicken.
2. In der Sub-Navigation auf User flows klicken.
3. New user flow klicken.
4. User flow erstellen:

   Name: digital-services-sign-up-and-sign-in
   Identity providers: Email Accounts with password
   User attributes: Given Name und Surname 

   

5. Create klicken.
   
   

Schritt 8: User Flow dem Web-Client zuordnen

In der Admin Console:

1. In der Navigation auf External identities klicken.
2. In der Sub-Navigation auf User flows klicken.
3. digital-services-sign-up-and-sign-in klicken.
4. In der Sub-Navigation auf Applications klicken.
5. Add application klicken.
   
   

   

6. Select klicken.

Schritt 9: E-Mail-Claim im Access-Token bereitstellen

In der Admin Console:

1. In der Navigation auf App registrations klicken.
2. Den Tab All applications wechseln.
3. customX API klicken.
4. In der Sub-Navigation auf Token configuration klicken.
5. Add optional claim klicken.
   

   Token type: Access
   Claim email: On
   Turn on the Microsoft Graph email permission (required for claims to appear in token): On

   

    

6. Add klicken.

7. Add klicken.

Schritt 10: customX konfigurieren

Issuer bestimmen

In der Admin Console:

1. In der Navigation auf App registrations klicken.
2. Den Tab All applications wechseln.
3. customX Web klicken.
4. Endpoints klicken.
5. OpenID Connect metadata document-Link kopieren.
   
   

   

6. Kopierten Link in neuem Tab eingeben.
7. Issuer-Adresse kopieren.
   
   

   

Eintragung in customX Einstellungen

1. "C:\customX\Config\customX.ini" öffnen.
2. Einstellungen eintragen.
   

   [SSO]
   Authentication=3
   
   [OpenIdConnectAuthentication]
   ;issuer=https://<tenant-subdomain>.ciamlogin.com/<tenant-id>/v2.0
   ;web-client-id=<Application (client) ID des Web-Clients>
   ;api-client-id=<Application (client) ID des API-Clients>
   ;scopes=api://<api-client-id>
   issuer=https://customxdigitalservices.ciamlogin.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/v2.0
   redirect-uri=http://localhost/CustomXApp/Start.html
   web-client-id=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
   api-client-id=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
   scopes=api://XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
   
   [SSOParameterMapping]
   cxEmail=email 

Schritt 11: (Optional) Benutzerdefinierte Anwendungsansprüche (Claims) übergebe

Benutzerattribute anlegen

In der Admin Console:

1. In der Navigation auf External identities klicken.
2. In der Sub-Navigation auf Custom user attributes klicken.
3. Add klicken.
   

   Name: CustomerID
   Data Type: string
   Description: Customer identifier for digital-services. 

   

    

4. Create klicken.
5. Add klicken.
   

   Name: ConfiguratorUserRole
   Data Type: string
   Description: Application role for configurator. 

    

   

    

6. Create klicken.

Werte mittels Microsoft Graph setzen

Microsoft Graph öffnen und Berechtigungen setzen

1. Microsoft Graph des External Tenants aufrufen.
   

   https://developer.microsoft.com/graph/graph-explorer?tenant=<TENANT-ID>
   
   Beispiel:
   https://developer.microsoft.com/graph/graph-explorer?tenant=11111111-2222-3333-4444-555555555555 

    

2. Mit einem Admin-Konto aus dem External Tenant anmelden.
3. Tenant kontrollieren.
   

   GET https://graph.microsoft.com/v1.0/organization?$select=id,displayName,verifiedDomains 

    

4. Run query klicken.
   

   

5. Berechtigungen setzen.
   

   User.ReadWrite.All
   Directory.ReadWrite.All 

   

Extensions-App-ID ermitteln

In der Admin Console:

1. In der Navigation auf App registrations klicken.
2. Den Tab All applications wechseln.
3. Ausdruck suchen:
   

   b2c-extensions-app
   
   oder
   
   aad-extensions-app 

    

4. Application (client) ID kopieren.
5. Bindestriche entfernen.
   

   

Beispiel:

Original:
831374b3-bd50-41bf-aa54-263ec9e050fc

Für Extension Attribute:
831374b3bd5041bfaa54263ec9e050fc 

Benutzerdaten prüfen

1. Microsoft Graph öffnen

2. Benutzer überprüfen.

   GET https://graph.microsoft.com/v1.0/users/<user-id>

3. Run query klicken.

   

4. Werte setzen.
   

   PATCH https://graph.microsoft.com/v1.0/users/<user-id>
   Content-Type: application/json
   {
   "extension_<extensions-app-id>_CustomerID": "4711",
   "extension_<extensions-app-id>_ConfiguratorUserRole": "customer"
   }

5. Run query klicken.
   

   

6. Ergebnis prüfen
   

   GET https://graph.microsoft.com/v1.0/users/<user-id>?$select=id,displayName,userPrincipalName,extension_<extensions-app-id>_CustomerID,extension_<extensions-app-id>_ConfiguratorUserRole

   

Anwendungsanspruch dem Access-Token hinzufügen

In der Admin Console:

1. In der Navigation auf App registrations klicken.
2. Den Tab All applications wechseln.
3. customX API klicken.
4. Bei Managed application in local directory auf customX API klicken.
   
   

   

5. In der Sub-Navigation auf Single sign-on klicken.
6. Bei Attributes & Claims auf Edit klicken.
7. Add new claim klicken.
8. Manage claim:
   

   Name: customer_id
   
   Source: Directory schema extension
   
   Select Application: Extensions-App

    

   

9. Select klicken.
10. user.CustomerID auswählen.
    
    

    

11. Add klicken.
12. Add new claim klicken.

13. Manage claim:

    Name: configurator_user_role
    
    Source: Directory schema extension
    
    Select Application: Extensions-App
    

    

14. Select klicken.

15. user.ConfiguratorUserRole auswählen.

    

Ggf. Manifest Datei anpassen

Erscheint die Fehlermeldung "OIDC Applications require custom signing keys to customize claims. Please check the security considerations before customizing the claims for the application", muss für Single-Tenant-Apps einen OIDC/JWT-Claim zu customizen.

Für Single-Tenant-Apps ist der normale Weg: Die App muss im Manifest explizit erlauben, dass gemappte Claims akzeptiert werden — über acceptMappedClaims: true. Microsoft beschreibt acceptMappedClaims genau dafür: Eine Anwendung kann Claims Mapping ohne eigenen Custom Signing Key nutzen, muss aber explizit anerkennen, dass Tokeninhalte durch Claims-Mapping verändert wurden.

In der Admin Console:

1. In der Navigation auf App registrations klicken.

2. Den Tab All applications wechseln.

3. customX API klicken.

4. In der Sub-Navigation auf Manifest klicken.

5. Nach "acceptMappedClaims": null suchen.

6. "acceptMappedClaims" auf true setzen.
   
   

   

Mapping in den customX-Einstellungen hinzufügen

1. "C:\customX\Config\customX.ini" öffnen.
2. Einstellungen eintragen.

[SSOParameterMapping]
cxEmail=email # Bereits in Schritt 9 gesetzt
IdentityProviderCustomerID=customer_id
IdentityProviderConfiguratorUserRole=configurator_user_role

Schritt 12: Access token überprüfen

1. Webbrowser öffnen.

2. DevTools öffnen z. B. Taste F12 drücken.

3. Tab Network/ Netzwerk öffnen.

4. customX Startseite aufrufen (http://localhost/CustomXApp/Start.html).

5. SSO-Button klicken.

6. In Microsoft Entra External ID authentifizieren.

7. Im Network-Tab im Filter nach token suchen.

8. Token auswählen.

9. Tab Preview auswählen
   
   

   

10. access_token Wert kopieren.

11. JSON-Web Token encoder öffnen (https://www.jwt.io/).

12. Access-Token encoden.

13. Inhalt auf wichtige Claims prüfen.

{
  "aud": "<api-client-id>",
  "iss": "https://<tenant-subdomain>.ciamlogin.com/<tenant-id>/v2.0",
  ...
  "azp": "<web-client-id>",
  ...
  "email": "rainer.zufall@muster.com",
  "name": "Rainer Zufall",
  ...
  "preferred_username": "rainer.zufall@muster.com",
  ...
  "scp": "customx-user-access",
  ...
  "customer_id": "1111",
  "configurator_user_role": "customer"
}

Das bedeutet:

Ergebnisbewertung

Die Token-Prüfung ist erfolgreich, wenn:

1. der Issuer (iss) dem konfigurierten Tenant entspricht,

2. die Audience (aud) auf die customX API verweist,

3. die anfragende Anwendung (azp) die customX-Webanwendung ist,

4. der erforderliche Scope customx-user-access enthalten ist,

5. sowie alle benötigten benutzerdefinierten Claims (z. B. customer_id und configurator_user_role) vorhanden sind.

Sind diese Voraussetzungen erfüllt, wurde das Access Token korrekt ausgestellt und kann von der customX API zur Autorisierung des Benutzers verwendet werden.