Schützen Ihrer API, die als API-Connector in Benutzerflows für die Self-Service-Registrierung von Microsoft Entra External ID verwendet wird

Gilt für: Mitarbeitermandanten Externe Mandanten (weitere Informationen)

Wenn Sie eine REST-API in einen Benutzerflow für die Self-Service-Registrierung von Microsoft Entra External ID integrieren, müssen Sie Ihren REST-API-Endpunkt mittels Authentifizierung schützen. Die REST-API-Authentifizierung stellt sicher, dass nur Dienste mit ordnungsgemäßen Anmeldeinformationen, z. B. Microsoft Entra ID, Aufrufe an Ihren Endpunkt senden können. In diesem Artikel erfahren Sie, wie Sie die REST-API schützen können.

Voraussetzungen

Führen Sie die Schritte im Leitfaden Exemplarische Vorgehensweise: Hinzufügen eines API-Connectors zu einem Benutzerflow für die Registrierung aus.

Sie können Ihren API-Endpunkt entweder mithilfe der HTTP-Standardauthentifizierung oder mithilfe der HTTPS-Clientzertifikatauthentifizierung schützen. In beiden Fällen stellen Sie die Anmeldeinformationen bereit, die von Microsoft Entra ID beim Aufrufen Ihres API-Endpunkts verwendet werden. Der API-Endpunkt überprüft dann die Anmeldeinformationen und führt Autorisierungsentscheidungen aus.

HTTP-Standardauthentifizierung

Tipp

Die Schritte in diesem Artikel können je nach dem Portal, mit dem Sie beginnen, geringfügig variieren.

Die HTTP-Standardauthentifizierung ist in RFC 2617 definiert. Die Standardauthentifizierung funktioniert wie folgt: Microsoft Entra ID sendet eine HTTP-Anforderung mit den Clientanmeldeinformationen (username und password) im Header Authorization. Die Anmeldeinformationen werden als Base64-codierte Zeichenfolge im Format username:password angegeben. Ihre API ist dann für die Überprüfung dieser Werte verantwortlich, um andere Autorisierungsentscheidungen zu treffen.

Führen Sie die folgenden Schritte aus, um einen API-Connector mit HTTP-Standardauthentifizierung zu konfigurieren:

1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Benutzeradministrator an.
2. Browsen Sie zu Identität>External Identities>Übersicht.
3. Wählen Sie Alle API-Connectors und dann den zu konfigurierenden API-Connector aus.
4. Wählen Sie als Authentifizierungstyp die Option Standard aus.
5. Geben Sie den Benutzernamen und das Kennwort für Ihren REST-API-Endpunkt an.
6. Wählen Sie Speichern aus.

HTTPS-Clientzertifikatauthentifizierung

Die Clientzertifikatauthentifizierung ist eine gegenseitige zertifikatbasierte Authentifizierung, bei welcher der Client (Microsoft Entra ID) sein Clientzertifikat für den Server bereitstellt, um seine Identität nachzuweisen. Dies erfolgt im Rahmen des SSL-Handshakes. Ihre API muss überprüfen, ob die Zertifikate zu einem gültigen Client (beispielsweise Microsoft Entra ID) gehören, und sie muss Autorisierungsentscheidungen treffen. Bei dem Clientzertifikat handelt es sich um ein digitales X.509-Zertifikat.

Wichtig

In Produktionsumgebungen muss das Zertifikat von einer Zertifizierungsstelle signiert werden.

Erstellen eines Zertifikats

Option 1: Verwenden von Azure Key Vault (empfohlen)

Zum Erstellen eines Zertifikats können Sie den Azure Key Vault verwenden, der über Optionen für selbstsignierte Zertifikate und Integrationen mit Zertifikatausstelleranbietern für signierte Zertifikate verfügt. Empfohlene Einstellungen umfassen:

• Betreff: CN=<yourapiname>.<tenantname>.onmicrosoft.com
• Inhaltstyp: PKCS #12
• Gültigkeitsdauer Aktionstyp: Email all contacts at a given percentage lifetime oder Email all contacts a given number of days before expiry
• Schlüsseltyp: RSA
• Schlüsselgröße: 2048
• Exportierbarer privater Schlüssel: Yes (um die Datei vom Typ .pfx exportieren zu können)

Sie können dann das Zertifikat exportieren.

Option 2: Erstellen eines selbstsignierten Zertifikats mit PowerShell

Wenn Sie noch nicht über ein Zertifikat verfügen, können Sie ein selbstsigniertes Zertifikat verwenden. Ein selbstsigniertes Zertifikat ist ein Sicherheitszertifikat, das nicht von einer Zertifizierungsstelle (ZS) signiert ist und nicht die Sicherheitsgarantien eines Zertifikats bietet, das von einer Zertifizierungsstelle signiert wurde.

Windows

Verwenden Sie unter Windows das PowerShell-Cmdlet New-SelfSignedCertificate, um ein Zertifikat zu generieren.

1. Führen Sie den folgenden PowerShell-Befehl aus, um ein selbstsigniertes Zertifikat zu generieren. Ändern Sie das Argument -Subject entsprechend Ihrer Anwendung und dem Azure AD B2C-Mandantennamen, z. B. contosowebapp.contoso.onmicrosoft.com. Sie können auch das -NotAfter-Datum anpassen, um einen anderen Ablaufzeitpunkt für das Zertifikat anzugeben.

   New-SelfSignedCertificate `
       -KeyExportPolicy Exportable `
       -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
       -KeyAlgorithm RSA `
       -KeyLength 2048 `
       -KeyUsage DigitalSignature `
       -NotAfter (Get-Date).AddMonths(12) `
       -CertStoreLocation "Cert:\CurrentUser\My"
   

2. Suchen Sie auf dem Windows-Computer nach Benutzerzertifikate verwalten und wählen Sie

3. Wählen Sie unter Zertifikate - Aktueller Benutzer die Option Persönlich>Zertifikate>IhrAnwendungsname.ihrmieter.onmicrosoft.com.

4. Wählen Sie das Zertifikat und dann Aktion>Alle Aufgaben>Exportieren aus.

5. Wählen Sie Weiter>Ja, den privaten Schlüssel exportieren>Weiter.

6. Übernehmen Sie die Standardeinstellungen für Exportdateiformat, und wählen Sie dann Weiter.

7. Aktivieren Sie die Option Passwort, geben Sie ein Passwort für das Zertifikat ein, und wählen Sie dann Weiter.

8. Um einen Speicherort für Ihr Zertifikat anzugeben, wählen Sie Durchsuchen und navigieren Sie zu einem Verzeichnis Ihrer Wahl.

9. Geben Sie im Fenster Speichern unter einen Dateinamen ein, und wählen Sie dann Speichern.

10. Wählen Sie Weiter>Fertig stellen aus.

Damit das Kennwort für die PFX-Datei in Azure AD B2C akzeptiert wird, muss es statt mit „AES256-SHA256“ mit der Option „TripleDES-SHA1“ im Exporthilfsprogramm des Windows-Zertifikatspeichers verschlüsselt werden.

macOS

Verwenden Sie unter macOS den Zertifikatsassistenten in Keychain Access, um ein Zertifikat zu generieren.

1. Führen Sie die Anweisungen unter Erstellen von selbstsignierten Zertifikaten mit der Schlüsselbundverwaltung auf dem Mac aus.
2. Wählen Sie in der App „Schlüsselbundverwaltung“ auf Ihrem Mac das von Ihnen erstellte Zertifikat aus.
3. Wählen Sie Ablage>Objekte exportieren aus.
4. Wählen Sie einen Dateinamen aus, um das Zertifikat zu speichern. Beispiel: self-signed-certificate.p12.
5. Wählen Sie als Dateiformat die Option Personal Information Exchange (.p12) aus.
6. Wählen Sie Speichern aus.
7. Geben Sie ein Kennwort in den Feldern Kennwort und Bestätigen ein.
8. Ändern Sie die Erweiterung der Datei in „.pfx“. Beispiel: self-signed-certificate.pfx.

Konfigurieren Ihres API-Connectors

Führen Sie die folgenden Schritte aus, um einen API-Connector mit Authentifizierung über ein Clientzertifikat zu konfigurieren:

1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Benutzeradministrator an.
2. Browsen Sie zu Identität>External Identities>Übersicht.
3. Wählen Sie Alle API-Connectors und dann den zu konfigurierenden API-Connector aus.
4. Wählen Sie als Authentifizierungstyp die Option Zertifikat aus.
5. Wählen Sie im Feld Zertifikat hochladen die PFX-Datei Ihres Zertifikats mit einem privaten Schlüssel aus.
6. Geben Sie im Feld Kennwort eingeben das Kennwort des Zertifikats ein.
7. Wählen Sie Speichern aus.

Treffen von Autorisierungsentscheidungen

Ihre API muss die Autorisierung basierend auf gesendeten Client-Zertifikaten implementieren, um die API-Endpunkte zu schützen. Für den Azure App Service und die Azure Funktionen finden Sie unter Konfigurieren der gegenseitigen TLS-Authentifizierung Informationen zum Aktivieren und Validieren des Zertifikats über Ihren API-Code. Alternativ können Sie Azure API Management als Ebene vor einem beliebigen API-Dienst verwenden, um Clientzertifikateigenschaften auf gewünschte Werte zu überprüfen.

Erneuern von Zertifikaten

Es wird empfohlen, Erinnerungswarnungen für den Zeitpunkt festzulegen, an dem das Zertifikat abläuft. Wenn die verwendeten Zertifikate ablaufen, müssen Sie ein neues Zertifikat generieren und die obigen Schritte wiederholen. Für den Übergang zu einem neuen Zertifikat kann Ihr API-Dienst während der Bereitstellung des neuen Zertifikats vorübergehend alte und neue Zertifikate akzeptieren.

Wenn Sie ein neues Zertifikat in einen vorhandenen API-Connector hochladen möchten, wählen Sie unter API-Connectors den API-Connector und anschließend die Option Neues Zertifikat hochladen aus. Das zuletzt hochgeladene Zertifikat, das noch nicht abgelaufen ist und dessen Startdatum überschritten wurde, wird automatisch von Microsoft Entra ID verwendet.

Authentifizierung mit API-Schlüssel

Von einigen Diensten wird ein API-Schlüsselmechanismus verwendet, um den Zugriff auf Ihre HTTP-Endpunkte während der Entwicklung zu verschleiern. In diesem Fall muss der Aufrufer einen eindeutigen Schlüssel als HTTP-Header oder HTTP-Abfrageparameter einschließen. Für Azure Functions können Sie dies erreichen, indem Sie code als Abfrageparameter in die Endpunkt-URL Ihres API-Connectors einschließen. Beispiel: https://contoso.azurewebsites.net/api/endpoint?code=0123456789.

Hierbei handelt es sich nicht um einen Mechanismus, der allein in der Produktion verwendet werden sollte. Daher ist die Konfiguration für die Standard- oder Zertifikatauthentifizierung immer erforderlich. Wenn Sie für Entwicklungszwecke keine Authentifizierungsmethode implementieren möchten (nicht empfohlen), können Sie in der API-Connectorkonfiguration die Standardauthentifizierung auswählen und temporäre Werte für username und password verwenden, die von der API ignoriert werden können, während Sie die ordnungsgemäße Autorisierung implementieren.

Nächste Schritte

• Verwenden Sie unsere Schnellstartbeispiele, um direkt loszulegen.