Erweitern der API-gesteuerten Bereitstellung zur Synchronisierung benutzerdefinierter Attribute

Artikel
02/28/2024

Standardmäßig unterstützen Apps für die API-gesteuerte Bereitstellung die Verarbeitung von Attributen, die Teil des Schemas für SCIM Core-Benutzer*innen und Enterprise-Benutzer*innen sind. Ihr Datensatzsystem enthält möglicherweise benutzerdefinierte Attribute, die Sie u. U. im Rahmen der API-gesteuerten Bereitstellung aufnehmen möchten. In diesem erweiterten Tutorial wird beschrieben, wie Sie Ihre App für die API-gesteuerte Bereitstellung erweitern, um zusätzliche benutzerdefinierte Attribute zu verarbeiten.

Hinweis

Bevor Sie dieses erweiterte Szenario ausprobieren, sollten Sie überprüfen, ob Ihre vordefinierte Konfiguration der Bereitstellungs-App wie erwartet funktioniert, indem Sie einen der folgenden API-Clients verwenden: Graph Explorer, cURL oder Postman.

Beispielszenario

Sie haben die App für die API-gesteuerte Bereitstellung konfiguriert. Ihre Bereitstellungs-App nutzt erfolgreich die Attribute, die Teil des Standardschemas für SCIM Core-Benutzer*innen und Enterprise-Benutzer*innen sind, und stellt Benutzer*innen in Microsoft Entra ID bereit. Sie möchten nun die zwei benutzerdefinierten Attribute HireDate und JobCode von Ihrem Personalsystem an den API-Endpunkt für die eingehende Bereitstellung senden. Sie möchten diese beiden benutzerdefinierten Attribute den Microsoft Entra-Attributen employeeHireDate und jobTitle zuordnen.

Schritt 1: Erweitern des Bereitstellungs-App-Schemas

In diesem Schritt fügen Sie die beiden Attribute „HireDate“ und „JobCode“, die nicht Teil des SCIM-Standardschemas sind, zur Bereitstellungs-App hinzu und verwenden sie im Bereitstellungsdatenfluss.

Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsadministrator an.
Browsen Sie zu Identität>Anwendungen>Unternehmensanwendungen.
Öffnen Sie Ihre API-gesteuerte Bereitstellungs-App.
Öffnen Sie das Blatt Bereitstellung.
Klicken Sie auf die Schaltfläche Bereitstellung bearbeiten.
Erweitern Sie den Abschnitt Zuordnungen, und klicken Sie auf den Link „Attributzuordnung“.
Scrollen Sie auf der Seite Attributzuordnungen nach unten. Wählen Sie Erweiterte Optionen anzeigen aus, und klicken Sie auf den Link Attributliste für API bearbeiten.
Scrollen Sie nach unten bis zum Ende der Seite Attributliste bearbeiten.
Fügen Sie der Liste die folgenden beiden Attribute als SCIM-Schemaerweiterungen hinzu. Sie können Ihren eigenen SCIM-Schemanamespace verwenden.
urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate
urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode
Speichern Sie Ihre Änderungen.

Hinweis

Wenn Sie der Bereitstellungs-App nur einige zusätzliche Attribute hinzufügen möchten, verwenden Sie das Microsoft Entra Admin Center, um das Schema zu erweitern. Wenn Sie weitere benutzerdefinierte Attribute hinzufügen möchten (etwa mehr als 20 Attribute), empfiehlt es sich, den UpdateSchema-Modus des CSV2SCIM PowerShell-Skripts zu verwenden, der den oben genannten manuellen Prozess automatisiert.

Schritt 2: Zuordnen der benutzerdefinierten Attribute

Nun fügen Sie diese Erweiterungen der Attributzuordnung der Bereitstellungs-App hinzu.

Klicken Sie auf der Seite Attributzuordnung auf den Link Neue Zuordnung hinzufügen.
Ordnen Sie employeeHireDate das Attribut urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate zu. Klicken Sie auf OK.
Wählen Sie als Nächstes die vorhandene Zuordnung für title aus, und klicken Sie darauf, um die Zuordnung zu bearbeiten.
Ändern Sie die Attributzuordnung in einen Ausdruck, der urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode als Teil des Microsoft Entra-Attributs jobTitle enthält.
```
  Join("", [title], "(", [urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode], ")")
```
Wenn title bei dieser Ausdruckszuordnung „Tour Lead“ und JobCode „TL-1001“ lautet, wird das Microsoft Entra-Attribut jobTitle auf „Tour Lead (TL-1001)“ festgelegt.
Speichern Sie die Attributzuordnungen.

Schritt 3: Hochladen einer Massenanforderung mit benutzerdefinierten Attributen

Öffnen Sie Ihren API-Client (Graph Explorer/Postman/cURL).
Kopieren Sie die Massenanforderung mit benutzerdefinierten Attributen, und fügen Sie sie ein.
Senden Sie die Massenanforderung an die URL des Bereitstellungs-API-Endpunkts.
Nach einiger Zeit können Sie die Bereitstellungsprotokolle überprüfen, um die Attributänderung zu überprüfen.
Sie können die Änderung auch im Microsoft Entra-Benutzerprofil überprüfen. Der Wert für Employee hire date spiegelt Ihre Mandantenzeitzone wider.

Anhang

Massenanforderung mit benutzerdefinierten Attributen

Die Massenanforderung enthält die benutzerdefinierten Attribute, die in den obigen Schritten konfiguriert wurden.

Anforderungstext

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "path": "/Users",
        "data": {
            "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:contoso:1.0:User"],
            "externalId": "701984",
            "userName": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "234300 Universal City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91608",
              "country": "USA",
              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5555",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Guide",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "employeeNumber": "701984",
                "costCenter": "4130",
                "organization": "Universal Studios",
                "division": "Theme Park",
                "department": "Tour Operations",
                "manager": {
                  "value": "89607",
                  "displayName": "John Smith"
                 }
            },
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {
                "HireDate": "2021-05-01T00:00:00-05:00",
                "JobCode": "TG-1001"
            }            
        }
    },
    {
        "method": "POST",
        "bulkId": "701985",
        "path": "/Users",
        "data": {
            "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:contoso:1.0:User"],
            "externalId": "701985",
            "userName": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Oracle City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91618",
              "country": "USA",
              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5545",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Lead",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
              "employeeNumber": "701984",
              "costCenter": "4130",
              "organization": "Universal Studios",
              "division": "Theme Park",
              "department": "Tour Operations",
              "manager": {
                "value": "701984",
                "displayName": "Barbara Jensen"
             }
            },
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {
                "HireDate": "2022-07-15T00:00:00-05:00",
                "JobCode": "TL-1003"
            }            
        }
    }
],
    "failOnErrors": null
}

Teilen über