Microsoft Entra ID SCIM-API-Referenz

Verwenden Sie dieses Referenzhandbuch, um Benutzer und Gruppen mithilfe des SciM-Protokolls (System für domänenübergreifende Identitätsverwaltung) v2.0 in Microsoft Entra ID bereitzustellen (synchronisieren).

SCIM-API –Übersicht

Die Microsoft Entra ID SCIM-Implementierung basiert auf den folgenden IETF-Entwürfen:

Alle SCIM-API-Endpunkte befinden sich unter der Basis-URL: https://graph.microsoft.com/rp/scim

Endpunkt Unterstützte HTTP-Methoden Beschreibung
/serviceproviderconfig GET Rufen Sie Konfigurationsdetails zur Microsoft Entra ID SCIM-Implementierung ab, z. B. unterstützte Authentifizierungsschemas, verfügbare Endpunkte und Compliance mit SCIM-Protokollen.
/resourcetypes GET Rufen Sie Informationen zu den von Microsoft Entra ID unterstützten Ressourcentypen (Benutzer und Gruppen) ab.
/schemas GET Rufen Sie detaillierte Informationen zu den von Microsoft Entra ID unterstützten Schemas ab.
/users GET, POST, PATCH, DELETE Lesen, Erstellen, Aktualisieren und Löschen von Benutzerdaten in Microsoft Entra ID.
/groups GET, POST, PATCH, DELETE Lesen, Erstellen, Aktualisieren und Löschen von Gruppen- und Gruppenmitgliedschaftsdaten in Entra ID.

Die folgenden Abschnitte enthalten Beispiele für API-Anforderungen und -Antworten, die derzeit in der Microsoft Entra ID SCIM-Implementierung unterstützt werden, sowie wichtige Hinweise und Einschränkungen, die sie in Ihrem Entwurf berücksichtigen sollten.

Aufrufen der SCIM-APIs

Bevor Sie die in diesem Artikel beschriebenen SCIM-API-Endpunkte aufrufen können, müssen Sie das SCIM-Bereitstellungs-API-Feature aktivieren, Abrechnung konfigurieren, Anmeldeinformationen einrichten und ein Zugriffstoken abrufen. Schrittweise Anleitungen finden Sie unter Enable the SCIM Provisioning API in Microsoft Entra ID.

Wenn Sie den Microsoft Graph-Endpunkt in der US Government-Cloud verwenden, verwenden Sie https://graph.microsoft.us/rp/scim sie als Basis-URL für SCIM-API-Anforderungen. In den Beispielen in diesem Artikel wird https://graph.microsoft.com verwendet, um den globalen Cloud-Endpunkt zu veranschaulichen.

Hinweis

SCIM-APIs arbeiten ausschließlich im Anwendungskontext (Nur-App-Token) und unterstützen keine delegierten Szenarien im Namen des Benutzers.

Zuordnung zu Graph-Benutzer- und -Gruppeneigenschaften

Informationen dazu, wie Microsoft Graph Benutzer- und Gruppeneigenschaften SCIM-Benutzer- und Gruppenattributen zugeordnet werden, finden Sie unter Microsoft Entra ID SCIM-API-Schemareferenz.

Drosselung

Die gleichen Einschränkungsrichtlinien und dienstspezifischen Einschränkungsgrenzwerte, die für Microsoft Graph APIs gelten, gelten auch für Microsoft Entra ID SCIM-APIs. Informationen zu den Einschränkungsrichtlinien, die für Microsoft Graph Benutzer- und Gruppen-APIs gelten, finden Sie unter Microsoft Graph Einschränkungsleitfaden und Microsoft Graph dienstspezifische Einschränkungsgrenzwerte für Identitäts- und Zugriffs-APIs.

Fehler

Eine Liste der gängigen Fehlercodes, die von SCIM-API-Endpunkten zurückgegeben werden, finden Sie unter SCIM-API-Fehlercodereferenz.

Dienstanbieter-Konfiguration abrufen

Verwenden Sie den /ServiceProviderConfig-Endpunkt, um zusätzliche Informationen zu Microsoft Entra ID SCIM-Implementierung anzuzeigen. Der /ServiceProviderConfig Endpunkt ist schreibgeschützt.

API-Endpunkt:https://graph.microsoft.com/rp/scim/serviceproviderconfig

Nach Erfolg gibt die API DEN HTTP-Status 200 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application User.Read.All, Group.Read.All und User.ReadWrite.AllGroup.ReadWrite.All

Beispiel 1 – Anfordern der Konfiguration des Dienstanbieters

Anforderung:

GET https://graph.microsoft.com/rp/scim/serviceproviderconfig
Authorization: Bearer {token}
Accept: application/json

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "documentationUri": "/graph/overview",
  "pagination": {
    "cursor": true,
    "index": false,
    "defaultPaginationMethod": "cursor",
    "defaultPageSize": 100,
    "maxPageSize": 1000
  },
  "patch": {
    "supported": true
  },
  "bulk": {
    "supported": false,
    "maxOperations": 0,
    "maxPayloadSize": 0
  },
  "filter": {
    "supported": true,
    "maxResults": 200
  }
}

Ressourcentypen auflisten

Informationen zu unterstützten Ressourcentypen können abgerufen werden, indem sie eine Anforderung an den Endpunkt "/resourcetypes" senden.

API-Endpunkte:

  • https://graph.microsoft.com/rp/scim/resourcetypes
  • https://graph.microsoft.com/rp/scim/resourcetypes/{identifier}

Nach Erfolg gibt die API DEN HTTP-Status 200 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application User.Read.All, Group.Read.All und User.ReadWrite.AllGroup.ReadWrite.All

Beispiel 1 – Anfordern aller Ressourcentypen

Anforderung:

GET https://graph.microsoft.com/rp/scim/resourcetypes
Authorization: Bearer {token}
Accept: application/json

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "User",
      "name": "User",
      "endpoint": "/Users",
      "description": "User Account",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
          "required": false
        },
        {
          "schema": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User",
          "required": false
        }
      ],
      "meta": {
        "location": "/resourcetypes/user",
        "resourceType": "resourceType"
      }
    },
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "Group",
      "name": "Group",
      "endpoint": "/Groups",
      "description": "Group",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group",
          "required": true
        }
      ],
      "meta": {
        "location": "/resourcetypes/group",
        "resourceType": "resourceType"
      }
    }
  ]
}

Beispiel 2 – Anfordern des Benutzerressourcentyps

Anforderung:

GET https://graph.microsoft.com/rp/scim/resourcetype/User
Authorization: Bearer {token}
Accept: application/json

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
  "id": "User",
  "name": "User",
  "endpoint": "/Users",
  "description": "User Account",
  "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
  "schemaExtensions": [
    {
      "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
      "required": false
    }
  ],
  "meta": {
    "location": "/resourcetypes/user",
    "resourceType": "resourceType"
  }
}

Schema abrufen

Informationen zu unterstützten SCIM-Schemas können abgerufen werden, indem sie eine Anforderung an den /schemas-Endpunkt senden.

API-Endpunkte:

  • https://graph.microsoft.com/rp/scim/schemas
  • https://graph.microsoft.com/rp/scim/schemas/{identifier}

Nach Erfolg gibt die API DEN HTTP-Status 200 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application User.Read.All, Group.Read.All und User.ReadWrite.AllGroup.ReadWrite.All

Hinweis

Zum Lesen des Schemas für benutzerdefinierte Sicherheitsattribute benötigt die App auch CustomSecAttributeDefinition.Read.All.

Beispiel 1 – Anfordern aller Schemas

Anforderung:

GET https://graph.microsoft.com/rp/scim/schemas
Authorization: Bearer {token}
Accept: application/json

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "Resources": [
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:User",
      "name": "User",
      "description": "User Account",
      "attributes": [...]
    },
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "name": "Group",
      "description": "Group",
      "attributes": [...]
    }
  ]
}

Beispiel 2 – Anfordern des Benutzerschemas

Anforderung:

GET https://graph.microsoft.com/rp/scim/schemas/urn:ietf:params:scim:schemas:core:2.0:User
Authorization: Bearer {token}
Accept: application/json

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "id": "urn:ietf:params:scim:schemas:core:2.0:User",
  "name": "User",
  "description": "User Account",
  "attributes": [...]
}

Beispiel 3 – Anfordern eines schemas für benutzerdefinierte Sicherheitsattribute

Anforderung:

GET https://graph.microsoft.com/rp/scim/schemas/urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes
Authorization: Bearer {token}
Accept: application/json

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "id": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes",
  "name": "MicrosoftEntraCustomSecurityAttributes",
  "description": "Microsoft Entra Custom Security Attributes",
  "attributes": [
    {
      "name": "Project",
      "type": "complex",
      "multiValued": false,
      "description": "Projects assigned to the user",
      "required": false,
      "caseExact": false,
      "subAttributes": [
        {
          "name": "ProjectName",
          "type": "String",
          "multiValued": false,
          "description": "Name of the project",
          "required": false,
          "caseExact": false,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none"
        }
      ],
      "mutability": "readWrite",
      "returned": "request",
      "uniqueness": "none"
    }, …
]
}

Benutzer auflisten

Verwenden Sie den /users Endpunkt, um die folgenden Vorgänge auszuführen:

  • Rufen Sie alle Benutzer im Mandanten ab (mit Paginierung).

  • Ruft Benutzer ab, die bestimmten Filterkriterien entsprechen.

API-Endpunkt:

https://graph.microsoft.com/rp/scim/users

Nach Erfolg gibt die API DEN HTTP-Status 200 zurück.

Wenn die Antwort mehrere Seiten enthält, verwenden Sie die cursorbasierte Paginierung , um alle Seiten im Ergebnis abzurufen.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application User.ReadBasic.All, User.Read.AllUser.ReadWrite.All

Hinweis

Um benutzerdefinierte Sicherheitsattribute für Benutzer zu lesen, benötigt die App außerdem CustomSecAttributeAssignment.Read.All oder CustomSecAttributeAssignment.ReadWrite.All.

User.ReadBasic.All schränkt Antworten auf grundlegende Profileigenschaften ein und unterstützt das Filtern nur nach Eigenschaften im Basisprofil. Von den von diesem Endpunkt unterstützten Filtern erfüllen id und userName diese Anforderung. Um Filter für active, groups.value, mailNickname, User.Read.All oder ownedGroups.value zu verwenden, gewähren Sie User.ReadWrite.All oder externalId.

Abfrageparameter für Listenbenutzer

Die folgenden SCIM-Abfrageparameter können mit diesem API-Endpunkt verwendet werden:

  • filter – zum Angeben der anzuwendenden Filterkriterien

  • Attribute – um anzugeben, welche Benutzerattribute vom Server zurückgegeben werden sollen.

  • excludedAttributes – um anzugeben, welche Benutzerattribute vom Server ausgeschlossen werden sollen.

  • count – um die Anzahl der abzurufenden Ergebnisse anzugeben. Der Standardwert ist 100. Größere projizierte Anforderungen unterstützen einen Wert von bis zu 999, vorbehaltlich der Einschränkungen im nächsten Abschnitt.

  • cursor – zum Wechseln zur nächsten Ergebnisseite

Einschränkungen für Listenbenutzer

Die Microsoft Entra ID SCIM-Implementierung weist die folgenden Einschränkungen auf:

  • Die Standardseitengröße beträgt 100 Einträge pro Seite.

  • Wenn Sie zwischen 101 und 999 Benutzer pro Seite anfordern möchten, geben Sie attributes an und nehmen Sie urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager nicht in die Projektion auf.

  • Wenn die attributes-Projektion urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager enthält, ignoriert der Dienst einen count-Wert größer als 100 und verwendet die Standardseitengröße von 100.

  • Die folgenden Benutzerattribute sind für den Vergleichsoperator eq zulässig:

    • active. Bei booleschen Werten wird die Groß- und Kleinschreibung nicht beachtet, einschließlich true, false, TRUE und FALSE.
    • userName
    • externalId
    • id
    • groups.value
    • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname
    • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:ownedGroups.value
  • Die folgenden Benutzerattribute sind für den ew Vergleichsoperator (endet mit) zulässig:

    • userName
    • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname
  • Verwenden Sie den Operator not, um einen ew-Vergleich für userName oder mailNickname zu negieren. Verwenden Sie den and logischen Operator, um unterstützte Filter zu kombinieren.

  • Alle codierten oder nicht codierten Leerzeichen in der Abfragezeichenfolge um das „=“ führen dazu, dass die Anforderung mit dem Fehler „BadRequest“ abgelehnt wird. Dies gilt für alle Abfrageparameter – Filter, Attribute, excludedAttributes, Count und Cursor.

  • Kombinationsfilter wird für die Verwendung mit externalId Attribut nicht unterstützt. Der folgende Kombinationsfilter kann beispielsweise nicht verwendet werden:

GET https://graph.microsoft.com/rp/scim/users?filter=externalId eq '12345' and userName eq 'user@contoso.com' 

Die folgenden Beispiele enthalten nur die Anforderungsdetails. Die Antwort ist aus Platzgründen nicht enthalten. Sie entspricht der standardmäßigen SCIM-Antwortnutzlast.

Beispiel 1A – Abrufen aller Benutzer

Anforderung:

GET https://graph.microsoft.com/rp/scim/users
Authorization: Bearer {token}
Accept: application/json

Antwort (200 OK):


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "itemsPerPage": 100,
  "nextCursor": "RFNwdAIAAQAAAB06MTAyMDE4QHhmcDFiLm9ubWljcm9zb2Z0LmNvbS...",
  "resources": [
    {
      "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:Microsoft:Entra:2.0:User"
      ],
      "id": "d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
      "active": true,
      "displayName": "Ellen Reckert",
      "name": {
        "familyName": "Reckert",
        "givenName": "Ellen"
      },
      "userName": "100009@contoso.com",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Human Resources US",
        "employeeNumber": "100009",
        "manager": {
          "value": "bbbbbbbb-7777-8888-9999-cccccccccccc"
        }
      },
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User": {
        "mailNickname": "100009",
        "userType": "Member"
      },
      "meta": {
        "location": "/users/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
        "resourceType": "user"
      }
    },
    { ... }
  ]
}

Beispiel 1B – Abrufen der nächsten Seite für das Abrufen aller Benutzer

Die obige Abfrage gibt standardmäßig 100 Benutzer pro Seite zurück. Wenn Ihr Mandant mehr als 100 Benutzer aufweist, verwenden Sie die Paginierung, um die nächste Gruppe von Benutzern abzurufen, indem Sie den Abfrageparameter cursor auf den in der Antwort empfangenen Wert von nextCursor festlegen.

GET https://graph.microsoft.com/rp/scim/users?cursor=RFNwdAIAAQAAAB06MTAyMDE4QHhmcDFiLm9ubWljcm9zb2Z0LmNvbS...
Authorization: Bearer {token}
Accept: application/json

Beispiel 1C – Verwenden des Count-Parameters zum Steuern der zurückgegebenen Benutzer

Sie können bis zu 999 Benutzer pro Seite anfordern, wenn Sie eine attributes Projektion angeben, die das urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager Attribut nicht enthält.

GET https://graph.microsoft.com/rp/scim/users?filter=active eq true&count=999&attributes=userName,id,displayName
Authorization: Bearer {token}
Accept: application/json
GET https://graph.microsoft.com/rp/scim/users?filter=active eq true&count=999&attributes=userName,id,displayName&cursor=RFNwdAIAAQAAAB06MTAyMDE4QHhmcDFiLm9ubWljcm9zb2Z0LmNvbS...
Authorization: Bearer {token}
Accept: application/json

Beispiel 2 – Benutzer nach ID mit bestimmten Attributen abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/users?filter=id eq "97c0abe1-14f7-417b-951c-bc8e2a17f200"&attributes=name.familyName,displayName
Authorization: Bearer {token}

Beispiel 3 – Abrufen von Benutzern mit einem Satz von benutzerdefinierten Sicherheitsattributen

Anforderung:

GET https://graph.microsoft.com/rp/scim/users?attributes=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes:attributeSetName
Authorization: Bearer {token}

Beispiel 4: Benutzer nach ID mit ausgeschlossenen Attributen abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/users?filter=id eq "97c0abe1-14f7-417b-951c-bc8e2a17f200"&excludedAttributes=name.familyName,displayName
Authorization: Bearer {token}

Beispiel 5 – Benutzer per mailNickname abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/users?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname eq "100009"&attributes=displayName
Authorization: Bearer {token}

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User"
      ],
      "id": "f5f5f5f5-aaaa-bbbb-cccc-d6d6d6d6d6d6",
      "displayName": "Ellen Reckert",
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User": {
        "mailNickname": "100009"
      },
      "meta": {
        "location": "/users/f5f5f5f5-aaaa-bbbb-cccc-d6d6d6d6d6d6",
        "resourceType": "user"
      }
    }
  ]
}

Beispiel 6 – Benutzer nach UserName abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/users?filter=userName eq "AdeleV@contoso.com"
Authorization: Bearer {token}

Beispiel 7 – Aktive Benutzer abrufen

Der active boolesche Filter berücksichtigt keine Groß- und Kleinschreibung.

Anforderung:

GET https://graph.microsoft.com/rp/scim/users?filter=active eq true
Authorization: Bearer {token}

Beispiel 8 – Ausschließen von Benutzern nach mailNickname-Suffix und Filter nach UserName-Suffix

Verwenden Sie not, um unterstützte Vergleiche mit ew zu negieren, und and, um die Filter zu kombinieren.

Anforderung:

GET https://graph.microsoft.com/rp/scim/users?filter=not(urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname ew "-admin") and not(urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname ew "-ga") and userName ew "@contoso.com"
Authorization: Bearer {token}

Beispiel 9 – Benutzer anhand der Gruppen-ID abrufen

Anforderung:

Verwenden Sie die Microsoft Entra Gruppenobjekt-ID für die groups.value Eigenschaft, um die direkten Mitglieder einer Gruppe abzurufen. Verwenden Sie diese Abfrage, statt das Attribut members von GET /groups/{id} anzufordern.

GET https://graph.microsoft.com/rp/scim/users?filter=groups.value eq "c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3"&attributes=displayName
Authorization: Bearer {token}

Antwort (200 OK) Die Antwort wurde zur besseren Lesbarkeit gekürzt.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
      "displayName": "Ellen Reckert",
      "meta": {
        "location": "/users/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
        "resourceType": "user"
      }
    }
  ]
}

Beispiel 10 – Benutzer abrufen, die Besitzer einer Gruppe sind

Obwohl ownedGroups in Benutzerantworttexten nicht zurückgegeben wird, können Sie dessen value Unterattribute als Filterziel verwenden. Geben Sie den vollständigen Microsoft Entra Benutzererweiterungsnamespace an.

Anforderung:

GET https://graph.microsoft.com/rp/scim/users?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:ownedGroups.value eq "c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3"
Authorization: Bearer {token}

Beispiel 11 : Abrufen bestimmter benutzerdefinierter Sicherheitsattribute für einen Benutzer

GET https://graph.microsoft.com/rp/scim/users?filter=userName eq "AdeleV@contoso.com"&attributes=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes:Project
Authorization: Bearer {token}

Antwort (200 OK) Die Antwort wurde zur besseren Lesbarkeit gekürzt.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes"
      ],
      "id": "b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
      "userName": "AdeleV@contoso.com",
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes": {
        "Project": {
          "ProjectName": "IdentityHub"
        }
      },
      "meta": {
        "location": "/users/b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
        "resourceType": "user"
      }
    }
  ]
}

Benutzer nach ID abrufen

Vorhandene Benutzer können abgerufen werden, indem sie eine GET-Anforderung an den /users-Endpunkt mit einer Benutzer-ID senden.

API-Endpunkte:

https://graph.microsoft.com/rp/scim/users/{id}

Nach Erfolg gibt die API DEN HTTP-Status 200 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application User.ReadBasic.All, User.Read.AllUser.ReadWrite.All

Hinweis

User.ReadBasic.All schränkt Antworten auf grundlegende Profileigenschaften ein. Um andere Benutzereigenschaften abzurufen, gewähren Sie User.Read.All oder User.ReadWrite.All.

Abfrageparameter für "Benutzer nach ID abrufen"

Die folgenden SCIM-Abfrageparameter können mit diesem API-Endpunkt verwendet werden:

  • Attribute – um anzugeben, welche Benutzerattribute vom Server zurückgegeben werden sollen.

  • excludedAttributes – um anzugeben, welche Benutzerattribute vom Server ausgeschlossen werden sollen.

Beispiel 1 – Benutzer nach ID mit bestimmten Attributen abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/users/aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb?attributes=displayName,userName
Authorization: Bearer {token}

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb",
  "displayName": "Adele Vance",
  "userName": "AdeleV@contoso.com",
  "meta": {
    "location": "/users/aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb",
    "resourceType": "user"
  }
}

Erstellen eines Benutzers

Sie können einen neuen Benutzer in Microsoft Entra ID erstellen, indem Sie eine POST-Anforderung an den /users-Endpunkt senden.

API-Endpunkte:

POST https://graph.microsoft.com/rp/scim/users

Nach Erfolg gibt die API DEN HTTP-Status 201 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application User.Create oder User.ReadWrite.All

Erforderliche Attribute für das Erstellen eines Benutzers

Für die erfolgreiche Benutzererstellung sind die folgenden Attribute erforderlich:

  • userName

  • password

  • name.familyName

  • name.givenName

  • active

  • displayName

Hinweis

Das urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname Attribut ist optional, wenn Sie einen Benutzer erstellen. Wenn Sie es weglassen, auf null festlegen oder einen leeren Wert angeben, leitet Microsoft Entra ID mailNickname aus userName ab. Es verwendet die Zeichen vor dem ersten @. Wenn userName@ nicht enthält, wird der vollständige Wert verwendet. Zum Beispiel erzeugt abc123@contoso.com einen mailNickname Wert von abc123.

Beispiel 1 – Erstellen eines neuen Benutzers

Anforderung:

POST https://graph.microsoft.com/rp/scim/users
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "active": true,
  "displayName": "Example User",
  "userName": "abc123@contoso.com",
  "password": "password",
  "name": {
    "familyName": "Example familyName",
    "givenName": "Example givenName"
  }
}

Antwort (201 erstellt):

Gibt die SCIM-Darstellung des erstellten Benutzers zurück.

In diesem Beispiel ermittelt Microsoft Entra ID den mailNickname-Wert abc123 aus userName.

Aktualisieren eines Benutzers

Der /users-Endpunkt ermöglicht eine PATCH-Anforderung zum Aktualisieren eines vorhandenen Benutzerprofils.

API-Endpunkte:

PATCH https://graph.microsoft.com/rp/scim/users/{id}

Nach Erfolg gibt die API DEN HTTP-Status 204 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application User.ReadUpdate.All oder User.ReadWrite.All

Hinweis

Wenn Ihre App nur bestimmte Benutzerattribute aktualisieren muss, verwenden Sie die Berechtigung mit den geringsten Rechten für diese Attribute. Ausführliche Informationen finden Sie in den SCIM-API-Anwendungsberechtigungen.

Einschränkungen für das Aktualisieren eines Benutzers

  • Bei PATCH-Vorgängen unterstützt die path-Eigenschaft beim Aktualisieren komplexer mehrwertiger Attribute wie Adressen nur den Filter „[type eq \" work\"]“.

  • Nachdem ein Benutzer erstellt wurde, kann das mailNickname Attribut nicht mithilfe eines PATCH-Vorgangs entfernt werden.

Beispiel 1 – Aktualisieren eines Attributwerts

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "Johnathan Doe"
    }
  ]
}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Beispiel 2 – Aktualisieren eines komplexen Werts

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:core:2.0:User:name",
      "value": {
        "familyName": "Jane",
        "givenName": "Doe"
      }
    }
  ]
}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Beispiel 3 – Aktualisieren eines komplexen mehrwertigen Attributs

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:core:2.0:User:addresses",
      "value": [
        {
          "type": "work",
          "streetAddress": "4567 Main Street",
          "locality": "Buffalo",
          "region": "NY",
          "postalCode": "98052",
          "country/region": "United States"
        }
      ]
    }
  ]
}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Beispiel 4 – Aktualisieren eines komplexen mehrwertigen Attributs mit Filter

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "operations": [
    {
      "op": "replace",
      "path": "emails[type eq \"work\" and primary eq true].value",         
      "value": "{edited_username}@{{tenant_domain}}"      
    }
  ]
}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Beispiel 5 – Aktualisieren des Benutzer-Managers

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager",
      "value": {
        "value": "915f96af-ea85-4687-b972-b26f69d719f9"
      }
    }
  ]
}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Beispiel 6 : Aktualisieren von benutzerdefinierten Sicherheitsattributen

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "operations": [
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes:Project.ProjectName",
      "value": "IdentityHubV2"
    }
  ]
}

Antwort (204 Kein Inhalt): Die Antwort entspricht der SCIM-Spezifikation.

Löschen eines Benutzers

Ein Benutzer kann gelöscht werden, indem er eine DELETE-Anforderung an den /users-Endpunkt mit einer vorhandenen Benutzer-ID sendet.

API-Endpunkte:

DELETE https://graph.microsoft.com/rp/scim/users/{id}

Nach Erfolg gibt die API DEN HTTP-Status 204 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application User.ReadWrite.All

Beispiel 1 – Löschen eines Benutzers

Anforderung:

DELETE https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Gruppen auflisten

Verwenden Sie den Endpunkt "/groups", um die folgenden Vorgänge auszuführen:

  • Rufen Sie alle Gruppen im Mandanten ab (mit Paginierung).

  • Ruft Gruppen ab, die bestimmten Filterkriterien entsprechen.

API-Endpunkte:

https://graph.microsoft.com/rp/scim/groups

Nach Erfolg gibt die API DEN HTTP-Status 200 zurück.

Wenn die Antwort mehrere Seiten enthält, verwenden Sie die cursorbasierte Paginierung , um alle Seiten im Ergebnis abzurufen.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application Group.Read.All, Group.ReadWrite.All

Abfrageparameter für Listengruppen

Die folgenden SCIM-Abfrageparameter können mit diesem API-Endpunkt verwendet werden:

  • filter – Zum Angeben der anzuwendenden Filterkriterien

  • attributes – um anzugeben, welche Gruppenattribute vom Server zurückgegeben werden sollen

  • excludedAttributes – um anzugeben, welche Gruppenattribute vom Server ausgeschlossen werden sollen

  • count – so geben Sie die Anzahl der abzurufenden Ergebnisse an (default=100)

  • cursor – um zur nächsten Ergebnisseite zu wechseln

Einschränkungen für Listengruppen

Die Microsoft Entra ID SCIM-Implementierung weist die folgenden Einschränkungen auf:

  • Wenn mehrere Seiten an dem Ergebnis beteiligt sind:

    • Die Standardseitengröße von 100 Einträgen pro Seite.

    • Die maximale Seitengröße beträgt 1000 Einträge pro Seite.

  • filter Im Abfrageparameter wird nur der and logische Operator zum Kombinieren von Filtern unterstützt. Die folgenden Gruppenattribute sind für den Vergleichsoperator eq zulässig:

    • displayName: Legen Sie dieses Attribut auf einen gültigen Microsoft Entra Gruppenanzeigenamen fest.
    • id: Legen Sie dieses Attribut auf eine gültige Microsoft Entra Gruppenobjekt-ID (GUID) in Ihrem Mandanten fest.
    • members.value: Legen Sie dieses Attribut auf eine gültige Microsoft Entra Benutzerobjekt-ID (GUID) in Ihrem Mandanten fest.
    • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:securityEnabled: Legen Sie für dieses Attribut einen Boolean-Wert ohne Berücksichtigung der Groß-/Kleinschreibung fest, einschließlich true, false, TRUE oder FALSE.
    • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:mailEnabled: Legen Sie dieses Attribut auf einen Booleschen Wert fest, bei dem die Groß-/Kleinschreibung nicht berücksichtigt wird, einschließlich true, false, TRUE oder FALSE.
    • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:owners.value: Legen Sie dieses Attribut auf eine gültige Microsoft Entra Benutzerobjekt-ID (GUID) in Ihrem Mandanten fest.
  • Die folgenden Gruppenattribute sind für den Vergleichsoperator "ew" (endsWith) zulässig.

    • Anzeigename
  • Die geschachtelte Gruppenmitgliedschaft wird bei Verwendung des member.value Filters nicht ausgewertet. Es werden nur direkte Mitgliedschaften ausgewertet.

Beispiele

Die folgenden Beispiele enthalten nur die Anforderungsdetails. Die Antwort ist aus Platzgründen nicht enthalten. Sie entspricht der standardmäßigen SCIM-Antwortnutzlast.

Beispiel 1 – Abrufen aller Gruppen

Anforderung:

GET https://graph.microsoft.com/rp/scim/groups
Authorization: Bearer {token}

Antwort (200 OK):

Wenn die Anzahl der Gruppen mehr als 100 beträgt, wird die Antwort die itemsPerPage-Eigenschaft und die nextCursor-Eigenschaft enthalten. Verwenden Sie den nextCursor Wert, um die nächste Seite des Ergebnisses abzurufen.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "itemsPerPage": 100,
  "nextCursor": "RFNwdAIAAQAAACpHcm91cF8zMDhiMzNkOC0wNjkxLTQzZTktOTA4Mi1kNG...",
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
      ],
      "id": "c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3",
      "displayName": "Sales and Marketing",
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": {
        "description": "Description of Sales and Marketing",
        "groupTypes": [
          "Unified"
        ],
        "mailEnabled": true,
        "mailNickname": "SalesandMarketing",
        "securityEnabled": false,
        "securityIdentifier": "ffffffff-5a5a-6b6b-7c7c-888888888888"
      },
      "meta": {
        "created": "2022-01-11T01:23:26+00:00",
        "location": "/groups/c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3",
        "resourceType": "group"
      }
    },    
    { ... }
  ]
}

Beispiel 1B – Abrufen der nächsten Seite für das Abrufen aller Gruppen

Die obige Abfrage gibt standardmäßig 100 Gruppen pro Seite zurück. Wenn Ihr Mandant mehr als 100 Gruppen aufweist, verwenden Sie die Paginierung, um die nächste Gruppe von Gruppen abzurufen, indem Sie den Abfrageparameter cursor auf den in der Antwort empfangenen Wert von nextCursor festlegen.

GET https://graph.microsoft.com/rp/scim/groups?cursor=RFNwdAIAAQAAACpHcm91cF8zMDhiMzNkOC0wNjkxLTQzZTktOTA4Mi1kNG...
Authorization: Bearer {token}
Accept: application/json

Beispiel 1C – Verwenden des Count-Parameters zum Steuern zurückgegebener Gruppen

Sie können den count Parameter verwenden, um eine bestimmte Anzahl von Gruppen abzurufen.

GET https://graph.microsoft.com/rp/scim/groups?count=1000
Authorization: Bearer {token}
Accept: application/json
GET https://graph.microsoft.com/rp/scim/groups?count=1000&cursor=RFNwdAIAAQAAACpHcm91cF8zMDhiMzNkOC0wNjkxLTQzZTktOTA4Mi1kNG...
Authorization: Bearer {token}
Accept: application/json

Beispiel 2 – Gruppen nach ID mit bestimmten Attributen abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/groups?filter=id eq "dddddddd-3333-4444-5555-eeeeeeeeeeee"&attributes=displayName
Authorization: Bearer {token}

Beispiel 3 – Abrufen einer Gruppe nach ID mit ausgeschlossenen Attributen

Anforderung:

GET https://graph.microsoft.com/rp/scim/groups?filter=id eq "dddddddd-3333-4444-5555-eeeeeeeeeeee"&excludedAttributes=displayName
Authorization: Bearer {token}

Beispiel 4 – Gruppe nach displayName abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/groups?filter=displayName eq "GroupA"
Authorization: Bearer {token}

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "a6a6a6a6-bbbb-cccc-dddd-e7e7e7e7e7e7",
      "displayName": "GroupA",
      "meta": {
        "location": "/groups/a6a6a6a6-bbbb-cccc-dddd-e7e7e7e7e7e7",
        "resourceType": "group"
      }
    }
  ]
}

Beispiel 5 – Gruppe nach Mitglied abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/groups?filter=members.value eq "d4b34e9e-0ad7-42df-b1f6-401b41fe1bee"
Authorization: Bearer {token}

Antwort (200 OK):

Die Antwort enthält sowohl zugewiesene als auch dynamische Gruppen, bei denen der Benutzer Mitglied ist.

Beispiel 6 – Abrufen von sicherheitsfähigen Gruppen

Anforderung:

GET https://graph.microsoft.com/rp/scim/groups?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:securityEnabled eq true
Authorization: Bearer {token}

Beispiel 7 – E-Mail-aktivierte Gruppen abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/groups?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:mailEnabled eq true
Authorization: Bearer {token}

Beispiel 8 – Abrufen von Gruppen, die einem Benutzer gehören

Obwohl owners in Gruppenantworttexten nicht zurückgegeben wird, können Sie dessen value Unterattribute als Filterziel verwenden. Geben Sie den vollständigen Microsoft Entra Gruppenerweiterungsnamespace an.

Anforderung:

GET https://graph.microsoft.com/rp/scim/groups?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:owners.value eq "d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4"
Authorization: Bearer {token}

Gruppe nach ID abrufen

Vorhandene Gruppen werden abgerufen, indem eine GET-Anforderung an den /groups-Endpunkt mit einer Gruppen-ID gesendet wird.

API-Endpunkte:

https://graph.microsoft.com/rp/scim/groups/{id}

Nach Erfolg gibt die API DEN HTTP-Status 200 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application Group.Read.All, Group.ReadWrite.All

Einschränkungen für "Gruppe nach ID abrufen"

  • Gruppenmitglieder werden durch diesen API-Aufruf nicht zurückgegeben. Die Paginierung auf Attributebene wird von der cursorbasierten Paginierungsspezifikation nicht unterstützt, sodass die API sie nicht verwenden kann, um große Memberauflistungen zurückzugeben. Um die direkten Mitglieder einer Gruppe abzurufen, verwenden Sie GET /users?filter=groups.value eq "{groupId}".

Abfrageparameter für "Gruppe nach ID abrufen"

Die folgenden SCIM-Abfrageparameter können mit diesem API-Endpunkt verwendet werden:

  • attributes – um anzugeben, welche Gruppenattribute vom Server zurückgegeben werden sollen.

  • excludedAttributes – um anzugeben, welche Gruppenattribute vom Server ausgeschlossen werden sollen.

Beispiel 1 – Gruppe nach ID abrufen

Anforderung:

GET https://graph.microsoft.com/rp/scim/groups/dddddddd-3333-4444-5555-eeeeeeeeeeee
Authorization: Bearer {token}

Antwort (200 OK):

Die Antwort wurde für eine bessere Lesbarkeit gekürzt.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
  ],
  "id": "dddddddd-3333-4444-5555-eeeeeeeeeeee",
  "displayName": "GroupA",
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": {
    "description": "Group for All Employees - Baseline access",
    "mailEnabled": false,
    "mailNickname": "3c998a58-6",
    "securityEnabled": true,
    "securityIdentifier": "ffffffff-5a5a-6b6b-7c7c-888888888888"
  },
  "meta": {
    "created": "2024-05-23T17:21:41+00:00",
    "location": "/groups/dddddddd-3333-4444-5555-eeeeeeeeeeee",
    "resourceType": "group"
  }
}

Erstellen einer Gruppe

Sie können eine neue Gruppe in Microsoft Entra ID erstellen, indem Sie eine POST-Anforderung an den Endpunkt "/groups" senden.

API-Endpunkte:

POST https://graph.microsoft.com/rp/scim/groups

Nach Erfolg gibt die API DEN HTTP-Status 201 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application Group.Create oder Group.ReadWrite.All

Erforderliche Attribute für das Erstellen einer Gruppe

Für die erfolgreiche Gruppenerstellung sind die folgenden Attribute erforderlich:

  • displayName

Beispiel 1 – Erstellen einer neuen Gruppe

Anforderung:

POST https://graph.microsoft.com/rp/scim/groups
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
  ],
  "displayName": "Test SCIM Group",
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": { 
    "mailEnabled": false, 
    "mailNickname": "test-scim-group", 
    "securityEnabled": true 
  }
}

Antwort (201 erstellt):

Gibt die SCIM-Darstellung der erstellten Gruppe zurück.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
  ],
  "id": "66aa66aa-bb77-cc88-dd99-00ee00ee00ee",
  "displayName": "Test SCIM Group",
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": {
    "mailEnabled": false,
    "mailNickname": "test-scim-group",
    "securityEnabled": true,
    "securityIdentifier": "ffffffff-5a5a-6b6b-7c7c-888888888888"
  },
  "meta": {
    "created": "2026-03-30T16:28:37+00:00",
    "location": "/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee",
    "resourceType": "group"
  }
}

Aktualisieren einer Gruppe

Der /groups Endpunkt ermöglicht eine PATCH-Anforderung zum Aktualisieren einer vorhandenen Gruppe.

API-Endpunkte:

PATCH https://graph.microsoft.com/rp/scim/groups/{id}

Nach Erfolg gibt die API DEN HTTP-Status 204 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application GroupMember.ReadWrite.All oder Group.ReadWrite.All für Mitgliedschaftsänderungen; Group.ReadWrite.All für Änderungen an Gruppeneigenschaften.

Hinweis

GroupMember.ReadWrite.All unterstützt nur Anfragen, mit denen Mitglieder hinzugefügt oder entfernt werden. Um Gruppeneigenschaften wie displayName oder description zu aktualisieren, gewähren Sie Group.ReadWrite.All.

Einschränkungen für die Aktualisierung einer Gruppe

  • Das Hinzufügen von Mitgliedern zu Gruppen muss in einem einzelnen PATCH Operation-Objekt erfolgen.  

  • Wenn Sie die API verwenden, um mehrere Mitglieder in einer Anforderung hinzuzufügen, können Sie nur bis zu 20 Mitglieder hinzufügen. 

  • Pro PATCH-Aufruf kann nur ein Mitglied aus einer Gruppe entfernt werden.  

  • Das Entfernen von Gruppenmitgliedern muss ohne andere Attributänderungen erfolgen, die im gleichen PATCH-Aufruf enthalten sind (einschließlich hinzufügen von Mitgliedern).  

  • Das Hinzufügen von Mitgliedern zu Gruppen muss ohne weitere Attributänderungen erfolgen (einschließlich des Entfernens von Mitgliedern).  

  • Das Hinzufügen von Gruppenmitgliedern wird als idempotente Operation behandelt. Wenn ein bestimmtes Mitglied bereits in der Gruppe vorhanden ist, wird kein Fehler zurückgegeben, und der Vorgang ist erfolgreich, solange alle memberIds auf gültige Benutzerobjekte verweisen.

  • Wenn eine memberId, die entweder im Vorgang zum Hinzufügen oder Entfernen der Gruppenmitgliedschaft übergeben wurde, ungültig ist, schlägt der gesamte Vorgang mit der Fehlermeldung “Resource '00000000-0000-0000-0000-000000000000' fehl, da sie nicht existiert oder eines ihrer referenzierten Eigenschaftsobjekte nicht vorhanden ist.

Beispiel 1 – Anzeigename der Gruppe aktualisieren

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "SCIM Testing Group Edited"
    }
  ]
}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Beispiel 2 – Gruppenbeschreibung aktualisieren

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:description",
      "value": "Finance group"
    }
  ]
}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Beispiel 3 – Hinzufügen von Gruppenmitgliedern

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "756b18d2-023a-4fa8-845e-9ac8b524100f"
        },
        {
          "value": "0e4c70dd-c015-48db-bb5a-6264d215ca8e"
        }
      ]
    }
  ]
}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Beispiel 4 – Entfernen von Gruppenmitgliedern

Anforderung:

PATCH https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb\"]"
    }
  ]
}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.

Löschen einer Gruppe

Eine Gruppe kann gelöscht werden, indem eine DELETE-Anforderung an den /groups-Endpunkt mit einer vorhandenen Gruppen-ID gesendet wird.

API-Endpunkte:

DELETE https://graph.microsoft.com/rp/scim/groups/{id}

Nach Erfolg gibt die API DEN HTTP-Status 204 zurück.

Erlaubnisse

Berechtigungstyp Berechtigungen (von am wenigsten bis am meisten privilegiert)
Application Group.ReadWrite.All

Beispiel 1 – Löschen einer Gruppe

Anforderung:

DELETE https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}

Antwort (204 Kein Inhalt):

Die Antwort entspricht der SCIM-Spezifikation.