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:

• RFC 7642: System für domänenübergreifende Identitätsverwaltung: Definitionen, Übersicht, Konzepte und Anforderungen
• RFC 7643: System für domänenübergreifende Identitätsverwaltung: Kernschema
• RFC 7644: System für domänenübergreifende Identitätsverwaltung: Protokoll
• RFC 9865: Cursorbasierte Paginierung von SCIM-Ressourcen

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

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.

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

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

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

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

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 (Standardwert ist 100)

• cursor – zum Wechseln zur nächsten Ergebnisseite

Einschränkungen für Listenbenutzer

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.

• Im Abfrageparameter "filter" wird nur der Logikoperator "and" unterstützt. Die folgenden Benutzerattribute sind für den Vergleichsoperator "eq" zulässig:

  • username
  • externalId
  • id
  • groups.value
  • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname

• Die folgenden Benutzerattribute sind für den Vergleichsoperator "ew" (endsWith) zulässig.

  • username
  • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname

• Nur der logische Operator filter wird im Abfrageparameter zur Kombination von Filtern unterstützt.

• 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 den count Parameter verwenden, um eine bestimmte Anzahl von Benutzern abzurufen.

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

GET https://graph.microsoft.com/rp/scim/users?count=1000&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 – Benutzer nach Benutzer-ID und Gruppen-ID abrufen

Anforderung: Verwenden Sie die Entra-group objectId für die Eigenschaft groups.value und die user objectId für die Eigenschaft id, um zu überprüfen, ob ein Benutzer zu einer bestimmten Gruppe gehört.

GET https://graph.microsoft.com/rp/scim/users?filter=filter=groups.value eq "dddddddd-3333-4444-5555-eeeeeeeeeeee" and id eq "19134e88-95eb-4616-89af-189f0a4e2abf"&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": "Tanya Clifton",
      "meta": {
        "location": "/users/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
        "resourceType": "user"
      }
    }
  ]
}

Beispiel 8 : 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

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

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

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

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

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

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 Logikoperator "und" 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.

• 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.

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

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

• Gruppenmitglieder werden von diesem API-Aufruf nicht zurückgegeben. Verwenden Sie GET /groups mit dem Filter "members.value", um Gruppen abzurufen, bei denen ein Benutzer Mitglied ist.

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

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

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

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.

Verwandte Inhalte

• Aktivieren Sie die SCIM-Bereitstellungs-API in Microsoft Entra ID
• SCIM-Unterstützung in Microsoft Entra ID
• Die Microsoft Entra ID SCIM-API-Fehler beheben