Riferimento per l'API SCIM di Microsoft Entra ID

Usare questa guida di riferimento per effettuare il provisioning (sincronizzare) utenti e gruppi in Microsoft Entra ID usando il protocollo SCIM (System for Cross-domain Identity Management) v2.0.

Panoramica dell'API SCIM

L'implementazione Microsoft Entra ID SCIM si basa sulle bozze IETF seguenti:

• RFC 7642: sistema per la gestione delle identità tra domini: definizioni, panoramica, concetti e requisiti
• RFC 7643: System for Cross-domain Identity Management: Core Schema
• RFC 7644: Sistema per La gestione delle identità tra domini: Protocollo
• RFC 9865: impaginazione basata su cursore delle risorse SCIM

Tutti gli endpoint dell'API SCIM si trovano nell'URL di base: https://graph.microsoft.com/rp/scim

Le sezioni seguenti contengono esempi di richieste API e risposte attualmente supportate nell'implementazione SCIM Microsoft Entra ID, insieme a note e vincoli importanti da considerare nella progettazione.

Richiamo delle API SCIM

Prima di poter chiamare gli endpoint dell'API SCIM descritti in questo articolo, è necessario abilitare la funzionalità API di provisioning SCIM, configurare la fatturazione, configurare le credenziali e ottenere un token di accesso. Per istruzioni dettagliate, vedere Enable the SCIM Provisioning API in Microsoft Entra ID.

Se si usa l'endpoint Microsoft Graph nel cloud us government, usare https://graph.microsoft.us/rp/scim come URL di base per le richieste api SCIM. Gli esempi in questo articolo usano https://graph.microsoft.com per illustrare l'endpoint cloud globale.

Mapping delle proprietà dell'utente e del gruppo di Graph

Per informazioni su come le proprietà utente e gruppo di Microsoft Graph eseguono il mapping agli attributi di utenti e gruppi SCIM, consultare il riferimento allo schema API SCIM di Microsoft Entra ID.

Throttling

Le stesse linee guida per la limitazione e i limiti di limitazione specifici del servizio che si applicano alle API di Microsoft Graph si applicano anche alle API SCIM Microsoft Entra ID. Per i criteri di limitazione applicabili alle API di utenti e gruppi Microsoft Graph, vedere Microsoft Graph indicazioni sulla limitazione delle richieste e Microsoft Graph limiti di limitazione specifici del servizio per le API di identità e accesso.

Errori

Per un elenco dei codici di errore comuni restituiti dagli endpoint dell'API SCIM, vedere il riferimento sui codici di errore dell'API SCIM.

Ottenere la configurazione del provider di servizi

Usare l'endpoint /ServiceProviderConfig per visualizzare informazioni aggiuntive sull'implementazione Microsoft Entra ID SCIM. L'endpoint /ServiceProviderConfig è di sola lettura.

Endpoint API:https://graph.microsoft.com/rp/scim/serviceproviderconfig

Al termine dell'operazione, l'API restituisce lo stato HTTP 200.

Autorizzazioni

Esempio 1: richiesta di configurazione del provider di servizi

Richiesta:

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

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

{
  "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
  }
}

Elencare i tipi di risorse

È possibile recuperare informazioni sui tipi di risorse supportati effettuando una richiesta all'endpoint /resourcetypes.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 200.

Autorizzazioni

Esempio 1: richiesta di tutti i tipi di risorse

Richiesta:

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

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

{
  "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"
      }
    }
  ]
}

Esempio 2: richiesta del tipo di risorsa utente

Richiesta:

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

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

{
  "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"
  }
}

Ottieni schema

È possibile recuperare informazioni sugli schemi SCIM supportati effettuando una richiesta all'endpoint /schemas.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 200.

Autorizzazioni

Esempio 1: richiesta di tutti gli schemi

Richiesta:

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

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

{
  "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": [...]
    }
  ]
}

Esempio 2: richiesta dello schema utente

Richiesta:

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

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

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

Esempio 3: richiesta dello schema degli attributi di sicurezza personalizzati

Richiesta:

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

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

{
  "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"
    }, …
]
}

Elencare gli utenti

Usare l'endpoint /users per eseguire le operazioni seguenti:

• Ottenere tutti gli utenti nel tenant (con paginazione).

• Ottenere gli utenti che soddisfano criteri di filtro specifici.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 200.

Se la risposta contiene più pagine, usare la paginazione basata su cursore per recuperare tutte le pagine nel risultato.

Autorizzazioni

Parametri di query per la lista utenti

I parametri di query SCIM seguenti possono essere usati con questo endpoint API:

• filter : per specificare i criteri di filtro da applicare

• attributi : per specificare gli attributi utente che devono essere restituiti dal server.

• excludedAttributes : per specificare gli attributi utente da escludere dal server.

• count : per specificare il numero di risultati da recuperare (il valore predefinito è 100)

• cursor : per passare alla pagina dei risultati successiva

Vincoli per gli utenti dell'elenco

L'implementazione Microsoft Entra ID SCIM presenta i vincoli seguenti:

• Quando vengono coinvolte più pagine nel risultato:

  • Dimensioni di pagina predefinite di 100 voci per pagina.
  • La dimensione massima della pagina è 1000 voci per pagina.

• Nel parametro di query "filter" è supportato solo l'operatore logico "and". Per l'operatore di confronto "eq" sono consentiti gli attributi utente seguenti:

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

• Gli attributi utente seguenti sono consentiti per l'operatore di confronto "ew" (endsWith).

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

• filter Nel parametro di query è supportato solo l'operatore logico e per la combinazione di filtri.

• Qualsiasi spazio vuoto codificato o non codificato nella stringa di query intorno a "=" comporta il rifiuto della richiesta con un errore "BadRequest". Questo vale per tutti i parametri di query, ovvero filtro, attributi, excludedAttributes, conteggio e cursore.

• Il filtro combinato non è supportato per l'uso con externalId l'attributo . Ad esempio, non è possibile usare il filtro combinato seguente:

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

Gli esempi seguenti includono solo i dettagli della richiesta. La risposta non è inclusa per brevità. È conforme al payload di risposta SCIM standard.

Esempio 1A: ottenere tutti gli utenti

Richiesta:

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

Risposta (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"
      }
    },
    { ... }
  ]
}

Esempio 1B: recupero della prossima pagina per visualizzare tutti gli utenti

La query precedente per impostazione predefinita restituisce 100 utenti per pagina. Se sono presenti più di 100 utenti nel tuo tenant, utilizza la paginazione per recuperare il set successivo di utenti impostando il parametro di query cursor al valore di nextCursor ricevuto nella risposta.

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

Esempio 1C: uso del parametro count per controllare gli utenti restituiti

È possibile usare il count parametro per recuperare un determinato numero di utenti.

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

Esempio 2: ottenere l'utente in base all'ID con attributi specifici

Richiesta:

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

Esempio 3: ottenere gli utenti con un set di attributi di sicurezza personalizzato

Richiesta:

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

Esempio 4 - Recuperare l'utente per ID con attributi esclusi

Richiesta:

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

Esempio 5: ottenere l'utente tramite mailNickname

Richiesta:

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}

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

{
  "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"
      }
    }
  ]
}

Esempio 6: Ottieni l'utente per nome utente

Richiesta:

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

Esempio 7: Trovare l'utente utilizzando l'ID utente e l'ID gruppo

Richiesta: Utilizzare Entra group objectId per la groups.value proprietà e per user objectId la id proprietà per verificare se un utente appartiene a un gruppo specifico.

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}

Risposta (200 OK) Risposta troncata per la leggibilità.

{
  "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"
      }
    }
  ]
}

Esempio 8- Recuperare attributi di sicurezza personalizzati specifici per un utente

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}

Risposta (200 OK) Risposta troncata per la leggibilità.

{
  "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"
      }
    }
  ]
}

Ottenere l'utente in base all'ID

Gli utenti esistenti possono essere recuperati effettuando una richiesta GET all'endpoint /users con un ID utente.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 200.

Autorizzazioni

Parametri di query per Ottenere l'utente in base all'ID

I parametri di query SCIM seguenti possono essere usati con questo endpoint API:

• attributi: per specificare gli attributi utente che devono essere restituiti dal server.

• excludedAttributes: per specificare gli attributi utente da escludere dal server.

Esempio 1: ottenere l'utente in base all'ID con attributi specifici

Richiesta:

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

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

{
  "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"
  }
}

Creare un utente

È possibile creare un nuovo utente in Microsoft Entra ID inviando una richiesta POST all'endpoint /users.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 201.

Autorizzazioni

Attributi obbligatori per Creare un utente

Per la corretta creazione dell'utente sono necessari gli attributi seguenti:

• userName

• password

• name.familyName

• name.givenName

• active

• displayName

Esempio 1: creare un nuovo utente

Richiesta:

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"
  }
}

Risposta (201 Creato):

Restituisce la rappresentazione SCIM dell'utente creato.

In questo esempio Microsoft Entra ID deriva il mailNickname valore abc123 da userName.

Aggiornare un utente

L'endpoint /users consente di effettuare una richiesta PATCH per l'aggiornamento di un profilo utente esistente.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 204.

Autorizzazioni

Vincoli per aggiornare un utente

• Per le operazioni PATCH, durante l'aggiornamento di attributi complessi a valori multipli come gli indirizzi, la proprietà path supporta solo il filtro "[type eq \"work\"]".

• Dopo la creazione di un utente, l'attributo mailNickname non può essere rimosso usando un'operazione PATCH.

Esempio 1: aggiornare un valore di attributo

Richiesta:

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"
    }
  ]
}

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Esempio 2: aggiornare un valore complesso

Richiesta:

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"
      }
    }
  ]
}

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Esempio 3: aggiornare un attributo multivalore complesso

Richiesta:

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"
        }
      ]
    }
  ]
}

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Esempio 4: aggiornare un attributo multivalore complesso con filtro

Richiesta:

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}}"      
    }
  ]
}

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Esempio 5 : Aggiornare il gestore utenti

Richiesta:

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"
      }
    }
  ]
}

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Esempio 6 - Aggiornare gli attributi di sicurezza personalizzati

Richiesta:

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"
    }
  ]
}

Risposta (204 Nessun contenuto): La risposta è conforme alla specifica SCIM.

Eliminare un utente

Un utente può essere eliminato effettuando una richiesta DELETE all'endpoint /users con un ID utente esistente.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 204.

Autorizzazioni

Esempio 1: eliminare un utente

Richiesta:

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

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Elencare i gruppi

Usare l'endpoint /groups per eseguire le operazioni seguenti:

• Ottenere tutti i gruppi nel tenant (con paginazione).

• Ottenere gruppi che corrispondono a criteri di filtro specifici.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 200.

Se la risposta contiene più pagine, usare la paginazione basata su cursore per recuperare tutte le pagine nel risultato.

Autorizzazioni

Parametri di query per i gruppi di elenco

I parametri di query SCIM seguenti possono essere usati con questo endpoint API:

• filter : per specificare i criteri di filtro da applicare

• attributes : per specificare quali attributi di gruppo devono essere restituiti dal server

• excludedAttributes : per specificare gli attributi del gruppo da escludere dal server

• count : per specificare il numero di risultati da recuperare (default=100)

• cursor : per passare alla pagina dei risultati successiva

Vincoli per i gruppi di elenchi

L'implementazione Microsoft Entra ID SCIM presenta i vincoli seguenti:

• Quando vengono coinvolte più pagine nel risultato:

  • Dimensioni di pagina predefinite di 100 voci per pagina.

  • La dimensione massima della pagina è 1000 voci per pagina.

• filter Nel parametro di query è supportato solo l'operatore logico "and". Gli attributi di gruppo seguenti sono consentiti per l'operatore di confronto "eq".

  • displayName: Impostare questo attributo su un nome visualizzato valido del gruppo Microsoft Entra.
  • id: Imposta questo attributo su un ID oggetto del gruppo di Microsoft Entra valido nel tuo tenant.
  • members.value: Imposti l'attributo su un ID oggetto utente (GUID) Microsoft Entra valido nel tenant.

• Gli attributi di gruppo seguenti sono consentiti per l'operatore di confronto "ew" (endsWith)

  • nome visualizzato

• L'appartenenza al gruppo annidata non viene valutata quando si usa il filtro member.value. Vengono valutate solo le appartenenze dirette.

Examples

Gli esempi seguenti includono solo i dettagli della richiesta. La risposta non è inclusa per brevità. È conforme al payload di risposta SCIM standard.

Esempio 1: ottenere tutti i gruppi

Richiesta:

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

Risposta (200 OK):

Se il numero di gruppi è maggiore di 100, la risposta includerà la itemsPerPage proprietà e nextCursor . Usare il nextCursor valore per recuperare la pagina successiva del risultato.

{
  "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"
      }
    },    
    { ... }
  ]
}

Esempio 1B: recupero della pagina successiva per ottenere tutti i gruppi

La query precedente per impostazione predefinita restituisce 100 gruppi per pagina. Se nel tenant sono presenti più di 100 gruppi, utilizzare la paginazione per ottenere l'insieme successivo di gruppi impostando il parametro di query cursor sul valore di nextCursor ricevuto nella risposta.

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

Esempio 1C: uso del parametro count per i gruppi di controllo restituiti

È possibile usare il count parametro per recuperare un determinato numero di gruppi.

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

Esempio 2: ottenere un gruppo per ID con attributi specifici

Richiesta:

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

Esempio 3: ottenere un gruppo in base all'ID con attributi esclusi

Richiesta:

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

Esempio 4: Ottenere un gruppo in base a displayName

Richiesta:

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

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

{
  "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"
      }
    }
  ]
}

Esempio 5: ottenere un gruppo per membro

Richiesta:

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

Risposta (200 OK):

La risposta include gruppi assegnati e dinamici in cui l'utente è membro.

Ottenere un gruppo in base all'ID

I gruppi esistenti vengono recuperati effettuando una richiesta GET all'endpoint /groups con un ID gruppo.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 200.

Autorizzazioni

Vincoli per ottenere il gruppo per ID

• I membri del gruppo non vengono restituiti da questa chiamata API. Usare il filtro GET /groups con members.value per recuperare i gruppi in cui l'utente è membro.

Parametri di query per ottenere il gruppo tramite ID

I parametri di query SCIM seguenti possono essere usati con questo endpoint API:

• attributes : per specificare quali attributi di gruppo devono essere restituiti dal server.

• excludedAttributes : per specificare gli attributi del gruppo da escludere dal server.

Esempio 1: ottenere un gruppo in base all'ID

Richiesta:

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

Risposta (200 OK):

La risposta viene troncata per la leggibilità.

{
  "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"
  }
}

Creare un gruppo

È possibile creare un nuovo gruppo in Microsoft Entra ID inviando una richiesta POST all'endpoint /groups.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 201.

Autorizzazioni

Attributi obbligatori per Creare un gruppo

Per la corretta creazione di gruppi sono necessari gli attributi seguenti:

• displayName

Esempio 1: Creare un nuovo gruppo

Richiesta:

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 
  }
}

Risposta (201 Creato):

Restituisce la rappresentazione SCIM del gruppo creato.

{
  "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"
  }
}

Aggiornare un gruppo

L'endpoint /groups consente di effettuare una richiesta PATCH per l'aggiornamento di un gruppo esistente.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 204.

Autorizzazioni

Vincoli per aggiornare un gruppo

• L'aggiunta di membri ai gruppi deve essere eseguita in un singolo oggetto PATCH Operation .  

• Quando si usa l'API per aggiungere più membri in una richiesta, è possibile aggiungere fino a 20 membri. 

• È possibile rimuovere un solo membro da un gruppo per ogni chiamata PATCH.  

• La rimozione dei membri del gruppo deve essere eseguita senza altre modifiche di attributo incluse nella stessa chiamata PATCH (inclusa l'aggiunta di membri).  

• L'aggiunta di membri ai gruppi deve essere eseguita senza altre modifiche agli attributi (inclusa la rimozione dei membri).  

• L'aggiunta di membri del gruppo viene considerata un'operazione idempotente . Se un membro specifico è già presente nel gruppo, non viene restituito alcun errore e l'operazione ha esito positivo, purché tutti i memberId del gruppo puntino a oggetti utente validi.

• Se un memberId passato nell'operazione di aggiunta o rimozione dell'appartenenza al gruppo non è valido, l'intera operazione ha esito negativo e il messaggio “Resource '00000000-0000-0000-0000-000000000000' di errore non esiste o uno dei relativi oggetti di proprietà di riferimento sottoposti a query non è presente".

Esempio 1: aggiornare il nome visualizzato del gruppo

Richiesta:

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"
    }
  ]
}

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Esempio 2 : Descrizione del gruppo di aggiornamento

Richiesta:

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"
    }
  ]
}

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Esempio 3: Aggiungere membri del gruppo

Richiesta:

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"
        }
      ]
    }
  ]
}

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Esempio 4: rimuovere i membri del gruppo

Richiesta:

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\"]"
    }
  ]
}

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Eliminare un gruppo

È possibile eliminare un gruppo effettuando una richiesta DELETE all'endpoint /groups con un ID gruppo esistente.

Endpoint API:

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

Al termine dell'operazione, l'API restituisce lo stato HTTP 204.

Autorizzazioni

Esempio 1: Eliminare un gruppo

Richiesta:

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

Risposta (204 Nessun contenuto):

La risposta è conforme alla specifica SCIM.

Contenuti correlati

• Abilitare l'API di provisioning SCIM in Microsoft Entra ID
• supporto di SCIM in Microsoft Entra ID
• Risoluzione dei problemi degli errori dell'API SCIM di Microsoft Entra ID