Tutorial: Entwickeln eines SCIM-Endpunkts und Planen seiner Bereitstellung in Microsoft Entra ID

Als Anwendungsentwickler können Sie die SCIM-Benutzerverwaltungs-API (System for Cross-Domain Identity Management, System für die domänenübergreifende Identitätsverwaltung) verwenden, um die automatische Bereitstellung von Benutzern und Gruppen zwischen Ihrer Anwendung und Microsoft Entra ID zu aktivieren. In diesem Artikel erfahren Sie, wie Sie einen SCIM-Endpunkt erstellen und in den Microsoft Entra-Bereitstellungsdienst integrieren. Die SCIM-Spezifikation bietet ein allgemeines Benutzerschema für die Bereitstellung. Bei der Verwendung mit Verbundstandards wie SAML oder OpenID Connect bietet SCIM Administratoren eine auf Standards basierende End-to-End-Lösung für die Zugriffsverwaltung.

Provisioning from Microsoft Entra ID to an app with SCIM

SCIM 2.0 ist eine standardisierte Definition von zwei Endpunkten: einem /Users- und einem /Groups-Endpunkt. Es verwendet allgemeine REST-API-Endpunkte, um Objekte zu erstellen, zu aktualisieren und zu löschen. SCIM besteht aus einem vordefinierten Schema für allgemeine Attribute wie Gruppenname, Benutzername, Vorname, Nachname und E-Mail-Adresse.

Apps, die eine SCIM 2.0 REST-API bieten, können den Aufwand für die Arbeit mit einer proprietären Benutzerverwaltungs-API reduzieren oder eliminieren. So ist beispielsweise jeder konforme SCIM-Client in der Lage, eine HTTP POST-Anforderung für ein JSON-Objekt an den /Users-Endpunkt zu senden, um einen neuen Benutzereintrag zu erstellen. Anstatt eine leicht abweichende API für dieselben grundlegenden Aktionen zu benötigen, können Apps, die dem SCIM-Standard entsprechen, sofort die Vorteile bereits vorhandener Clients, Tools und Codes nutzen.

Das in SCIM 2.0 definierte Standard-Benutzerobjektschema und die REST-APIs für die Verwaltung (RFC 7642, 7643, 7644) ermöglichen eine einfachere Integration von Identitätsanbietern und Apps. Anwendungsentwickler, die einen SCIM-Endpunkt erstellen, können die Integration mit jedem SCIM-konformen Client durchführen, ohne selbst Anpassungen vornehmen zu müssen.

Um die Bereitstellung für eine Anwendung zu automatisieren, ist es erforderlich, einen SCIM-Endpunkt zu erstellen und zu integrieren, auf den vom Microsoft Entra-Bereitstellungsdienst zugegriffen wird. Verwenden Sie die folgenden Schritte, um mit der Bereitstellung von Benutzern und Gruppen in Ihrer Anwendung zu beginnen.

  1. Entwerfen Ihres Benutzer- und Gruppenschemas: Identifizieren Sie die Objekte und Attribute Ihrer Anwendung, um zu ermitteln, wie sie mit dem von der Microsoft Entra SCIM-Implementierung unterstützten Benutzer- und Gruppenschema zusammenhängen.

  2. Verstehen der Microsoft Entra SCIM-Implementierung: Machen Sie sich damit vertraut, wie der Microsoft Entra-Bereitstellungsdienst implementiert wird, um die Verarbeitung von SCIM-Protokollanforderungen und -antworten zu modellieren.

  3. Erstellen eines SCIM-Endpunkts: Ein Endpunkt muss SCIM 2.0-kompatibel sein, damit er in den Microsoft Entra-Bereitstellungsdienst integriert werden kann. Optional können Sie Bibliotheken und Codebeispiele der Microsoft Common Language Infrastructure (CLI) verwenden, um Ihren Endpunkt zu erstellen. Diese Beispiele dienen nur als Referenz und zu Testzwecken. Sie sollten nicht als Abhängigkeiten in Ihrer Produktions-App verwendet werden.

  4. Integrieren Ihres SCIM-Endpunkts in den Microsoft Entra-Bereitstellungsdienst. Microsoft Entra ID unterstützt mehrere Drittanbieteranwendungen, die SCIM 2.0 implementieren. Wenn Sie eine dieser Apps verwenden, können Sie sowohl die Bereitstellung als auch die Aufhebung der Bereitstellung von Benutzern und Gruppen schnell automatisieren.

  5. [Optional] Veröffentlichen Ihrer Anwendung im Microsoft Entra-Anwendungskatalog: Erleichtern Sie es Ihren Kunden, Ihre Anwendung zu entdecken und die Bereitstellung einfach zu konfigurieren.

Diagram that shows the required steps for integrating a SCIM endpoint with Microsoft Entra ID.

Entwerfen Ihres Benutzer- und Gruppenschemas

Jede Anwendung benötigt verschiedene Attribute, um einen Benutzer oder eine Gruppe erstellen zu können. Beginnen Sie Ihre Integration, indem Sie die erforderlichen Objekte (Benutzer, Gruppen) und Attribute (Name, Vorgesetzter, Positionsbezeichnung, usw.) identifizieren, die Ihre Anwendung benötigt.

Mit dem SCIM-Standard wird ein Schema zum Verwalten von Benutzern und Gruppen definiert.

Für das Kernbenutzerschema sind nur drei Attribute erforderlich (alle anderen sind optional):

  • id: Vom Dienstanbieter definierter Bezeichner
  • userName: Ein eindeutiger Bezeichner für den Benutzer (ist in der Regel dem Microsoft Entra-Benutzerprinzipalnamen zugeordnet)
  • meta: Schreibgeschützte, vom Dienstanbieter verwaltete Metadaten

Neben dem Benutzerschema core definiert der SCIM-Standard eine Benutzererweiterung enterprise mit einem Modell für die Erweiterung des Benutzerschemas, um die Anforderungen Ihrer Anwendung zu erfüllen.

Wenn für Ihre Anwendung beispielsweise sowohl die E-Mail-Adressen als auch die Vorgesetzten von Benutzer*innen benötigt werden, können Sie mit dem Schema core die E-Mail-Adressen und mit dem Schema enterprise die Vorgesetzten erfassen.

Gehen Sie zum Entwerfen Ihres Schemas wie folgt vor:

  1. Listen Sie die von Ihrer Anwendung benötigten Attribute auf, und kategorisieren Sie sie dann als Attribute, die für die Authentifizierung erforderlich sind (z. B. „loginName“ und „email“). Attribute sind für die Verwaltung des Benutzerlebenszyklus (z. B. Status/Aktiv) erforderlich, und alle anderen Attribute werden benötigt, damit die Anwendung funktioniert (z. B. Vorgesetzter, Tag).

  2. Überprüfen Sie, ob die Attribute bereits im Kernbenutzerschema oder im Unternehmensbenutzerschema definiert sind. Falls nicht, muss eine entsprechende Erweiterung des Benutzerschemas definiert werden. Siehe Beispiel für eine Erweiterung des Benutzers, um die Bereitstellung eines Benutzers tag zu ermöglichen.

  3. Ordnen Sie SCIM-Attribute den Benutzerattributen in Microsoft Entra ID zu. Wenn für eines der Attribute, die Sie in Ihrem SCIM-Endpunkt definiert haben, kein eindeutiges Gegenstück im Microsoft Entra-Benutzerschema vorhanden ist, leiten Sie den Mandantenadministrator an, das Schema zu erweitern, oder verwenden Sie ein Erweiterungsattribut, wie im Beispiel für die tags-Eigenschaft gezeigt.

Die folgende Tabelle enthält ein Beispiel für erforderliche Attribute:

Erforderliches App-Attribut/Beispiel Zugeordnetes SCIM-Attribut Zugeordnetes Microsoft Entra-Attribut
loginName userName userPrincipalName
firstName name.givenName givenName
lastName name.familyName surName
workMail emails[type eq "work"].value E-Mail
manager manager manager
tag urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag extensionAttribute1
status aktiv isSoftDeleted (berechneter Wert, wird für Benutzer nicht gespeichert)

Die folgende JSON-Nutzlast zeigt ein Beispiel für ein SCIM-Schema:

{
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
      "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User"],
     "userName":"bjensen@testuser.com",
     "id": "48af03ac28ad4fb88478",
     "externalId":"bjensen",
     "name":{
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
     "manager": "123456"
   },
     "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
     "tag": "701984",
   },
   "meta": {
     "resourceType": "User",
     "created": "2010-01-23T04:56:22Z",
     "lastModified": "2011-05-13T04:42:34Z",
     "version": "W\/\"3694e05e9dff591\"",
     "location":
 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"
   }
}   

Hinweis

Die JSON-Darstellung enthält neben den für die Anwendung erforderlichen Attributen auch die erforderlichen Attribute id, externalId und meta.

Die Unterscheidung zwischen /User und /Group ist hilfreich, um Standardbenutzerattribute in Microsoft Entra ID der SCIM-RFC zuzuordnen. Weitere Informationen finden Sie unter wie benutzerdefinierte Attribute zwischen Microsoft Entra ID und Ihrem SCIM-Endpunkt zugeordnet werden.

Die folgende Tabelle enthält ein Beispiel für Benutzerattribute:

Microsoft Entra-Benutzer urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
IsSoftDeleted aktiv
department urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
displayName displayName
employeeId urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
Facsimile-TelephoneNumber phoneNumbers[type eq "fax"].value
givenName name.givenName
jobTitle title
mail emails[type eq "work"].value
mailNickname externalId
manager urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
mobile phoneNumbers[type eq "mobile"].value
postalCode addresses[type eq "work"].postalCode
proxy-Addresses emails[type eq "other"].Value
physical-Delivery-OfficeName addresses[type eq "other"].Formatted
streetAddress addresses[type eq "work"].streetAddress
surname name.familyName
telephone-Number phoneNumbers[type eq "work"].value
user-PrincipalName userName

Die folgende Tabelle enthält ein Beispiel für Gruppenattribute:

Microsoft Entra Gruppe urn:ietf:params:scim:schemas:core:2.0:Group
displayName displayName
members members
objectId externalId

Hinweis

Es ist nicht erforderlich, sowohl Benutzer als auch Gruppen oder alle hier gezeigten Attribute zu unterstützen. Hierbei handelt es sich lediglich um eine Referenz, die zeigt, wie Attribute in Microsoft Entra ID häufig Eigenschaften im SCIM-Protokoll zugeordnet sind.

Im SCIM-RFC sind verschiedene Endpunkte definiert. Sie können mit dem Endpunkt /User beginnen und dann Erweiterungen vornehmen. In der folgenden Tabelle sind einige der SCIM-Endpunkte aufgeführt:

Endpunkt BESCHREIBUNG
/User Führt CRUD-Vorgänge für ein Benutzerobjekt aus.
/Group Führt CRUD-Vorgänge für ein Gruppenobjekt aus.
/Schemas Der Satz von unterstützten Attributen kann bei einzelnen Clients und Dienstanbietern unterschiedlich sein. Ein Dienstanbieter enthält möglicherweise name, title und emails, während ein anderer name, title und phoneNumbers verwendet. Der Endpunkt „/Schemas“ ermöglicht die Erkennung der unterstützten Attribute.
/Bulk Massenvorgänge ermöglichen das Ausführen von Vorgängen für eine große Sammlung von Ressourcenobjekten in einem einzigen Schritt (z. B. Aktualisieren der Mitgliedschaften für eine große Gruppe).
/ServiceProviderConfig Stellt Einzelheiten zu den unterstützten Features des SCIM-Standards bereit, z. B. die unterstützten Ressourcen und die Authentifizierungsmethode.
/ResourceTypes Definiert die Metadaten für jede Ressource

Hinweis

Verwenden Sie den Endpunkt /Schemas, wenn Sie benutzerdefinierte Attribute unterstützen möchten oder wenn sich Ihr Schema häufig ändert, da ein Client so automatisch das aktuelle Schema abrufen kann. Verwenden Sie den Endpunkt /Bulk, um Gruppen zu unterstützen.

Grundlegendes zur Microsoft Entra-SCIM-Implementierung

Die Microsoft Entra-Bereitstellungsdienste sind für die Unterstützung einer SCIM 2.0-Benutzerverwaltungs-API konzipiert.

Wichtig

Das Verhalten der Microsoft Entra-SCIM-Implementierung wurde zuletzt am 18. Dezember 2018 aktualisiert. Informationen zu den Änderungen finden Sie unter Compliance mit dem SCIM 2.0-Protokoll des Microsoft Entra-Benutzerbereitstellungsdiensts.

Im Rahmen der SCIM 2.0-Protokollspezifikation muss Ihre Anwendung die folgenden Anforderungen unterstützen:

Anforderung Referenzhinweise (SCIM-Protokoll)
Erstellen von Benutzern und optional auch Gruppen Abschnitt 3.3
Ändern von Benutzern oder Gruppen mit PATCH-Anforderungen Abschnitt 3.5.2. Durch die Unterstützung wird sichergestellt, dass Gruppen und Benutzer auf leistungsstarke Weise bereitgestellt werden.
Abrufen einer bekannten Ressource für einen zuvor erstellten Benutzer oder eine zuvor erstellte Gruppe Abschnitt 3.4.1
Abfragen von Benutzern oder Gruppen Abschnitt 3.4.2. Standardmäßig werden Benutzer mit ihrer id abgerufen und mit ihrer username und externalId abgefragt. Gruppen werden mit displayName abgefragt.
Filter excludedAttributes=members beim Abfragen der Gruppenressource Abschnitt 3.4.2.2
Unterstützen der Auflistung von Benutzern und der Paginierung Abschnitt 3.4.2.4.
Vorläufiges Löschen eines Benutzers (active=false) und Wiederherstellen des Benutzers (active=true) Das Benutzerobjekt sollte unabhängig vom Aktivitätsstatus des Benutzers in einer Anforderung zurückgegeben werden. Der Benutzer sollte nur dann nicht zurückgegeben werden, wenn er endgültig aus der Anwendung gelöscht wurde.
Unterstützen des/Schemas-Endpunkts Abschnitt 7 Der Endpunkt für die Schemaermittlung wird verwendet, um weitere Attribute zu ermitteln.
Akzeptiert ein einzelnes Bearertoken für die Authentifizierung und Autorisierung von Microsoft Entra ID für Ihre Anwendung.

Verwenden Sie bei der Implementierung eines SCIM-Endpunkts die allgemeinen Richtlinien, um die Kompatibilität mit Microsoft Entra ID zu gewährleisten:

General:

  • id ist eine erforderliche Eigenschaft für alle Ressourcen. Für jede Antwort, die eine Ressource zurückgibt, muss sichergestellt werden, dass jede Ressource diese Eigenschaft aufweist. Eine Ausnahme ist ListResponse mit 0 (null) Elementen.
  • Die gesendeten Werte sollten im gleichen Format gespeichert werden, in dem sie gesendet wurden. Ungültige Werte sollten mit einer aussagekräftigen Fehlermeldung zurückgewiesen werden. Zwischen Daten von Microsoft Entra ID und den in der SCIM-Anwendung gespeicherten Daten sollten keine Transformationen von Daten stattfinden. (Beispiel: Eine als 55555555555 gesendete Telefonnummer sollte nicht in dem Format +5 (555) 555-5555 gespeichert/zurückgegeben werden.)
  • Die Antwort von PATCH muss nicht die gesamte Ressource enthalten.
  • Unterscheiden Sie bei Strukturelementen in SCIM nicht zwischen Groß- und Kleinschreibung, insbesondere bei Vorgangswerten für PATCHop (gemäß Definition im Abschnitt 3.5.2). Von Microsoft Entra ID werden die Werte von op als Add (Hinzufügen), Replace (Ersetzen) und Remove (Entfernen) ausgegeben.
  • Von Microsoft Entra ID werden Anforderungen zum Abrufen eines zufälligen Benutzers und einer zufälligen Gruppe gesendet, um sicherzustellen, dass der Endpunkt und die Anmeldeinformationen gültig sind. Dies wird auch im Rahmen des Flows Verbindung testen durchgeführt.
  • HTTPS-Unterstützung auf Ihrem SCIM-Endpunkt
  • Benutzerdefinierte komplexe und mehrwertige Attribute werden unterstützt, aber Microsoft Entra ID verfügt nicht über viele komplexe Datenstrukturen, aus denen in diesen Fällen Daten gepullt werden können. Name/Wert-Attribute lassen sich leicht zuordnen, aber der Datenfluss zu komplexen Attributen mit drei oder mehr Unterattributen wird nicht unterstützt.
  • Die type-Unterattributwerte von mehrwertigen komplexen Attributen müssen eindeutig sein. Beispielsweise können nicht zwei verschiedene E-Mail-Adressen mit dem Untertyp „work“ verwendet werden.
  • Der Header für alle Antworten sollte den Inhaltstyp „anwendung/scim+json“ aufweisen

Das Abrufen von Ressourcen:

  • Eine Antwort auf eine Abfrage-/Filteranforderung muss immer eine ListResponse sein.
  • In Microsoft Entra werden nur die folgenden Operatoren verwendet: eq, and.
  • Das Attribut, nach dem die Ressourcen abgefragt werden können, muss als entsprechendes Attribut für die Anwendung festgelegt werden. Weitere Informationen finden Sie unter Anpassen von Attributzuordnungen für die Benutzerbereitstellung.

/Benutzer:

  • Das Attribut „entitlements“ wird nicht unterstützt.
  • Alle Attribute, die für die Eindeutigkeit des Benutzers berücksichtigt werden, müssen als Teil einer gefilterten Abfrage verwendet werden können. (Wenn z. B. die Eindeutigkeit des Benutzers sowohl für „userName“ als auch für „emails[type eq "work"]“ ausgewertet wird, muss eine GET-Anforderung für /Users mit einem Filter sowohl Abfragen vom Typ userName eq "user@contoso.com" als auch vom Typ emails[type eq "work"].value eq "user@contoso.com" zulassen.

/Gruppen:

  • Gruppen sind optional, werden jedoch nur unterstützt, wenn die SCIM-Implementierung Anforderungen vom Typ PATCH unterstützt.
  • Der Wert „displayName“ für Gruppen muss eindeutig sein, um den Abgleich zwischen Microsoft Entra ID und der SCIM-Anwendung zu ermöglichen. Diese Eindeutigkeit ist keine Voraussetzung für das SCIM-Protokoll, sondern eine Voraussetzung für die Integration eines SCIM-Endpunkts in Microsoft Entra ID.

/Schemas (Schema-Ermittlung):

  • Ein Beispiel für eine Anforderung/Antwort
  • Die Schemaermittlung wird für bestimmte Kataloganwendungen verwendet. Die Schemaermittlung ist die einzige Methode, um weitere Attribute zum Schema einer vorhandenen SCIM-Anwendung im Katalog hinzuzufügen. Die Schemaermittlung wird derzeit für benutzerdefinierte SCIM-Anwendungen ohne Katalog nicht unterstützt.
  • Wenn kein Wert vorhanden ist, senden Sie keine NULL-Werte.
  • Eigenschaftswerte sollten in Camel-Case-Schreibweise (z. B. „readWrite“) angegeben werden.
  • Muss eine Listen Antwort zurückgeben.
  • Der Microsoft Entra-Bereitstellungsdienst stellt die /schemas-Anforderung, wenn Sie die Bereitstellungskonfiguration speichern. Die Anforderung wird auch gestellt, wenn Sie die Seite „Bereitstellung bearbeiten“ öffnen. Andere ermittelte Attribute werden Kunden in den Attributzuordnungen unter der Liste der Zielattribute angezeigt. Die Schemaermittlung führt nur dazu, dass weitere Zielattribute hinzugefügt werden. Attribute werden nicht entfernt.

Benutzerbereitstellung und Aufheben der Bereitstellung

Die folgende Abbildung zeigt die Nachrichten, die von Microsoft Entra ID an einen SCIM-Endpunkt gesendet werden, um den Lebenszyklus eines Benutzers im Identitätsspeicher Ihrer Anwendung zu verwalten.

Diagram that shows the user deprovisioning sequence.

Gruppenbereitstellung und Aufheben der Bereitstellung

Die Gruppenbereitstellung und die Aufhebung einer Gruppenbereitstellung sind optional. In der folgenden Abbildung sind die Nachrichten dargestellt, die Microsoft Entra ID bei entsprechender Implementierung und Aktivierung an einen SCIM-Endpunkt sendet, um den Lebenszyklus einer Gruppe im Identitätsspeicher Ihrer Anwendung zu verwalten. Diese Nachrichten unterscheiden sich von den Nachrichten zu Benutzern auf zwei Arten:

  • Für Anforderungen zum Abrufen von Gruppen wird angegeben, dass das members-Attribut aus allen Ressourcen ausgeschlossen wird, die als Antwort auf die Anforderung bereitgestellt werden.
  • Bei Anforderungen für die Ermittlung, ob ein Referenzattribut einen bestimmten Wert hat, handelt es sich um Anforderungen zum members-Attribut.

Das folgende Diagramm zeigt die Abfolge einer Gruppenbereitstellung:

Diagram that shows the group deprovisioning sequence.

SCIM-Protokollanforderungen und -antworten

Dieser Artikel enthält SCIM-Beispielanforderungen, die vom Microsoft Entra-Bereitstellungsdienst ausgegeben werden, sowie erwartete Beispielantworten. Die besten Ergebnisse erzielen Sie, wenn Sie Ihre App so codieren, dass diese Anforderungen in diesem Format verarbeitet und die erwarteten Antworten ausgegeben werden.

Wichtig

Lesen Sie den Abschnitt Bereitstellungszyklen: Erster Zyklus und inkrementelle Zyklen unter Funktionsweise der Bereitstellung, um zu verstehen, wie und wann der Microsoft Entra-Benutzerbereitstellungsdienst die in diesem Beispiel beschriebenen Vorgänge ausgibt.

Vorgänge für Benutzer

Vorgänge für Gruppen

Schema Ermittlung

Vorgänge für Benutzer

  • Verwenden Sie die Attribute userName oder emails[type eq "work"], um Benutzer abzufragen.

Benutzer erstellen

Anforderung

POST /Users

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com"
    }],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName"
    },
    "roles": []
}
Antwort

HTTP/1.1 201 Created

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "48af03ac28ad4fb88478",
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Benutzer abrufen

Anforderung

GET /Users/5d48a0a8e9f04aa38008

Antwort (Benutzer gefunden)

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5d48a0a8e9f04aa38008",
    "externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_feed3ace-693c-4e5a-82e2-694be1b39934",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_22370c1a-9012-42b2-bf64-86099c2a1c22@testuser.com",
        "type": "work",
        "primary": true
    }]
}
Anforderung

GET /Users/5171a35d82074e068ce2

Antwort (Benutzer nicht gefunden. Das Detail ist nicht erforderlich, sondern nur der Status.)

HTTP/1.1 404 Nicht gefunden

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "404",
    "detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}

Benutzer nach Abfrage abrufen

Anforderung

GET /Users?filter=userName eq "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081"

Antwort

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "id": "2441309d85324e7793ae",
        "externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
        "meta": {
            "resourceType": "User",
            "created": "2018-03-27T19:59:26.000Z",
            "lastModified": "2018-03-27T19:59:26.000Z"
            
        },
        "userName": "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_91b67701-697b-46de-b864-bd0bbe4f99c1@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Benutzer nach Abfrage abrufen – keine Ergebnisse

Anforderung

GET /Users?filter=userName eq "non-existent user"

Antwort

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 0,
    "Resources": [],
    "startIndex": 1,
    "itemsPerPage": 20
}

Benutzer aktualisieren [mehrwertige Eigenschaften]

Anforderung

PATCH /Users/6764549bef60420686bc HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
            {
            "op": "Replace",
            "path": "emails[type eq \"work\"].value",
            "value": "updatedEmail@microsoft.com"
            },
            {
            "op": "Replace",
            "path": "name.familyName",
            "value": "updatedFamilyName"
            }
    ]
}
Antwort

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "6764549bef60420686bc",
    "externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_fbb9dda4-fcde-4f98-a68b-6c5599e17c27",
    "name": {
        "formatted": "givenName updatedFamilyName",
        "familyName": "updatedFamilyName",
        "givenName": "givenName"
    },
    "active": true,
    "emails": [{
        "value": "updatedEmail@microsoft.com",
        "type": "work",
        "primary": true
    }]
}

Benutzer aktualisieren [einwertige Eigenschaften]

Anforderung

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "userName",
        "value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
    }]
}
Antwort

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5171a35d82074e068ce2",
    "externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_49dc1090-aada-4657-8434-4995c25a00f7@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Benutzer deaktivieren

Anforderung

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "Operations": [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}
Antwort
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
    "userName": "deanruiz@testuser.com",
    "name": {
        "familyName": "Harris",
        "givenName": "Larry"
    },
    "active": false,
    "emails": [
        {
            "value": "gloversuzanne@testuser.com",
            "type": "work",
            "primary": true
        }
    ],
    "addresses": [
        {
            "country": "ML",
            "type": "work",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "Users",
        "location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
    }
}

Benutzer löschen

Anforderung

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

Antwort

HTTP/1.1 204 No Content

Vorgänge für Gruppen

  • Gruppen werden immer mit einer leeren Mitgliederliste erstellt.
  • Verwenden Sie das Attribut displayName, um Gruppen abzufragen.
  • Bei einer Aktualisierung der Gruppe mit PATCH-Anforderung sollte in der Antwort HTTP 204 No Content angezeigt werden. Es ist nicht ratsam, einen Text mit einer Liste aller Mitglieder zurückzugeben.
  • Die Rückgabe aller Mitglieder der Gruppe muss nicht unterstützt werden.

Erstellen einer Gruppe

Anforderung

POST /Groups HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "displayName": "displayName",
    "meta": {
        "resourceType": "Group"
    }
}
Antwort

HTTP/1.1 201 Created

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "927fa2c08dcb4a7fae9e",
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "displayName": "displayName",
    "members": []
}

Gruppe abrufen

Anforderung

GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1

Antwort

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "40734ae655284ad3abcc",
    "externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "displayName": "displayName",
}

Gruppe nach „displayName“ abrufen

Anforderung

GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1

Antwort

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
        "id": "8c601452cc934a9ebef9",
        "externalId": "0db508eb-91e2-46e4-809c-30dcbda0c685",
        "meta": {
            "resourceType": "Group",
            "created": "2018-03-27T22:02:32.000Z",
            "lastModified": "2018-03-27T22:02:32.000Z",
            
        },
        "displayName": "displayName",
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Gruppe aktualisieren [Nichtmitglieder-Attribute]

Anforderung

PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "displayName",
        "value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
    }]
}
Antwort

HTTP/1.1 204 No Content

Gruppe aktualisieren [Mitglieder hinzufügen]

Anforderung

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Add",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}
Antwort

HTTP/1.1 204 No Content

Gruppe aktualisieren [Mitglieder entfernen]

Anforderung

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Remove",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}
Antwort

HTTP/1.1 204 No Content

Gruppe löschen

Anforderung

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Antwort

HTTP/1.1 204 No Content

Schema-Ermittlung

Schema ermitteln

Anforderung

GET /Schemas

Antwort

HTTP/1.1 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "itemsPerPage": 50,
    "startIndex": 1,
    "totalResults": 3,
    "Resources": [
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:User",
    "name" : "User",
    "description" : "User Account",
    "attributes" : [
      {
        "name" : "userName",
        "type" : "string",
        "multiValued" : false,
        "description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value.  This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
        "required" : true,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "server"
      },                
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
    "name" : "Group",
    "description" : "Group",
    "attributes" : [
      {
        "name" : "displayName",
        "type" : "string",
        "multiValued" : false,
        "description" : "A human-readable name for the Group.
REQUIRED.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "name" : "EnterpriseUser",
    "description" : "Enterprise User",
    "attributes" : [
      {
        "name" : "employeeNumber",
        "type" : "string",
        "multiValued" : false,
        "description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    }
  }
]
}

Sicherheitsanforderungen

TLS-Protokollversionen

Die einzige zulässige Protokollversion ist TLS 1.2. Es ist keine andere SSL/TLS-Version zulässig.

  • Die Größe von RSA-Schlüsseln muss mindestens 2.048 Bit betragen.
  • ECC-Schlüssel müssen mindestens 256 Bit groß und mit einer genehmigten elliptischen Kurve erzeugt worden sein

Schlüssellängen

Alle Dienste müssen X.509-Zertifikate verwenden, die mit kryptografischen Schlüsseln ausreichender Länge erzeugt wurden. Das bedeutet:

Verschlüsselungssammlungen

Alle Dienste müssen so konfiguriert sein, dass sie die folgenden Verschlüsselungssammlungen in exakt der im Beispiel angegebenen Reihenfolge verwenden. Wenn Sie nur ein RSA-Zertifikat haben, sind die installierten ECDSA-Verschlüsselungssammlungen wirkungslos.

TLS 1.2-Verschlüsselungssammlungen (Minimum):

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

IP-Bereiche

Der Microsoft Entra-Bereitstellungsdienst wird derzeit unter den IP-Bereichen für Microsoft Entra-ID ausgeführt, wie hier aufgeführt. Sie können die unter dem Tag Microsoft Entra ID aufgeführten IP-Adressbereiche hinzufügen, um den Datenverkehr vom Microsoft Entra-Bereitstellungsdienst in Ihre Anwendung zuzulassen. Sie müssen die IP-Adressbereichsliste sorgfältig auf berechnete Adressen überprüfen. Eine Adresse wie 40.126.25.32 könnte in der IP-Adressbereichsliste als 40.126.0.0/18 dargestellt werden. Sie können die IP-Adressbereichsliste mithilfe der folgenden API auch programmgesteuert abrufen.

Microsoft Entra ID unterstützt auch eine Agent-basierte Lösung, um eine Konnektivität mit Anwendungen in privaten Netzwerken bereitzustellen (lokal, in Azure gehostet, in AWS gehostet usw.). Kunden können einen einfachen Agent bereitstellen, der die Konnektivität mit Microsoft Entra ID bietet, ohne eingehende Ports auf einem Server in ihrem privaten Netzwerk zu öffnen. Hiererhalten Sie weitere Informationen.

Erstellen eines SCIM-Endpunkts

Nachdem Sie das Schema entworfen und die Microsoft Entra-SCIM-Implementierung verstanden haben, können Sie mit der Entwicklung Ihres SCIM-Endpunkts beginnen. Anstatt bei Null anzufangen und die Implementierung komplett selbst zu erstellen, können Sie auf zahlreiche Open-Source-SCIM-Bibliotheken zurückgreifen, die von der SCIM-Community veröffentlicht werden.

Eine Anleitung zum Erstellen eines SCIM-Endpunkts, einschließlich Beispielen, finden Sie unter Tutorial: Entwickeln eines SCIM-Beispielendpunkts.

Das Open-Source-Referenzcodebeispiel für .NET Core, das vom Microsoft Entra-Bereitstellungsteam veröffentlicht wird, ist eine solche Ressource, die Ihnen einen schnellen Einstieg in die Entwicklung ermöglicht. Erstellen Sie einen SCIM-Endpunkt und testen Sie ihn. Verwenden Sie die Sammlung von Postman-Tests, die als Teil des Referenzcodes bereitgestellt werden, oder führen Sie die aufgeführten Beispielanforderungen/-antworten aus.

Hinweis

Der Referenzcode soll Ihnen den Einstieg in das Erstellen des SCIM-Endpunkts erleichtern und wird in unveränderter Form zur Verfügung gestellt. Beiträge aus der Community sind stets willkommen, um den Code weiter auszubauen und zu pflegen.

Die Lösung besteht aus zwei Projekten: Microsoft.SCIM und Microsoft.SCIM.WebHostsample.

Das Projekt Microsoft.SCIM ist eine Bibliothek und definiert die Komponenten des Webdiensts, welcher der SCIM-Spezifikation entspricht. Es deklariert die Schnittstelle Microsoft.SCIM.IProvider. Anforderungen werden in Aufrufe der Methoden des Anbieters übersetzt, die für den Betrieb in einem Identitätsspeicher programmiert sind.

Breakdown: A request translated into calls to the provider's methods

Das Projekt Microsoft.SCIM.WebHostSample ist eine ASP.NET Core-Webanwendung, die auf der leeren Vorlage basiert. Der Beispielcode kann eigenständig bereitgestellt werden und in Containern oder in Internetinformationsdiensten gehostet werden. Implementiert wird auch die Schnittstelle Microsoft.SCIM.IProvider, die Klassen im Arbeitsspeicher als Beispielidentitätsspeicher beibehält.

public class Startup
{
    ...
    public IMonitor MonitoringBehavior { get; set; }
    public IProvider ProviderBehavior { get; set; }

    public Startup(IWebHostEnvironment env, IConfiguration configuration)
    {
        ...
        this.MonitoringBehavior = new ConsoleMonitor();
        this.ProviderBehavior = new InMemoryProvider();
    }
    ...

Erstellen eines benutzerdefinierten SCIM-Endpunkts

Der SCIM-Endpunkt muss über eine HTTP-Adresse und über ein Serverauthentifizierungszertifikat mit einer der folgenden Stammzertifizierungsstellen verfügen:

  • CNNIC
  • Comodo
  • CyberTrust
  • DigiCert
  • GeoTrust
  • GlobalSign
  • Go Daddy
  • VeriSign
  • WoSign
  • DST Root CA X3

Das .NET Core SDK enthält ein HTTPS-Entwicklungszertifikat, das bei der Entwicklung verwendet wird. Das Zertifikat wird im Rahmen der ersten Ausführung installiert. Je nach Ausführung der ASP.NET Core-Webanwendung lauscht es an einem anderen Port:

  • Microsoft.SCIM.WebHostSample: https://localhost:5001
  • IIS Express: https://localhost:44359

Weitere Informationen zu HTTPS in ASP.NET Core erhalten Sie über folgenden Link: Erzwingen von HTTPS in ASP.NET Core

Behandeln der Endpunktauthentifizierung

Anforderungen aus dem Microsoft Entra-Bereitstellungsdienst enthalten ein OAuth 2.0-Bearertoken. Ein Autorisierungsserver stellt das Bearertoken aus. Microsoft Entra ID ist ein Beispiel eines vertrauenswürdigen Autorisierungsservers. Konfigurieren Sie den Microsoft Entra-Bereitstellungsdienst so, dass er eines der folgenden Token verwendet:

  • Langlebiges Bearertoken Wenn der SCIM-Endpunkt ein OAuth-Bearertoken benötigt, das von einem anderen Aussteller als Microsoft Entra ID stammt, kopieren Sie das erforderliche OAuth-Bearertoken in das optionale Feld Geheimes Token. In einer Entwicklungsumgebung können Sie das Testtoken vom /scim/token-Endpunkt verwenden. Testtoken sollten nicht in Produktionsumgebungen verwendet werden.

  • Microsoft Entra Bearertoken. Wird das Feld Geheimes Token leer gelassen, fügt Microsoft Entra ID in jede Anforderung ein von Microsoft Entra ID ausgestelltes OAuth-Bearertoken ein. Apps, die Microsoft Entra ID als Identitätsanbieter verwenden, können dieses Microsoft Entra ID-ausgestelltes Token überprüfen.

    • Die Anwendung, die Anforderungen empfängt, muss den Tokenaussteller als Microsoft Entra ID für einen erwarteten Microsoft Entra-Mandanten überprüfen.
    • Ein iss-Anspruch identifiziert den Aussteller des Tokens. Beispiel: "iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/". In diesem Beispiel wird die Basisadresse des Anspruchswerts (https://sts.windows.net) zum Identifizieren von Microsoft Entra ID als Aussteller verwendet, während das Segment mit der relativen Adresse (12345678-0000-0000-0000-000000000000) ein eindeutiger Bezeichner des Microsoft Entra-Mandanten ist, für den das Token ausgestellt wurde.
    • Die Zielgruppe für ein Token ist die Anwendungs-ID für die Anwendung im Katalog. Die in einem einzelnen Mandanten registrierten Anwendungen empfangen den gleichen iss-Anspruch mit SCIM-Anforderungen. Die Anwendung-ID für alle benutzerdefinierten Apps lautet 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Das von der Microsoft Entra ID generierte Token sollte nur für Tests verwendet werden. Es darf nicht in Produktionsumgebungen verwendet werden.

Im Beispielcode werden Anforderungen mit dem Microsoft.AspNetCore.Authentication.JwtBearer-Paket authentifiziert. Mit dem folgenden Code wird erzwungen, dass Anforderungen an Endpunkte des Diensts mit dem von Microsoft Entra ID für einen bestimmten Mandanten ausgegebenen Bearertoken authentifiziert werden:

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        ...
    }
    else
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
            .AddJwtBearer(options =>
            {
                options.Authority = " https://sts.windows.net/12345678-0000-0000-0000-000000000000/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

public void Configure(IApplicationBuilder app)
{
    ...
    app.UseAuthentication();
    app.UseAuthorization();
    ...
}

Ein Bearertoken ist auch zur Verwendung der bereitgestellten Postman-Tests und zum lokalen Debuggen mithilfe von „localhost“ erforderlich. Für den Beispielcode werden ASP.NET Core-Umgebungen verwendet, damit im Entwicklungsstadium die Authentifizierungsoptionen geändert und selbstsignierte Token verwendet werden können.

Weitere Informationen zu mehreren Umgebungen in ASP.NET Core finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.

Der folgende Code erzwingt, dass Anforderungen an Endpunkte des Diensts mit einem Bearertoken authentifiziert werden, das mit einem benutzerdefinierten Schlüssel signiert wurde:

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters =
                new TokenValidationParameters
                {
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    ValidateLifetime = false,
                    ValidateIssuerSigningKey = false,
                    ValidIssuer = "Microsoft.Security.Bearer",
                    ValidAudience = "Microsoft.Security.Bearer",
                    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"))
                };
        });
    }
...

Senden Sie eine GET-Anforderung an den Tokencontroller, um ein gültiges Bearertoken abzurufen. Die Methode GenerateJSONWebToken ist für die Erstellung eines Tokens verantwortlich, das den für die Entwicklung konfigurierten Parametern entspricht:

private string GenerateJSONWebToken()
{
    // Create token key
    SymmetricSecurityKey securityKey =
        new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"));
    SigningCredentials credentials =
        new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

    // Set token expiration
    DateTime startTime = DateTime.UtcNow;
    DateTime expiryTime = startTime.AddMinutes(120);

    // Generate the token
    JwtSecurityToken token =
        new JwtSecurityToken(
            "Microsoft.Security.Bearer",
            "Microsoft.Security.Bearer",
            null,
            notBefore: startTime,
            expires: expiryTime,
            signingCredentials: credentials);

    string result = new JwtSecurityTokenHandler().WriteToken(token);
    return result;
}

Vorgehensweise beim Bereitstellen und beim Aufheben der Bereitstellung von Benutzern

Beispiel 1: Abfragen des Diensts nach einem passenden Benutzer

Microsoft Entra ID fragt den Dienst nach einem Benutzer mit einem externalId-Attributwert ab, der mit dem mailNickname-Attributwert eines Benutzers in Microsoft Entra ID übereinstimmt. Die Abfrage wird als Hypertext Transfer-Protokoll-Anforderung (HTTP-Anforderung) wie in diesem Beispiel ausgedrückt, wobei „jyoung“ ein Beispiel für ein mailNickname-Attribut eines Benutzers in Microsoft Entra ID ist.

Hinweis

Dies ist nur ein Beispiel. Nicht alle Benutzer verfügen über ein mailNickname-Attribut, und der Wert eines Benutzers ist möglicherweise im Verzeichnis nicht eindeutig. Das für den Abgleich verwendete Attribut (in diesem Fall externalId) kann auch in den Microsoft Entra-Attributzuordnungen konfiguriert werden.

GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
 Authorization: Bearer ...

Im Beispielcode wird die Anforderung in einen Aufruf der QueryAsync-Methode des Dienstanbieters übersetzt. Dies ist die Signatur dieser Methode:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  
// Microsoft.SCIM.IQueryParameters is defined in 
// Microsoft.SCIM.Protocol.  

Task<Resource[]> QueryAsync(IRequest<IQueryParameters> request);

In der Beispielabfrage für einen Benutzer mit einem bestimmten Wert für das Attribut externalId lauten die Werte der Argumente, die an die QueryAsync-Methode übergeben werden, wie folgt:

  • parameters.AlternateFilters.Count: 1
  • parameters.AlternateFilters.ElementAt(0).AttributePath: "externalId"
  • parameters.AlternateFilters.ElementAt(0).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(0).ComparisonValue: "jyoung"

Beispiel 2: Bereitstellen eines Benutzers

Wenn in der Antwort auf eine an den SCIM-Endpunkt gesendete Abfrage für einen Benutzer mit einem externalId-Attributwert, der dem mailNickname-Attributwert eines Benutzers entspricht, keine Benutzer zurückgegeben werden, wird von Microsoft Entra ID die Bereitstellung eines Benutzers angefordert, der dem Benutzer in Microsoft Entra ID entspricht. Dies ist ein Beispiel für eine Anforderung dieser Art:

POST https://.../scim/Users HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
   "schemas":
   [
     "urn:ietf:params:scim:schemas:core:2.0:User",
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0User"],
   "externalId":"jyoung",
   "userName":"jyoung@testuser.com",
   "active":true,
   "addresses":null,
   "displayName":"Joy Young",
   "emails": [
     {
       "type":"work",
       "value":"jyoung@Contoso.com",
       "primary":true}],
   "meta": {
     "resourceType":"User"},
    "name":{
     "familyName":"Young",
     "givenName":"Joy"},
   "phoneNumbers":null,
   "preferredLanguage":null,
   "title":null,
   "department":null,
   "manager":null}

Im Beispielcode wird die Anforderung in einen Aufruf der CreateAsync-Methode des Dienstanbieters übersetzt. Dies ist die Signatur dieser Methode:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  

Task<Resource> CreateAsync(IRequest<Resource> request);

In der Anforderung einer Benutzerbereitstellung entspricht der Wert des Ressourcenarguments einer Instanz der Klasse Microsoft.SCIM.Core2EnterpriseUser. Diese Klasse wird in der Microsoft.SCIM.Schemas-Bibliothek definiert. Wenn die Anforderung zum Bereitstellen des Benutzers erfolgreich ist, wird von der Implementierung der Methode erwartet, dass eine Instanz der Klasse Microsoft.SCIM.Core2EnterpriseUser zurückgegeben wird. Der Wert der Identifier-Eigenschaft ist auf den eindeutigen Bezeichner des neu bereitgestellten Benutzers festgelegt.

Beispiel 3: Abfragen des aktuellen Status eines Benutzers

Microsoft Entra ID fordert den aktuellen Zustand des angegebenen Benutzers vom Dienst mit einer Anforderung an, z. B.:

GET ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

Im Beispielcode wird die Anforderung in einen Aufruf der RetrieveAsync-Methode des Dienstanbieters übersetzt. Dies ist die Signatur dieser Methode:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource and 
// Microsoft.SCIM.IResourceRetrievalParameters 
// are defined in Microsoft.SCIM.Schemas 

Task<Resource> RetrieveAsync(IRequest<IResourceRetrievalParameters> request);

Im Beispiel für eine Anforderung zum Abrufen des aktuellen Status eines Benutzers lauten die Werte der Eigenschaften des Objekts, das als Wert des Parameters-Arguments angegeben wird, wie folgt:

  • Bezeichner: „54D382A4-2050-4C03-94D1-E769F1D15682“
  • SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Beispiel 4: Abfragen des Werts eines zu aktualisierenden Referenzattributs

Microsoft Entra ID überprüft vor der Aktualisierung den aktuellen Attributwert im Identitätsspeicher. Allerdings wird zuerst nur das manager-Attribut für Benutzer*innen überprüft. Dies ist ein Beispiel für eine Anforderung, mit der ermittelt wird, ob das manager-Attribut eines Benutzerobjekts derzeit über einen bestimmten Wert verfügt: Im Beispielcode wird die Anforderung in einen Aufruf der QueryAsync-Methode des Dienstanbieters übersetzt. Der Wert der Eigenschaften des Objekts, das als Wert des parameters-Arguments angegeben wird, lautet wie folgt:

  • parameters.AlternateFilters.Count: 2
  • parameters.AlternateFilters.ElementAt(x).AttributePath: „ID“
  • parameters.AlternateFilters.ElementAt(x).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(x).ComparisonValue: „54D382A4-2050-4C03-94D1-E769F1D15682“
  • parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
  • parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(y).ComparisonValue: „2819c223-7f76-453a-919d-413861904646“
  • parameters.RequestedAttributePaths.ElementAt(0): „ID“
  • parameters.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Der Wert des Index x kann 0 und der Wert des Index y kann 1 sein. Oder der Wert von x kann 1 und der Wert von y kann 0 sein. Es hängt von der Reihenfolge der Ausdrücke des Filterabfrageparameters ab.

Beispiel 5: Anforderung von Microsoft Entra ID an einen SCIM-Endpunkt zur Aktualisierung eines Benutzers

Hier ist ein Beispiel für eine Anforderung von Microsoft Entra ID an einen SCIM-Endpunkt zur Aktualisierung eines Benutzers:

PATCH ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
    "schemas": 
    [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":
    [
      {
        "op":"Add",
        "path":"manager",
        "value":
          [
            {
              "$ref":"http://.../scim/Users/2819c223-7f76-453a-919d-413861904646",
              "value":"2819c223-7f76-453a-919d-413861904646"}]}]}

Im Beispielcode wird die Anforderung in einen Aufruf der UpdateAsync-Methode des Dienstanbieters übersetzt. Dies ist die Signatur dieser Methode:

// System.Threading.Tasks.Tasks and 
// System.Collections.Generic.IReadOnlyCollection<T>  // are defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.IPatch, 
// is defined in Microsoft.SCIM.Protocol. 

Task UpdateAsync(IRequest<IPatch> request);

Im Beispiel für eine Anforderung zum Aktualisieren eines Benutzers verfügt das Objekt, das als Wert des Patch-Arguments angegeben wird, über diese Eigenschaftswerte:

Argument Wert
ResourceIdentifier.Identifier „54D382A4-2050-4C03-94D1-E769F1D15682“
ResourceIdentifier.SchemaIdentifier urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
(PatchRequest as PatchRequest2).Operations.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName OperationName.Add
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath Manager
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference http://.../scim/Users/2819c223-7f76-453a-919d-413861904646
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 2819c223-7f76-453a-919d-413861904646

Beispiel 6: Aufheben der Bereitstellung eines Benutzers

Um die Bereitstellung für einen Benutzer aus einem Identitätsspeicher mit vorgelagertem SCIM-Endpunkt aufzuheben, sendet Microsoft Entra ID eine Anforderung der folgenden Art:

DELETE ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

Im Beispielcode wird die Anforderung in einen Aufruf der DeleteAsync-Methode des Dienstanbieters übersetzt. Dies ist die Signatur dieser Methode:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.IResourceIdentifier, 
// is defined in Microsoft.SCIM.Protocol. 

Task DeleteAsync(IRequest<IResourceIdentifier> request);

Im Beispiel für eine Anforderung zum Aufheben der Bereitstellung eines Benutzers verfügt das Objekt, das als Wert des resourceIdentifier-Arguments angegeben wird, über diese Eigenschaftswerte:

  • ResourceIdentifier.Identifier: „54D382A4-2050-4C03-94D1-E769F1D15682“
  • ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Integrieren Ihres SCIM-Endpunkts in den Microsoft Entra-Bereitstellungsdienst

Microsoft Entra ID kann für das automatische Bereitstellen von zugewiesenen Benutzern und Gruppen für Anwendungen konfiguriert werden, die ein bestimmtes Profil des SCIM 2.0-Protokolls implementieren. Die Einzelheiten des Profils sind im Abschnitt Verstehen der Microsoft Entra-SCIM-Implementierung dokumentiert.

Überprüfen Sie beim Anbieter Ihrer Anwendung oder in der Dokumentation zu Ihrer Anwendung, ob diese Anforderungen voll erfüllt werden.

Wichtig

Die Microsoft Entra-SCIM-Implementierung basiert auf dem Microsoft Entra-Benutzerbereitstellungsdienst, der auf die ständige Synchronisierung der Benutzer zwischen Microsoft Entra ID und der Zielanwendung ausgelegt ist, und implementiert eine ganz bestimmte Reihe von Standardvorgängen. Es ist wichtig, diese Verhaltensweisen zu verstehen, um das Verhalten des Microsoft Entra-Bereitstellungsdiensts nachvollziehen zu können. Weitere Informationen finden Sie in Vorgänge während der Bereitstellung: Startzyklus und Inkrementell in Funktionsweise der Bereitstellung.

Erste Schritte

Tipp

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

Anwendungen, die das SCIM-Profil wie in diesem Artikel beschrieben erfüllen, können über das Feature „Nicht-Kataloganwendung“ im Microsoft Entra-Anwendungskatalog mit Microsoft Entra ID verbunden werden. Nach der Verbindung führt Microsoft Entra ID einen Synchronisierungsprozess aus. Der Prozess wird alle 40 Minuten ausgeführt. Bei dem Prozess wird der SCIM-Endpunkt der Anwendung auf zugewiesene Benutzer*innen und Gruppen abgefragt. Entsprechend den Details der Zuweisung werden Benutzer*innen und Gruppen dann erstellt oder geändert.

So verbinden Sie eine Anwendung, die SCIM unterstützt:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsadministrator an.

  2. Browsen Sie zu Identität>Anwendungen>Unternehmensanwendungen.

  3. Eine Liste mit allen konfigurierten Apps wird angezeigt, einschließlich Apps, die aus dem Katalog hinzugefügt wurden.

  4. Wählen Sie + Neue Anwendung>+ Eigene Anwendung erstellen aus.

  5. Geben Sie einen Namen für Ihre Anwendung ein, und wählen Sie die Option Beliebige andere, nicht im Katalog zu findende Anwendung integrieren und dann Hinzufügen aus, um ein App-Objekt zu erstellen. Die neue App wird der Liste mit den Unternehmensanwendungen hinzugefügt und mit dem App-Verwaltungsbildschirm geöffnet.

    Der folgende Screenshot zeigt den Microsoft Entra-Anwendungskatalog:

    Screenshot shows the Microsoft Entra application gallery.

  6. Wählen Sie auf dem App-Verwaltungsbildschirm im linken Bereich die Option Bereitstellung.

  7. Wählen Sie im Menü Bereitstellungsmodus die Option Automatisch aus.

    Der folgende Screenshot zeigt das Konfigurieren von Bereitstellungseinstellungen im Microsoft Entra Admin Center:

    Screenshot of app provisioning page in the Microsoft Entra admin center.

  8. Geben Sie im Feld Mandanten-URL die URL des SCIM-Endpunkts der Anwendung ein. Beispiel: https://api.contoso.com/scim/

  9. Wenn der SCIM-Endpunkt ein OAuth-Bearertoken benötigt, das von einem anderen Aussteller als Microsoft Entra ID stammt, kopieren Sie das erforderliche OAuth-Bearertoken in das optionale Feld Geheimes Token. Wird dieses Feld leer gelassen, fügt Microsoft Entra ID in jede Anforderung ein von Microsoft Entra ID ausgestelltes OAuth-Bearertoken ein. Apps, die Microsoft Entra ID als Identitätsanbieter verwenden, können dieses Microsoft Entra ID-ausgestelltes Token überprüfen.

    Hinweis

    Es wird nicht empfohlen, dieses Feld leer zu lassen und sich auf ein von Microsoft Entra ID generiertes Token zu verlassen. Diese Option steht in erster Linie zu Testzwecken zur Verfügung.

  10. Wählen Sie die Option Verbindung testen aus, damit Microsoft Entra ID versucht, eine Verbindung mit dem SCIM-Endpunkt herzustellen. Wenn der Versuch nicht erfolgreich ist, werden Fehlerinformationen angezeigt.

    Hinweis

    Die Option Verbindung testen fragt den SCIM-Endpunkt nach einem Benutzer ab, der nicht vorhanden ist, und verwendet dabei einen zufälligen global eindeutigen Bezeichner (Globally Unique Identifier, GUID) als entsprechende Eigenschaft, die in der Microsoft Entra-Konfiguration ausgewählt wurde. Die erwartete richtige Antwort ist „HTTP 200 OK“ mit einer leeren SCIM ListResponse-Meldung.

  11. Wählen Sie bei einer erfolgreichen Verbindungsherstellung mit der Anwendung die Option Speichern, um die Administratoranmeldeinformationen zu speichern.

  12. Im Abschnitt Zuordnungen stehen zwei Sätze von Attributzuordnungen zur Verfügung: eine für Benutzerobjekte und eine für Gruppenobjekte. Wählen Sie beide nacheinander aus, um die Attribute zu überprüfen, die von Microsoft Entra ID mit Ihrer App synchronisiert werden. Beachten Sie, dass die als übereinstimmende Eigenschaften ausgewählten Attribute für den Abgleich der Benutzer und Gruppen in Ihrer App für Updatevorgänge verwendet werden. Wählen Sie Speichern aus, um Ihre Änderungen zu committen.

    Hinweis

    Sie können die Synchronisierung von Gruppenobjekten optional deaktivieren. Deaktivieren Sie dazu die Zuordnung „Gruppen“.

  13. Im Feld Bereich unter Einstellungen wird festgelegt, welche Benutzer und Gruppen synchronisiert werden. Wählen Sie Nur zugewiesene Benutzer und Gruppen synchronisieren (empfohlen) aus, damit nur Benutzer und Gruppen synchronisiert werden, die auf der Registerkarte Benutzer und Gruppen zugewiesen sind.

  14. Legen Sie den Bereitstellungsstatus nach Abschluss der Konfiguration auf Ein fest.

  15. Wählen Sie Speichern, um den Microsoft Entra-Bereitstellungsdienst zu starten.

  16. Wenn nur zugewiesene Benutzer und Gruppen synchronisiert werden (empfohlen), wählen Sie die Registerkarte Benutzer und Gruppen aus. Weisen Sie anschließend die Benutzer bzw. Gruppen zu, die synchronisiert werden sollen.

Nachdem der erste Zyklus gestartet wurde, können Sie im linken Bereich die Option Bereitstellungsprotokolle auswählen, um den Fortschritt zu überwachen. Hier werden alle Aktionen angezeigt, die vom Bereitstellungsdienst für Ihre App durchgeführt werden. Weitere Informationen zum Lesen der Microsoft Entra-Bereitstellungsprotokolle finden Sie unter Meldung zur automatischen Bereitstellung von Konten für Benutzer*innen.

Hinweis

Der erste Zyklus dauert länger als spätere Synchronisierungen, die ungefähr alle 40 Minuten erfolgen, solange der Dienst ausgeführt wird.

Wenn Sie eine Anwendung erstellen, die von mehreren Mandanten verwendet wird, stellen Sie sie im Microsoft Entra-Anwendungskatalog zur Verfügung. Dies erleichtert Organisationen das Auffinden der Anwendung und das Konfigurieren der Bereitstellung. Das Veröffentlichen Ihrer App im Microsoft Entra-Katalog und das Verfügbarmachen der Bereitstellung für andere ist einfach. Die entsprechenden Schritte sind hier angegeben. Microsoft arbeitet mit Ihnen zusammen, um Ihre Anwendung in den Katalog zu integrieren, Ihren Endpunkt zu testen und die Onboarding-Dokumentation für Kunden freizugeben.

Verwenden Sie die Prüfliste, um ein schnelles Onboarding Ihrer Anwendung sowie eine reibungslose Bereitstellung für Kunden zu gewährleisten. Die Informationen werden beim Onboarding für den Katalog von Ihnen erfasst.

  • Unterstützung eines SCIM 2.0-Benutzer- und Gruppenendpunkts (nur einer ist erforderlich, aber beide werden empfohlen)
  • Unterstützung von mindestens 25 Anforderungen pro Sekunde und Mandant, um sicherzustellen, dass Benutzer und Gruppen ohne Verzögerung bereitgestellt werden bzw. deren Bereitstellung aufgehoben wird (erforderlich)
  • Einrichtung eines Kontakts für technische und supportbezogene Fragen, um Kunden nach dem Katalogonboarding zu unterstützen (erforderlich)
  • 3 nicht ablaufende Testanmeldeinformationen für Ihre Anwendung (erforderlich)
  • Unterstützung der OAuth-Autorisierungscodegenehmigung oder eines langlebigen Tokens gemäß der Beschreibung im Beispiel (erforderlich)
  • OIDC-Apps müssen mindestens eine Rolle (benutzerdefiniert oder Standard) definiert haben.
  • Einrichtung einer Anlaufstelle für technische und supportbezogene Fragen, um Kunden nach dem Katalogonboarding zu unterstützen (erforderlich)
  • Unterstützung der Schemaerkennung (erforderlich)
  • Unterstützung der Aktualisierung mehrerer Gruppenmitgliedschaften mit einem einzelnen PATCH-Vorgang
  • Öffentliche Dokumentation Ihres SCIM-Endpunkts

Die SCIM-Spezifikation definiert kein SCIM-spezifisches Schema für die Authentifizierung und Autorisierung und basiert auf bestehenden Branchenstandards.

Autorisierungsmethode Vorteile Nachteile Unterstützung
Benutzername und Kennwort (von Microsoft Entra ID nicht empfohlen oder unterstützt) Einfache Implementierung Unsicher – Ihr KeNNwort ist unwichtig Diese Unterstützung gibt es nicht für neue katalogisierte oder nicht katalogisierte Apps.
Langlebiges Bearertoken Bei langlebigen Token muss kein Benutzer anwesend sein. Administratoren können sie beim Einrichten der Bereitstellung leicht verwenden. Langlebige Token können nur schwer mit einem Administrator geteilt werden, ohne unsichere Methoden wie E-Mail zu verwenden. Unterstützt für Katalog- und Nicht-Katalog-Apps.
OAuth-Autorisierungscodegenehmigung Zugriffstoken haben eine kürzere Lebensdauer als Kennwörter und verfügen über einen automatischen Aktualisierungsmechanismus, den langlebige Bearertoken nicht haben. Bei der ersten Autorisierung muss ein echter Benutzer anwesend sein, was einen gewissen Grad an Verantwortlichkeit bedeutet. Ein Benutzer muss anwesend sein. Wenn der*die Benutzer*in das Unternehmen verlässt, wird das Token ungültig, und die Autorisierung muss erneut erfolgen. Wird nur für Katalog-Apps unterstützt. Sie können über die Benutzeroberfläche jedoch ein Zugriffstoken als geheimes Token für kurzfristige Testzwecke bereitstellen. An der Unterstützung für die Autorisierung über OAuth-Code für nicht im Katalog enthaltene Anwendungen wird noch gearbeitet – zusätzlich zur Unterstützung für konfigurierbare Authentifizierungs-/Token-URLs in der Katalog-App.
Genehmigung von OAuth-Clientanmeldeinformationen Zugriffstoken haben eine kürzere Lebensdauer als Kennwörter und verfügen über einen automatischen Aktualisierungsmechanismus, den langlebige Bearertoken nicht haben. Sowohl die Autorisierungscodegenehmigung als auch die Genehmigung von Clientanmeldeinformationen gehören zum gleichen Typ Zugriffstoken. Ein Wechsel zwischen diesen beiden Methoden ist daher für die API transparent. Die Bereitstellung kann automatisiert werden. Neue Token können ohne Benutzerinteraktion und im Hintergrund angefordert werden. Wird nur für Katalog-Apps unterstützt. Sie können über die Benutzeroberfläche jedoch ein Zugriffstoken als geheimes Token für kurzfristige Testzwecke bereitstellen. Unterstützung für Zuweisung von OAuth-Client-Anmeldeinformationen auf Nicht-Katalog ist in unserem Backlog.

Hinweis

Es wird nicht empfohlen, das Tokenfeld auf der Benutzeroberfläche der benutzerdefinierten App zur Konfiguration der Microsoft Entra-Bereitstellung leer zu lassen. Das generierte Token steht in erster Linie zu Testzwecken zur Verfügung.

Ablauf der OAuth-Codegenehmigung

Vom Bereitstellungsdienst wird die Autorisierungscodegenehmigung unterstützt. Nachdem Sie Ihre Anforderung zur Veröffentlichung Ihrer App im Katalog übermittelt haben, setzt sich unser Team mit Ihnen in Verbindung, um die folgenden Informationen zu erfassen:

  • Autorisierungs-URL: Eine URL des Clients, um die Autorisierung des Ressourcenbesitzers über die Umleitung des Benutzer-Agents zu erhalten. Der Benutzer wird zu dieser URL umgeleitet, um den Zugriff zu autorisieren.

  • URL für den Tokenaustausch: Eine URL des Clients, um eine Autorisierungsgenehmigung für ein Zugriffstoken auszutauschen (üblicherweise mit Clientauthentifizierung).

  • Client-ID: Der Autorisierungsserver stellt dem registrierten Client eine Client-ID aus. Dabei handelt es sich um eine eindeutige Zeichenfolge, die die vom Client bereitgestellten Registrierungsinformationen darstellt. Die Client-ID ist kein Geheimnis. Sie wird dem Ressourcenbesitzer verfügbar gemacht und darf nicht allein für die Clientauthentifizierung verwendet werden.

  • Geheimer Clientschlüssel: Ein vom Autorisierungsserver generiertes Geheimnis. Hierbei muss es sich um einen eindeutigen Wert handeln, der nur dem Autorisierungsserver bekannt ist.

Hinweis

Die Autorisierungs-URL und die URL für den Tokenaustausch können derzeit nicht für einzelne Mandanten konfiguriert werden.

Hinweis

OAuth v1 wird aufgrund der Offenlegung des geheimen Clientschlüssels nicht unterstützt. OAuth v2 dagegen wird unterstützt.

Es wird empfohlen, ist aber nicht erforderlich, dass Sie mehrere Geheimnisse unterstützen, um eine einfache Verlängerung ohne Downtime zu ermöglichen.

Einrichten des Ablaufs der OAuth-Codegenehmigung

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsadministrator an.

  2. Navigieren Sie zu Identität>sanwendungen>Unternehmensanwendungen>Anwendungsbereitstellung,> und wählen Sie Autorisieren aus.

  3. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsadministrator an.

  4. Browsen Sie zu Identität>Anwendungen>Unternehmensanwendungen.

  5. Wählen Sie Ihre Anwendung aus, und navigieren Sie zu Bereitstellung.

  6. Wählen Sie Autorisieren.

    1. Benutzer*innen werden zur Autorisierungs-URL (Anmeldeseite für die Drittanbieter-App) weitergeleitet.

    2. Der Administrator stellt Anmeldeinformationen für die Drittanbieteranwendung bereit.

    3. Die Drittanbieter-App leitet die Benutzer*innen zurück und stellt den Autorisierungscode bereit.

    4. Der Bereitstellungsdienst ruft die Token-URL auf und stellt den Autorisierungscode bereit. Die Drittanbieteranwendung reagiert mit dem Zugriffstoken, dem Aktualisierungstoken und einem Ablaufdatum.

  7. Wenn der Bereitstellungszyklus beginnt, überprüft der Dienst, ob das aktuelle Zugriffstoken gültig ist und tauscht es bei Bedarf gegen ein neues aus. Das Zugriffstoken wird in jeder für die App veröffentlichten Anforderung bereitgestellt, und die Gültigkeit der Anforderung wird bei jeder Anforderung überprüft.

Hinweis

Zwar ist es nicht möglich, OAuth für eine Anwendung einzurichten, die nicht aus dem Katalog stammt, Sie können allerdings manuell ein Zugriffstoken auf Ihrem Autorisierungsserver generieren und es als geheimes Token für eine katalogfremde Anwendung einfügen. Dies ermöglicht es Ihnen, die Kompatibilität Ihres SCIM-Servers mit dem Microsoft Entra-Bereitstellungsdienst zu überprüfen, bevor Sie ein Onboarding im App-Katalog ausführen, für den die OAuth-Codegenehmigung unterstützt wird.

Langlebige OAuth-Bearertoken: Wenn Ihre Anwendung den Ablauf der OAuth-Autorisierungscodegenehmigung nicht unterstützt, generieren Sie stattdessen ein langlebiges OAuth-Bearertoken, mit dem ein Administrator die Bereitstellungsintegration einrichten kann. Das Token sollte unbefristet sein, andernfalls wird der Bereitstellungsauftrag nach Ablauf des Token unter Quarantäne gestellt.

Teilen Sie uns über UserVoice mit, wenn weitere Methoden zur Authentifizierung und Autorisierung erforderlich sind.

Es empfiehlt sich, die vorhandene Dokumentation zu aktualisieren und unsere gemeinsame Integration in Ihren Marketingkanälen hervorzuheben, um über die Integration zu informieren und Interesse dafür zu wecken. Wir empfehlen Ihnen, die folgende Prüfliste durchzugehen, um den Start zu unterstützen:

  • Stellen Sie sicher, dass Ihre Vertriebs- und Kundensupportteams mit den Integrationsfunktionen vertraut und bereit sind, sich zu ihnen zu äußern. Schulen Sie Ihre Teams, stellen Sie häufig gestellte Fragen bereit, und nehmen Sie die Integration in Ihr Vertriebsmaterial auf.
  • Erstellen Sie einen Blogbeitrag oder eine Pressemitteilung mit einer Beschreibung der gemeinsamen Integration, der Vorteile und der ersten Schritte. Beispiel: Imprivata und Microsoft Entra Pressemitteilung
  • Nutzen Sie soziale Medien wie Twitter, Facebook oder LinkedIn, um bei Ihren Kunden für die Integration zu werben. Schließen Sie @Microsoft Entra ID ein, damit wir Ihren Beitrag retweeten können. Beispiel: Twitter-Beitrag von Imprivata
  • Erstellen oder aktualisieren Sie Ihre Marketingseiten/Website (Integrationsseite, Partnerseite, Preisseite und Ähnliches), um die Verfügbarkeit der gemeinsamen Integration einzuschließen. Beispiel: Integrationsseite von Pingboard, Integrationsseite von Smartsheet, Preisseite von Monday.com
  • Erstellen Sie einen Hilfecenter-Artikel oder eine technische Dokumentation mit den ersten Schritten für Kunden. Beispiel: Integration von Envoy und Microsoft Entra.
  • Machen Sie Kunden über Ihre Kundenkommunikationskanäle (monatliche Newsletter, E-Mail-Kampagnen, Produktanmerkungen) auf die neue Integration aufmerksam.

Nächste Schritte