Esercitazione: Sviluppare e pianificare il provisioning per un endpoint SCIM in Microsoft Entra ID

  • Articolo

Gli sviluppatori di applicazioni possono utilizzare l'API di gestione utenti SCIM (System for Cross-Domain Identity Management) per abilitare il provisioning automatico di utenti e gruppi tra l'applicazione e Microsoft Entra ID. Questo articolo illustra come creare un endpoint SCIM ed eseguire l'integrazione con il servizio di provisioning di Microsoft Entra. La specifica SCIM offre uno schema utente comune per il provisioning. Se usato con standard di federazione come OpenID Connect o SAML, SCIM offre agli amministratori una soluzione end-to-end basata su standard per la gestione degli accessi.

Provisioning da Microsoft Entra ID a un'app con SCIM

SCIM 2.0 è una definizione standardizzata di due endpoint: un endpoint /Users e un endpoint /Groups. Usa endpoint dell'API REST comuni per creare, aggiornare ed eliminare oggetti. SCIM è costituito da uno schema predefinito per attributi comuni, ad esempio nome del gruppo, nome utente, nome utente, cognome e posta elettronica.

Le app che offrono un'API REST SCIM 2.0 possono ridurre o eliminare le difficoltà associate all'uso di un'API proprietaria di gestione degli utenti. Tutti i client SCIM conformi, ad esempio, sono in grado di inviare un HTTP POST di un oggetto JSON all'endpoint /Users per creare una nuova voce utente. Invece di richiedere un'API leggermente diversa per le stesse azioni di base, le app conformi allo standard SCIM possono sfruttare immediatamente i vantaggi del codice, dei client e degli strumenti preesistenti.

Lo schema dell'oggetto utente standard e le API REST per la gestione definiti in SCIM 2.0 (RFC 7642, 7643 e 7644) facilitano l'integrazione tra provider di identità e app. Gli sviluppatori di applicazioni che creano un endpoint SCIM possono effettuare l'integrazione con qualsiasi client conforme a SCIM senza che siano necessarie operazioni personalizzate.

Per automatizzare il provisioning in un'applicazione, è necessario compilare e integrare un endpoint SCIM accessibile dal servizio di provisioning Microsoft Entra. Usare la procedura seguente per avviare il provisioning di utenti e gruppi nell'applicazione.

  1. Progettare lo schema di utenti e gruppi: identificare gli oggetti e gli attributi dell'applicazione per determinare come vengono mappati allo schema utente e gruppo supportato dall'implementazione di Microsoft Entra SCIM.

  2. Informazioni sull'implementazione di Microsoft Entra SCIM: informazioni su come viene implementato il servizio di provisioning di Microsoft Entra per modellare la gestione e le risposte delle richieste del protocollo SCIM.

  3. Creare un endpoint SCIM: un endpoint deve essere compatibile con SCIM 2.0 per l'integrazione con il servizio di provisioning di Microsoft Entra. Facoltativamente, usare le librerie e gli esempi di codice Microsoft Common Language Infrastructure (CLI) per creare l'endpoint. Questi esempi sono solo per riferimento e test; è consigliabile usarli come dipendenze nell'app di produzione.

  4. Integrare l'endpoint SCIM con il servizio di provisioning Microsoft Entra. Microsoft Entra ID supporta diverse applicazioni di terze parti che implementano SCIM 2.0. Se si usa una di queste app, è possibile automatizzare rapidamente sia il provisioning che il deprovisioning di utenti e gruppi.

  5. [Facoltativo] Pubblicare l'applicazione nella raccolta di applicazioni di Microsoft Entra: è possibile consentire ai clienti di individuare facilmente l'applicazione e configurare facilmente il provisioning.

Diagramma che mostra i passaggi necessari per l'integrazione di un endpoint SCIM con Microsoft Entra ID.

Progettare lo schema degli utenti e dei gruppi

Ogni applicazione richiede attributi diversi per creare un utente o un gruppo. Avviare l'integrazione identificando gli oggetti obbligatori (utenti, gruppi) e gli attributi (nome, manager, titolo di lavoro e così via) necessari per l'applicazione.

Lo standard SCIM definisce uno schema per la gestione di utenti e gruppi.

Lo schema utente principale richiede solo tre attributi (tutti gli altri attributi sono facoltativi):

  • id, identificatore definito dal provider di servizi
  • userName, un identificatore univoco per l'utente (in genere esegue il mapping al nome dell'entità utente di Microsoft Entra)
  • meta, metadati di sola lettura gestiti dal provider di servizi

Oltre allo schema utente principale, lo standard SCIM definisce un'estensione utente aziendale con un modello per estendere lo schema utente in base alle esigenze dell'applicazione.

Ad esempio, se l'applicazione richiede sia l'indirizzo di posta elettronica di un utente che il responsabile dell'utente, usare lo schema principale per raccogliere il messaggio di posta elettronica dell'utente e lo schema utente dell'azienda per raccogliere il manager dell'utente.

Per progettare lo schema, seguire questa procedura:

  1. Elencare gli attributi richiesti dall'applicazione, quindi classificarli come attributi necessari per l'autenticazione, ad esempio loginName e posta elettronica. Gli attributi sono necessari per gestire il ciclo di vita dell'utente (ad esempio, stato/attivo) e tutti gli altri attributi necessari per il funzionamento dell'applicazione (ad esempio, manager, tag).

  2. Controllare se gli attributi sono già definiti nello schema utente principale o schema utente dell'azienda. In caso contrario, è necessario definire un'estensione per lo schema utente che copra gli attributi mancanti. Vedere l'esempio per un'estensione all'utente in modo da consentire il provisioning di un tag utente.

  3. Eseguire il mapping degli attributi SCIM agli attributi utente in Microsoft Entra ID. Se uno degli attributi definiti nell'endpoint SCIM non ha una controparte chiara nello schema utente di Microsoft Entra, guidare l'amministratore tenant a estendere il proprio schema o usare un attributo di estensione come illustrato nell'esempio per la proprietà tags.

La tabella seguente elenca un esempio di attributi obbligatori:

Attributo/esempio di app obbligatorio Attributo SCIM mappato Attributo Microsoft Entra mappato
loginName userName userPrincipalName
firstName name.givenName givenName
lastName name.familyName cognome
workMail emails[type eq "work"].value mail
manager manager manager
tag urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag extensionAttribute1
stato active isSoftDeleted (valore calcolato non archiviato per l'utente)

Il payload JSON seguente illustra uno schema SCIM di esempio:

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

Nota

Oltre agli attributi necessari per l'applicazione, la rappresentazione JSON include anche gli attributi necessari id, externalId e meta.

Consente di classificare tra /User e /Group per eseguire il mapping di qualsiasi attributo utente predefinito in Microsoft Entra ID all'RFC SCIM, vedere come vengono mappati gli attributi di personalizzazione tra Microsoft Entra ID e l'endpoint SCIM.

La tabella seguente elenca un esempio di attributi utente:

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

La tabella seguente elenca un esempio di attributi di gruppo:

Gruppo di Microsoft Entra urn:ietf:params:scim:schemas:core:2.0:Group
displayName displayName
membri membri
objectId ExternalId

Nota

Non è necessario supportare sia gli utenti che i gruppi o tutti gli attributi illustrati qui, ma è solo un riferimento sul modo in cui gli attributi in Microsoft Entra ID vengono spesso mappati alle proprietà nel protocollo SCIM.

Nell'RFC di SCIM sono definiti diversi endpoint. È possibile iniziare con l'endpoint /User e quindi espandersi da questa posizione. La tabella seguente elenca alcuni degli endpoint SCIM:

Endpoint Descrizione
/User Eseguire operazioni CRUD su un oggetto utente.
/Group Eseguire operazioni CRUD su un oggetto gruppo.
/Schemas Il set di attributi supportato da ogni client e provider di servizi può variare. Un provider di servizi potrebbe includere name, title e emails, mentre un altro magari usa name, title e phoneNumbers. L'endpoint degli schemi consente l'individuazione degli attributi supportati.
/Bulk Le operazioni in blocco consentono di eseguire azioni su una grande raccolta di oggetti risorsa in un'unica operazione, come ad esempio aggiornare le appartenenze per un gruppo di grandi dimensioni.
/ServiceProviderConfig Offre informazioni dettagliate sulle funzionalità dello standard SCIM supportate, ad esempio sulle risorse supportate e sul metodo di autenticazione.
/ResourceTypes Specifica i metadati relativi a ogni risorsa.

Nota

Usare l'endpoint /Schemas per supportare attributi personalizzati o se lo schema viene modificato frequentemente perché consente a un client di recuperare automaticamente lo schema più aggiornato. Usare l'endpoint /Bulk per supportare i gruppi.

Informazioni sull'implementazione di Microsoft Entra SCIM

Il servizio di provisioning Microsoft Entra è progettato per supportare un'API di gestione utenti SCIM 2.0.

Importante

L'ultimo aggiornamento del comportamento dell'implementazione SCIM di Microsoft Entra è stato eseguito il 18 dicembre 2018. Per informazioni sulle modifiche, vedere Conformità al protocollo SCIM 2.0 del servizio di provisioning utenti di Microsoft Entra.

Nell'ambito della specifica del protocollo SCIM 2.0, l'applicazione deve supportare i requisiti seguenti:

Requisito Note di riferimento (protocollo SCIM)
Creare utenti e, facoltativamente, anche gruppi Sezione 3.3
Modificare utenti o gruppi con richieste PATCH Sezione 3.5.2. Il supporto assicura che il provisioning di gruppi e utenti venga effettuato con prestazioni elevate.
Recuperare una risorsa nota per un utente o un gruppo creato in precedenza Sezione 3.4.1
Eseguire query su utenti o gruppi Sezione 3.4.2. Per impostazione predefinita, gli utenti vengono recuperati con i propri id e sottoposti a query con i relativi username e externalId, e i gruppi vengono sottoposti a query con displayName.
Il filtro excludedAttributes=members quando si esegue una query sulla risorsa del gruppo Sezione 3.4.2.2
Elenco di supporto per utenti e impaginazione Sezione 3.4.2.4.
Eliminazione temporanea di un utente active=false e ripristino dell'utente active=true L'oggetto utente deve essere restituito in una richiesta se l'utente è attivo o meno. L'unica volta in cui l'utente non deve essere restituito è quando viene eliminato definitivamente dall'applicazione.
Supporto dell'endpoint /Schemas Sezione 7 L'endpoint di individuazione dello schema viene usato per individuare altri attributi.
Accettare un singolo token di connessione per l'autenticazione e l'autorizzazione di Microsoft Entra ID all'applicazione.

Usare le linee guida generali per implementare un endpoint SCIM per garantire la compatibilità con Microsoft Entra ID:

Generale:

  • id è una proprietà obbligatoria per tutte le risorse. In tutte le risposte che restituiscono una risorsa deve essere garantita la presenza di questa proprietà per ogni risorsa, tranne in caso di ListResponse con zero elementi.
  • I valori inviati devono essere archiviati nello stesso formato in cui sono stati inviati. I valori non validi devono essere rifiutati con un messaggio di errore descrittivo e interattivo. Le trasformazioni dei dati non devono verificarsi tra i dati di Microsoft Entra ID e i dati archiviati nell'applicazione SCIM. (ad esempio. Un numero di telefono inviato come 55555555555 non deve essere salvato/restituito come +5 (555) 555-5555)
  • Non è necessario includere l'intera risorsa nella risposta PATCH.
  • Non richiedere una corrispondenza con distinzione tra maiuscole e minuscole sugli elementi strutturali in SCIM, in particolare valori dell'operazione op PATCH, come definito nella sezione 3.5.2. Microsoft Entra ID genera i valori di op come Aggiungi, Sostituisci e Rimuovi.
  • Microsoft Entra ID effettua richieste per recuperare un utente e un gruppo casuali e verificare così che l'endpoint e le credenziali siano validi. Viene eseguita anche come parte del flusso di connessione di test.
  • Supportare HTTPS nell'endpoint SCIM.
  • Gli attributi complessi e multivalore personalizzati sono supportati, ma Microsoft Entra ID non dispone di molte strutture di dati complesse da cui estrarre i dati in questi casi. È possibile eseguire facilmente il mapping degli attributi nome/valore, ma il flusso dei dati a attributi complessi con tre o più attributi secondari non è supportato.
  • I valori dei sottoattributi "tipo" degli attributi complessi multivalenti devono essere unici. Ad esempio, non possono essere presenti due indirizzi di posta elettronica diversi con il sottotipo "lavoro".
  • L'intestazione per tutte le risposte deve essere di tipo content-Type: application/scim+json

Recupero di risorse:

  • La risposta a una richiesta di query/filtro dovrà essere sempre un messaggio ListResponse.
  • Microsoft Entra usa solo gli operatori seguenti: eq, and
  • L'attributo su cui è possibile eseguire query sulle risorse deve essere impostato come attributo corrispondente nell'applicazione. Vedere Personalizzazione dei mapping degli attributi di provisioning utenti.

/Utenti:

  • L'attributo entitlements non è supportato.
  • Tutti gli attributi considerati per l'univocità utente devono essere utilizzabili come parte di una query filtrata. Ad esempio, se l'univocità dell'utente viene valutata sia per userName che per i messaggi di posta elettronica[type eq "work"], un GET to /Users con un filtro deve consentire sia query userName eq "user@contoso.com" che email[type eq "work"].value eq "user@contoso.com".

/Gruppi:

  • I gruppi sono facoltativi, ma sono supportati solo se l'implementazione di SCIM supporta le richieste PATCH.
  • I gruppi devono avere univocità sul valore "displayName" in modo che corrisponda a Microsoft Entra ID e all'applicazione SCIM. L'univocità non è un requisito del protocollo SCIM, ma è un requisito per l'integrazione di un endpoint SCIM con Microsoft Entra ID.

/Schemas (individuazione degli schemi):

  • Richiesta/risposta di esempio
  • L'individuazione dello schema viene usata in determinate applicazioni della raccolta. L'individuazione dello schema è l'unico metodo per aggiungere altri attributi allo schema di un'applicazione SCIM della raccolta esistente. L'individuazione dello schema non è attualmente supportata nell'applicazione SCIM personalizzata non raccolta.
  • Se un valore non è presente, non inviare valori Null.
  • I valori delle proprietà devono essere maiuscole e minuscole (ad esempio, readWrite).
  • Deve restituire una risposta di elenco.
  • Il servizio di provisioning Microsoft Entra effettua la richiesta /schemas quando si salva la configurazione del provisioning. La richiesta viene effettuata anche quando si apre la pagina di provisioning delle modifiche. Gli altri attributi individuati vengono visualizzati ai clienti nei mapping degli attributi nell'elenco degli attributi di destinazione. L'individuazione dello schema comporta solo l'aggiunta di più attributi di destinazione. Gli attributi non vengono rimossi.

Provisioning e deprovisioning utenti

Il diagramma seguente mostra i messaggi inviati da Microsoft Entra ID a un endpoint SCIM per gestire il ciclo di vita di un utente nell'archivio delle identità dell'applicazione.

Diagramma che mostra la sequenza di deprovisioning utente.

Provisioning e deprovisioning di gruppi

Il provisioning e il deprovisioning di gruppi sono facoltativi. Se implementati e abilitati, la figura seguente mostra i messaggi inviati da Microsoft Entra ID a un endpoint SCIM per gestire il ciclo di vita di un gruppo nell'archivio delle identità dell'applicazione. Questi messaggi si differenziano dai messaggi relativi agli utenti in due modi:

  • Le richieste per il recupero di gruppi specificano che l'attributo members deve essere escluso da qualsiasi risorsa fornita in risposta alla richiesta.
  • Le richieste per determinare se un attributo reference ha un determinato valore sono richieste relative all'attributo members.

Il diagramma seguente mostra la sequenza di deprovisioning del gruppo:

Diagramma che mostra la sequenza di deprovisioning del gruppo.

Richieste e risposte del protocollo SCIM

Questo articolo fornisce richieste SCIM di esempio generate dal servizio di provisioning di Microsoft Entra ed esempi di risposte previste. Per ottenere risultati ottimali, è consigliare creare il codice dell'app in modo da gestire tali richieste in questo formato e generare le risposte previste.

Importante

Per comprendere come e quando il servizio di provisioning utenti di Microsoft Entra genera le operazioni descritte nell'esempio, vedere la sezione Cicli di provisioning: Iniziali e incrementali in Funzionamento del provisioning.

Operazioni relative agli utenti

Operazioni relative ai gruppi

Individuazione dello schema

Operazioni relative agli utenti

  • Usare gli attributi userName o emails[type eq "work"] per eseguire query sugli utenti.

Creare un utente

Richiedi

POST /Users

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com"
    }],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName"
    },
    "roles": []
}
Response

HTTP/1.1 201 (Creato)

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "48af03ac28ad4fb88478",
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Ottenere un utente

Richiedi

GET /Users/5d48a0a8e9f04aa38008

Risposta (utente trovato)

HTTP/1.1 200 (OK)

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5d48a0a8e9f04aa38008",
    "externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}
Richiedi

GET /Users/5171a35d82074e068ce2

Risposta (utente non trovato; Il dettaglio non è obbligatorio, solo lo stato).

HTTP/1.1 404 Non trovato

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

Ottenere un utente tramite query

Richiedi

GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee"

Response

HTTP/1.1 200 (OK)

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "id": "2441309d85324e7793ae",
        "externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
        "meta": {
            "resourceType": "User",
            "created": "2018-03-27T19:59:26.000Z",
            "lastModified": "2018-03-27T19:59:26.000Z"
            
        },
        "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Ottenere un utente tramite query, zero risultati

Richiedi

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

Response

HTTP/1.1 200 (OK)

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

Aggiornare un utente [proprietà multivalore]

Richiedi

PATCH /Users/6764549bef60420686bc HTTP/1.1

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

HTTP/1.1 200 (OK)

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

Aggiornare un utente [proprietà a valore singolo]

Richiedi

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

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

HTTP/1.1 200 (OK)

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

Disabilitare un utente

Richiedi

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

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

Eliminazione di un utente.

Richiedi

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

Response

HTTP/1.1 204 (Nessun contenuto)

Operazioni relative ai gruppi

  • I gruppi vengono creati con un elenco di membri vuoti.
  • Usare l'attributo displayName per eseguire query sui gruppi.
  • La richiesta PATCH di aggiornamento del gruppo dovrà restituire una risposta con codice HTTP 204 (Nessun contenuto). Non è consigliabile restituire un corpo con un elenco di tutti i membri.
  • Non è necessario supportare la restituzione di tutti i membri del gruppo.

Crea gruppo

Richiedi

POST /Groups HTTP/1.1

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

HTTP/1.1 201 (Creato)

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

Ottenere un gruppo

Richiedi

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

Response

HTTP/1.1 200 (OK)

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

Ottenere un gruppo in base a displayName

Richiedi

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

Response

HTTP/1.1 200 (OK)

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

Aggiornare un gruppo [attributi non relativi ai membri]

Richiedi

PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1

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

HTTP/1.1 204 (Nessun contenuto)

Aggiornare un gruppo [aggiungere membri]

Richiedi

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

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

HTTP/1.1 204 (Nessun contenuto)

Aggiornare un gruppo [rimuovere membri]

Richiedi

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

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

HTTP/1.1 204 (Nessun contenuto)

Eliminare un gruppo

Richiedi

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Response

HTTP/1.1 204 (Nessun contenuto)

Individuazione dello schema

Individuare lo schema

Richiedi

GET /Schemas

Response

HTTP/1.1 200 (OK)

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

Requisiti di sicurezza

Versioni del protocollo TLS

L'unica versione del protocollo accettabile è TLS 1.2. Non è consentita alcuna altra versione SSL/TLS.

  • Le chiavi RSA devono essere di almeno 2.048 bit.
  • Le chiavi ECC devono essere di almeno 256 bit ed essere generate con una curva ellittica approvata.

Lunghezza delle chiavi

Tutti i servizi devono usare certificati X.509 generati con chiavi crittografiche di lunghezza sufficiente, come illustrato di seguito.

Pacchetti di crittografia

Tutti i servizi devono essere configurati per usare i pacchetti di crittografia seguenti, nell'ordine esatto in cui sono specificati nell'esempio. Se si ha solo un certificato RSA, l'installazione dei pacchetti di crittografia ECDSA non avrà alcun effetto.

Livello minimo dei pacchetti di crittografia TLS 1.2:

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

Intervalli di indirizzi IP

Il servizio di provisioning Microsoft Entra opera attualmente con gli intervalli IP per Microsoft Entra ID, come indicato di seguito. È possibile aggiungere gli intervalli IP elencati sotto il tag AzureActiveDirectory per consentire il traffico dal servizio di provisioning Microsoft Entra nell'applicazione. Sarà necessario esaminare attentamente l'elenco di intervalli di indirizzi IP per verificare gli indirizzi calcolati. Un indirizzo come '40.126.25.32' può essere rappresentato nell'elenco di intervalli di indirizzi IP come '40.126.0.0/18'. È anche possibile recuperare a livello di codice l'elenco di intervalli di indirizzi IP usando l'API seguente.

Microsoft Entra ID supporta anche una soluzione basata su agente per fornire connettività alle applicazioni nelle reti private (locale, ospitata in Azure, ospitata in AWS e così via). I clienti possono distribuire un agente leggero, che fornisce connettività a Microsoft Entra ID senza aprire porte in ingresso, in un server nella propria rete privata. Altre informazioni qui.

Creare un endpoint SCIM

Dopo aver progettato lo schema e aver compreso l'implementazione SCIM di Microsoft Entra, si può iniziare a sviluppare l'endpoint SCIM. Anziché iniziare da zero e creare autonomamente l'intera implementazione, è possibile usare molte librerie SCIM open source pubblicate dalla community SCIM.

Per indicazioni su come creare un endpoint SCIM, inclusi esempi, vedere Sviluppare un endpoint SCIM di esempio.

L'esempio di codice di riferimento di .NET Core open source pubblicato dal team di provisioning di Microsoft Entra è una risorsa di questo tipo che può iniziare a sviluppare. Compilare un endpoint SCIM, quindi testarlo eseguendo le richieste/risposte di esempio fornite.

Nota

Il codice di riferimento è utile per iniziare a creare l'endpoint SCIM e viene fornito "COSÌ COM'È". Sono benvenuti i contributi della community per la compilazione e la gestione del codice.

La soluzione è costituita da due progetti: Microsoft.SCIM e Microsoft.SCIM.WebHostSample.

Il progetto Microsoft.SCIM è la libreria che definisce i componenti del servizio Web conforme alla specifica SCIM. Dichiara l'interfaccia Microsoft.SCIM.IProvider e le richieste vengono convertite in chiamate ai metodi del provider, che saranno programmati per eseguire operazioni su un archivio identità.

Scomposizione: una richiesta convertita in chiamate ai metodi del provider

Il progetto Microsoft.SCIM.WebHostSample è un'applicazione Web ASP.NET Core basata sul modello Vuoto. Ciò consente di distribuire il codice di esempio come codice autonomo, ospitato in contenitori o in Internet Information Services. Viene implementata anche l'interfaccia Microsoft.SCIM.IProvider, mantenendo le classi in memoria come archivio identità di esempio.

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

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

Creazione di un endpoint SCIM personalizzato

L'endpoint SCIM deve avere un indirizzo HTTP e un certificato di autenticazione server la cui autorità di certificazione radice è uno dei nomi seguenti:

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

.NET Core SDK include un certificato di sviluppo HTTPS usato durante lo sviluppo. Il certificato viene installato come parte dell'esperienza di prima esecuzione. A seconda di come viene eseguita, l'applicazione Web ASP.NET Core è in ascolto di una porta diversa:

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

Per altre informazioni su HTTPS in ASP.NET Core, usare il collegamento seguente: Imponi HTTPS in ASP.NET Core

Gestione dell'autenticazione dell'endpoint

Le richieste dal servizio di provisioning Microsoft Entra includono un token di connessione OAuth 2.0. Un server di autorizzazione rilascia il token di connessione. Microsoft Entra ID è un esempio di server di autorizzazione attendibile. Configurare il servizio di provisioning di Microsoft Entra per l'uso di uno dei token seguenti:

  • Token di connessione di lunga durata. Se l'endpoint SCIM richiede un token di connessione OAuth da un'autorità di certificazione diversa da Microsoft Entra ID, copiare il token di connessione OAuth nel campo Token segreto facoltativo. In un ambiente di sviluppo è possibile usare il token di test dall'endpoint /scim/token. I token di test non devono essere usati negli ambienti di produzione.

  • Token di connessione Microsoft Entra. Se il campo Token segreto viene lasciato vuoto, Microsoft Entra ID include un token di connessione OAuth emesso da Microsoft Entra ID con ogni richiesta. Le app che usano Microsoft Entra ID come provider di identità possono convalidare questo token rilasciato da Microsoft Entra ID.

    • L'applicazione che riceve le richieste deve convalidare l'autorità emittente del token come Microsoft Entra ID per un tenant Microsoft Entra previsto.
    • Un'attestazione iss identifica l'autorità emittente del token. Ad esempio: "iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/". In questo esempio, l'indirizzo di base del valore dell'attestazione, https://sts.windows.net identifica Microsoft Entra ID come autorità di certificazione, mentre il segmento di indirizzo relativo aaaabbbbbb-0000-cccc-1111-dddd2222eeee è un identificatore univoco del tenant di Microsoft Entra per cui è stato rilasciato il token.
    • Il gruppo di destinatari per un token è l'ID applicazione per l'applicazione nella raccolta. Le applicazioni registrate in un singolo tenant ricevono la stessa attestazione iss con richieste SCIM. L'ID applicazione per tutte le app personalizzate è 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Il token generato da Microsoft Entra ID deve essere usato solo per i test. Non deve essere usato negli ambienti di produzione.

Nel codice di esempio, le richieste vengono autenticate usando il pacchetto Microsoft.AspNetCore.Authentication.JwtBearer. Il codice seguente impone l'autenticazione delle richieste per qualsiasi endpoint del servizio con il token di connessione rilasciato da Microsoft Entra ID per un tenant specificato:

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

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

Il codice di esempio usa ambienti ASP.NET Core per modificare le opzioni di autenticazione durante la fase di sviluppo e abilitare l'uso di un token autofirmato.

Per altre informazioni su più ambienti in ASP.NET Core, vedere Usare più ambienti in ASP.NET Core.

Il codice seguente impone l'autenticazione delle richieste per qualsiasi endpoint del servizio con un token di connessione firmato con una chiave personalizzata:

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

Inviare una richiesta GET al controller dei token per ottenere un token di connessione valido. Il metodo GenerateJSONWebToken è responsabile della creazione di un token corrispondente ai parametri configurati per lo sviluppo:

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

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

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

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

Gestione del provisioning e del deprovisioning di utenti

Esempio 1. Eseguire query sul servizio per trovare un utente corrispondente

Microsoft Entra ID esegue query nel servizio per trovare un utente con valore dell'attributo externalId corrispondente al valore dell'attributo mailNickname di un utente in Microsoft Entra ID. La query viene espressa come richiesta HTTP (Hypertext Transfer Protocol), come questo esempio, dove jyoung è un esempio di mailNickname di un utente in Microsoft Entra ID.

Nota

Questo è solo un esempio. Non tutti gli utenti avranno un attributo mailNickname e il valore di un utente potrebbe non essere univoco nella directory. L'attributo usato per la corrispondenza (che in questo caso è externalId), inoltre, è configurabile nei mapping degli attributi di Microsoft Entra.

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

Nel codice di esempio, la richiesta viene convertita in una chiamata al metodo QueryAsync del provider del servizio. Ecco la firma del metodo:

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

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

Nella query di esempio, per un utente con un determinato valore dell'attributo externalId, i valori degli argomenti passati al metodo QueryAsync sono i seguenti:

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

Esempio 2. Effettuare il provisioning di un utente

Se la risposta a una query all'endpoint SCIM per un utente con un valore di attributo externalId corrispondente al valore dell'attributo mailNickname di un utente non restituisce alcun utente, Microsoft Entra ID richiede che il servizio effettui il provisioning di un utente corrispondente a quello in Microsoft Entra ID. Di seguito è riportato un esempio di richiesta di questo tipo:

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

Nel codice di esempio, la richiesta viene convertita in una chiamata al metodo CreateAsync del provider del servizio. Ecco la firma del metodo:

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

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

In una richiesta di provisioning utenti, il valore dell'argomento della risorsa è un'istanza della classe Microsoft.SCIM.Core2EnterpriseUser. Questa classe viene definita nella libreria Microsoft.SCIM.Schemas. Se la richiesta di provisioning dell'utente ha esito positivo, l'implementazione del metodo dovrebbe restituire un'istanza della classe Microsoft.SCIM.Core2EnterpriseUser. Il valore della proprietà Identifier viene impostato sull'identificatore univoco dell'utente appena sottoposto a provisioning.

Esempio 3. Eseguire query sullo stato corrente di un utente

Microsoft Entra ID richiede lo stato corrente dell'utente specificato dal servizio con una richiesta, ad esempio:

GET ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...

Nel codice di esempio, la richiesta viene convertita in una chiamata al metodo RetrieveAsync del provider del servizio. Ecco la firma del metodo:

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

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

Nell'esempio di una richiesta per recuperare lo stato corrente di un utente, i valori delle proprietà dell'oggetto fornito come valore dell'argomento parametri sono analoghi ai seguenti:

  • Identificatore: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
  • SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Esempio 4. Eseguire query sul valore di un attributo di riferimento da aggiornare

Microsoft Entra ID controlla il valore dell'attributo corrente nell'archivio delle identità prima di aggiornarlo. Tuttavia, solo l'attributo manager è il primo controllo per gli utenti. Ecco un esempio di richiesta per determinare se l'attributo manager di un oggetto utente ha attualmente un determinato valore: nel codice di esempio la richiesta viene convertita in una chiamata al metodo QueryAsync del provider del servizio. Il valore delle proprietà dell'oggetto fornito come valore dell'argomento parameters è analogo al seguente:

  • parameters.AlternateFilters.Count: 2
  • parameters.AlternateFilters.ElementAt(x).AttributePath: "ID"
  • parameters.AlternateFilters.ElementAt(x).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(x).ComparisonValue: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
  • parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
  • parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(y).ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
  • parameters.RequestedAttributePaths.ElementAt(0): "ID"
  • parameters.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Il valore dell'indice x può essere 0 e il valore dell'indice y può essere 1. In alternativa, il valore di x può essere 1 e il valore di y può essere 0. Dipende dall'ordine delle espressioni del parametro di query di filtro.

Esempio 5. Richiedere da Microsoft Entra ID a un endpoint SCIM per aggiornare un utente

Ecco un esempio di richiesta da Microsoft Entra ID a un endpoint SCIM per aggiornare un utente:

PATCH ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
    "schemas": 
    [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":
    [
      {
        "op":"Add",
        "path":"manager",
        "value":
          [
            {
              "$ref":"http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
              "value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}]}]}

Nel codice di esempio, la richiesta viene convertita in una chiamata al metodo UpdateAsync del provider del servizio. Ecco la firma del metodo:

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

Task UpdateAsync(IRequest<IPatch> request);

Nell'esempio di una richiesta per l'aggiornamento di un utente, i valori delle proprietà dell'oggetto fornito come valore dell'argomento patch sono analoghi ai seguenti:

Argomento Valore
ResourceIdentifier.Identifier "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
ResourceIdentifier.SchemaIdentifier urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
(PatchRequest as PatchRequest2).Operations.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName OperationName.Add
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath Manager
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 00aa00aa-bb11-cc22-dd33-44ee44ee44ee

Esempio 6. Effettuare il deprovisioning di un utente

Per effettuare il deprovisioning di un utente da un archivio identità anteriore da un endpoint SCIM, Microsoft Entra ID invia una richiesta, ad esempio:

DELETE ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...

Nel codice di esempio, la richiesta viene convertita in una chiamata al metodo DeleteAsync del provider del servizio. Ecco la firma del metodo:

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

Task DeleteAsync(IRequest<IResourceIdentifier> request);

Nell'esempio di richiesta per il deprovisioning di un utente, l'oggetto specificato come valore dell'argomento resourceIdentifier ha i valori delle proprietà seguenti.

  • ResourceIdentifier.Identifier: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
  • ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Integrare l'endpoint SCIM con il servizio di provisioning Microsoft Entra

È possibile configurare Microsoft Entra ID per il provisioning automatico di utenti e gruppi assegnati nelle applicazioni che implementano un profilo specifico del protocollo SCIM 2.0. Le specifiche del profilo sono documentate in Informazioni sull'implementazione di Microsoft Entra SCIM.

Verificare la conformità ai requisiti sopra riportati con il provider dell'applicazione o consultando la documentazione fornita dal provider.

Importante

L'implementazione SCIM di Microsoft Entra è basata sul servizio di provisioning utenti di Microsoft Entra, progettato per mantenere gli utenti costantemente sincronizzati tra Microsoft Entra e l'applicazione di destinazione, e implementa un set molto specifico di operazioni standard. È importante comprendere questi comportamenti per comprendere il comportamento del servizio di provisioning Microsoft Entra. Per altre informazioni, vedere la sezione Cicli di provisioning: iniziali e incrementali in Funzionamento del provisioning.

Introduzione

Suggerimento

La procedura descritta in questo articolo può variare leggermente in base al portale di partenza.

Le applicazioni che supportano il profilo SCIM descritto in questo articolo possono essere connesse ad Microsoft Entra ID usando la funzionalità "Applicazione non nella raccolta" nella raccolta di applicazioni di Microsoft Entra. Dopo la connessione, Microsoft Entra ID esegue un processo di sincronizzazione. Il processo viene eseguito ogni 40 minuti. Il processo esegue una query sull'endpoint SCIM dell'applicazione per gli utenti e i gruppi assegnati e li crea o li modifica in base ai dettagli dell'assegnazione.

Per connettere un'applicazione che supporta SCIM:

  1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come amministratore applicazione.

  2. Passare a Identità>Applicazioni>Applicazioni aziendali.

  3. Verrà visualizzato un elenco di tutte le app configurate, incluse le app aggiunte dalla raccolta.

  4. Selezionare + Nuova applicazione>+ Crea un'applicazione personalizzata.

  5. Immettere un nome per l'applicazione, scegliere l'opzione "Integrare qualsiasi altra applicazione non trovata nella raccolta" e selezionare Aggiungi per creare un oggetto app. La nuova app verrà aggiunta all'elenco delle applicazioni aziendali e verrà visualizzata la schermata di gestione dell'app.

    Lo screenshot seguente mostra la raccolta di applicazioni Microsoft Entra:

    Screenshot che mostra la raccolta di applicazioni Microsoft Entra.

  6. Nella schermata di gestione dell'app selezionare Provisioning nel pannello sinistro.

  7. Nel menu Modalità di provisioning selezionare Automatica.

    Lo screenshot seguente mostra la configurazione delle impostazioni di provisioning nell'interfaccia di amministrazione di Microsoft Entra:

    Screenshot della pagina di provisioning delle app nell'interfaccia di amministrazione di Microsoft Entra.

  8. Nel campo URL tenant immettere l'URL dell'endpoint SCIM dell'applicazione. Esempio: https://api.contoso.com/scim/

  9. Se l'endpoint SCIM richiede un token di connessione OAuth da un'autorità di certificazione diversa da Microsoft Entra ID, copiare il token di connessione OAuth nel campo Token segreto facoltativo. Se questo campo viene lasciato vuoto, Microsoft Entra ID include un token di connessione OAuth emesso da Microsoft Entra ID con ogni richiesta. Le app che usano Microsoft Entra ID come provider di identità possono convalidare questo token rilasciato da Microsoft Entra ID.

    Nota

    Non è consigliabile lasciare vuoto questo campo e usare un token generato da Microsoft Entra ID. Questa opzione è disponibile principalmente a scopo di test.

  10. Selezionare Test connessione per fare in modo che Microsoft Entra ID tenti di connettersi all'endpoint SCIM. Se il tentativo non riesce, verranno visualizzate le informazioni sull'errore.

    Nota

    Test connessione esegue una query sull'endpoint SCIM per un utente che non esiste, usando un GUID casuale come proprietà corrispondente selezionata nella configurazione di Microsoft Entra. La risposta corretta prevista è HTTP 200 OK con un messaggio ListResponse SCIM vuoto.

  11. Se il tentativo di connessione all'applicazione ha esito positivo, selezionare Salva per salvare le credenziali di amministratore.

  12. Nella sezione Mapping sono disponibili due set di mapping degli attributi selezionabili: uno per gli oggetti utente e uno per gli oggetti gruppo. Selezionare ognuno di essi per esaminare gli attributi sincronizzati da Microsoft Entra ID all'app. Gli attributi selezionati come proprietà corrispondenti vengono usati per trovare le corrispondenze con gli utenti e i gruppi nell'app per le operazioni di aggiornamento. Selezionare Salva per eseguire il commit delle modifiche.

    Nota

    Facoltativamente, è possibile disattivare la sincronizzazione degli oggetti gruppo disabilitando il mapping relativo ai gruppi.

  13. In Impostazioni il campo Ambito definisce gli utenti e i gruppi che devono essere sincronizzati. Selezionare Sincronizza solo utenti e gruppi assegnati (scelta consigliata) per sincronizzare solo gli utenti e i gruppi assegnati nella scheda Utenti e gruppi.

  14. Al termine della configurazione, impostare Stato del provisioning su Sì.

  15. Selezionare Salva per avviare il servizio di provisioning di Microsoft Entra.

  16. Se si sincronizzano solo utenti e gruppi assegnati (scelta consigliata), selezionare la scheda Utenti e gruppi. Assegnare quindi gli utenti o i gruppi da sincronizzare.

Dopo l'avvio del ciclo iniziale, è possibile selezionare la scheda Log di provisioning nel pannello sinistro per monitorare lo stato di avanzamento, visualizzando tutte le azioni eseguite dal servizio di provisioning sull'app. Per altre informazioni sulla lettura dei log di provisioning di Microsoft Entra, vedere Creazione di report sul provisioning automatico degli account utente.

Nota

Il ciclo iniziale richiede più tempo rispetto alle sincronizzazioni successive, che vengono eseguite circa ogni 40 minuti fintanto che il servizio è in esecuzione.

Se si sta creando un'applicazione usata da più tenant, renderla disponibile nella raccolta di applicazioni Microsoft Entra. È facile per le organizzazioni individuare l'applicazione e configurare il provisioning. Pubblicare l'app nella raccolta di Microsoft Entra e rendere il provisioning disponibile ad altri è semplice. Consultare i passaggi qui Microsoft collabora con l'utente per integrare l'applicazione nella raccolta, testare l'endpoint e rilasciare documentazione per i clienti.

Usare l'elenco di controllo per eseguire rapidamente l'onboarding dell'applicazione e i clienti hanno un'esperienza di distribuzione uniforme. Queste informazioni sono raccolte durante l'onboarding nella raccolta.

  • Supportare un endpoint SCIM 2.0 per gli utenti e per i gruppi (ne è necessario uno solo, ma è consigliabile usare entrambi)
  • Supportare almeno 25 richieste al secondo per tenant per assicurare che il provisioning e il deprovisioning di utenti e gruppi vengano effettuati senza ritardi (obbligatorio)
  • Stabilire i contatti di progettazione e supporto tecnico per assistere i clienti dopo l'onboarding nella raccolta (obbligatorio)
  • Usare 3 credenziali di test non in scadenza per l'applicazione (obbligatorio)
  • Supportare la concessione del codice di autorizzazione OAuth o un token di lunga durata come descritto nell'esempio (obbligatorio)
  • Le app OIDC devono avere almeno 1 ruolo (personalizzato o predefinito) definito
  • Stabilire un punto di contatto per la progettazione e il supporto tecnico per supportare i clienti dopo l'onboarding nella raccolta (obbligatorio)
  • Supporto dell'individuazione dello schema (obbligatorio)
  • Supportare l'aggiornamento di più appartenenze ai gruppi con una singola operazione PATCH
  • Documentare pubblicamente l'endpoint SCIM

La specifica SCIM non definisce uno schema specifico di SCIM per l'autenticazione e l'autorizzazione e si basa sull'uso di standard di settore esistenti.

Metodo di autorizzazione Vantaggi Svantaggi Supporto tecnico
Nome utente e password (non consigliato o supportato da Microsoft Entra ID) Facile da implementare Non sicuro. La pa$$word è irrilevante. Non supportato per le nuove app della raccolta o non della raccolta.
Token di connessione di lunga durata I token di lunga durata non richiedono che sia presente un utente. Possono essere usati facilmente dagli amministratori durante la configurazione del provisioning. I token di lunga durata possono essere difficili da condividere con un amministratore senza usare metodi non sicuri come la posta elettronica. Supportato sia per le app della raccolta che per quelle non nella raccolta.
Concessione del codice di autorizzazione OAuth I token di accesso hanno una durata più breve rispetto alle password e hanno un meccanismo di aggiornamento automatico che i token di connessione di lunga durata non hanno. Durante l'autorizzazione iniziale deve essere presente un utente reale e questo offre un livello di affidabilità aggiuntivo. Deve essere presente un utente. Se l'utente lascia l'organizzazione, il token non è valido ed è necessario completare nuovamente l'autorizzazione. È supportato per le app della raccolta ma non per quelle non della raccolta. Tuttavia, è possibile fornire un token di accesso nell'interfaccia utente come token segreto a scopo di test a breve termine. Il supporto per la concessione di codice OAuth in una raccolta è incluso nel backlog, oltre al supporto per gli URL di autenticazione/token configurabili nell'app della raccolta.
Concessione di credenziali client OAuth I token di accesso hanno una durata più breve rispetto alle password e hanno un meccanismo di aggiornamento automatico che i token di connessione di lunga durata non hanno. Sia la concessione del codice di autorizzazione che la concessione delle credenziali client creano lo stesso tipo di token di accesso, quindi il passaggio tra questi metodi è trasparente per l'API. Il provisioning può essere automatizzato e i nuovi token possono essere richiesti automaticamente senza interazione dell'utente. È supportato per le app della raccolta ma non per quelle non della raccolta. Tuttavia, è possibile fornire un token di accesso nell'interfaccia utente come token segreto a scopo di test a breve termine. Il supporto per la concessione di credenziali client OAuth in una raccolta è incluso nel backlog.

Nota

Non è consigliabile lasciare vuoto il campo del token nell'interfaccia utente dell'app personalizzata per la configurazione del provisioning di Microsoft Entra. Il token generato è disponibile principalmente a scopo di test.

Flusso di concessione del codice OAuth

Il servizio di provisioning supporta la concessione del codice di autorizzazione e, dopo aver inviato la richiesta di pubblicazione dell'app nella raccolta, il team collaborerà con l'utente per raccogliere le informazioni seguenti:

  • URL di autorizzazione, un URL dal client per ottenere l'autorizzazione dal proprietario della risorsa tramite il reindirizzamento dell'agente utente. L'utente viene reindirizzato a questo URL per l'autorizzazione dell'accesso.

  • URL di scambio di token, un URL del client per scambiare una concessione di autorizzazione per un token di accesso, in genere con l'autenticazione client.

  • ID client, il server di autorizzazione rilascia al client registrato un identificatore client, ovvero una stringa univoca che rappresenta le informazioni di registrazione fornite dal client. L'identificatore client non è un segreto. Viene esposto al proprietario della risorsa e non deve essere usato da solo per l'autenticazione client.

  • Segreto client, un segreto generato dal server di autorizzazione che deve essere un valore univoco noto solo al server di autorizzazione.

Nota

L'URL di autorizzazione e l'URL di scambio di token non sono attualmente configurabili per ogni tenant.

Nota

OAuth v1 non è supportato a causa dell'esposizione del segreto client. OAuth v2 è supportato.

Quando si usa il flusso di concessione del codice OAuth, è necessario supportare un modello in cui ogni cliente invierà il proprio ID client e il segreto client durante la configurazione di un'istanza di provisioning. Non è supportata una singola coppia ID client/Segreto client a livello di app.

Come configurare il flusso di concessione del codice OAuth

  1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come amministratore applicazione.

  2. Passare a Identità>Applicazioni>Applicazioni aziendali>Applicazione>Provisioning e selezionare Autorizza.

  3. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come amministratore applicazione.

  4. Passare a Identità>Applicazioni>Applicazioni aziendali.

  5. Selezionare l'applicazione e passare a Provisioning.

  6. Seleziona Autorizza.

    1. Gli utenti vengono reindirizzati all'URL di autorizzazione (pagina di accesso per l'app di terze parti).

    2. L'amministratore fornisce le credenziali all'applicazione di terze parti.

    3. L'app di terze parti reindirizza l'utente e fornisce il codice di concessione

    4. Il servizio di provisioning chiama l'URL del token e fornisce il codice di concessione. L'applicazione di terze parti risponde con il token di accesso, il token di aggiornamento e la data di scadenza

  7. Quando inizia il ciclo di provisioning, il servizio controlla se il token di accesso corrente è valido e lo scambia con un nuovo token, se necessario. Il token di accesso viene fornito in ogni richiesta effettuata all'app e prima di ogni richiesta ne viene verificata la validità.

Nota

Anche se non è possibile configurare OAuth nelle applicazioni non della raccolta, è possibile generare manualmente un token di accesso dal server di autorizzazione e immetterlo come token segreto in un'applicazione non raccolta. In questo modo è possibile verificare la compatibilità del server SCIM con il servizio di provisioning Microsoft Entra prima dell'onboarding nella raccolta di app, che supporta la concessione del codice OAuth.

Token di connessione OAuth di lunga durata: Se l'applicazione non supporta il flusso di concessione del codice di autorizzazione OAuth, generare invece un token di connessione OAuth di lunga durata che un amministratore può usare per configurare l'integrazione del provisioning. Il token deve essere perpetuo, altrimenti il processo di provisioning viene messo in quarantena alla scadenza del token.

Per altri metodi di autenticazione e autorizzazione, comunicare questa esigenza in UserVoice.

Per favorire la conoscenza e la richiesta dell'integrazione congiunta, è consigliabile aggiornare la documentazione esistente e promuovere l'integrazione nei canali di marketing. È consigliabile completare l'elenco di controllo seguente per supportare il lancio:

  • Assicurarsi che i team di supporto tecnico e di vendita siano consapevoli, pronti, e che possano parlare con le funzionalità di integrazione. Informare i team, fornire loro domande frequenti e includere l'integrazione nei materiali di vendita.
  • Creare un post di blog o un comunicato stampa che descriva l'integrazione congiunta, i relativi vantaggi e come iniziare a usarla. Esempio: Imprivata e Microsoft Entra Press Release
  • Sfruttare i social media, come Twitter, Facebook o LinkedIn, per promuovere l'integrazione presso i clienti. Assicurarsi di includere @Microsoft Entra ID per consentire a Microsoft di fare il retweet del post. Esempio: Post di X imprivata
  • Creare o aggiornare le pagine di marketing o il sito Web (ad esempio la pagina di integrazione, la pagina dei partner, la pagina dei prezzi e così via) per includere la disponibilità dell'integrazione congiunta. Esempio: Pagina di integrazione di Pingboard, pagina di integrazione di Smartsheet, pagina dei prezzi di Monday.com
  • Creare un articolo del centro assistenza o documentazione tecnica che illustri ai clienti come iniziare a usare l'integrazione. Esempio: Integrazione di Envoy + Microsoft Entra.
  • Avvisare i clienti della nuova integrazione tramite la comunicazione ai clienti (newsletter mensili, campagne di posta elettronica, note sulla versione del prodotto).

Passaggi successivi

Sviluppare un endpoint SCIM di esempioAutomatizzare il provisioning e il deprovisioning utenti nelle app SaaSPersonalizzare i mapping degli attributi per il provisioning utentiScrittura di espressioni per il mapping degli attributiFiltri di ambito per il provisioning degli utentiNotifiche di provisioning degli accountElenco di esercitazioni su come integrare app SaaS