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

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 descrive come creare un endpoint SCIM e integrarlo con il servizio di provisioning Microsoft Entra. La specifica SCIM offre uno schema utente comune per il provisioning. Se usato con standard federativo come SAML o OpenID Connessione, SCIM offre agli amministratori una soluzione end-to-end basata su standard per la gestione degli accessi.

Provisioning from Microsoft Entra ID to an app with SCIM

SCIM 2.0 è una definizione standardizzata di due endpoint: un /Users endpoint e un /Groups endpoint. 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. Ad esempio, qualsiasi client SCIM conforme sa come creare 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 il modo in cui eseguono il mapping allo schema utente e gruppo supportato dall'implementazione di Microsoft Entra SCIM.

  2. Comprendere l'implementazione di Microsoft Entra SCIM: comprendere 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. Come opzione, usare librerie e esempi di codice di Microsoft Common Language Infrastructure (CLI) per compilare 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: consente ai clienti di individuare facilmente l'applicazione e configurare facilmente il provisioning.

Diagram that shows the required steps for integrating a SCIM endpoint with 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 necessari (utenti, gruppi) e 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 per soddisfare le esigenze dell'applicazione.

Ad esempio, se l'applicazione richiede sia la 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 aziendale per raccogliere il responsabile dell'utente.

Per progettare lo schema, seguire questa procedura:

  1. Elencare gli attributi richiesti dall'applicazione, quindi classificare 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 nello schema utente aziendale . In caso contrario, è necessario definire un'estensione per lo schema utente che copre gli attributi mancanti. Vedere l'esempio per un'estensione all'utente per consentire il provisioning di un utente tag.

  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 tags proprietà .

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/2819c223-7f76-453a-919d-413861904646"
   }
}   

Nota

Oltre agli attributi necessari per l'applicazione, la rappresentazione JSON include anche gli attributi , externalIde meta necessariid.

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 personalizzare gli attributi vengono mappati 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
surname name.familyName
telephone-Number phoneNumbers[type eq "work"].value
user-PrincipalName userName

La tabella seguente elenca un esempio di attributi di gruppo:

Gruppo 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 bulk consentono di eseguire operazioni su una raccolta di grandi dimensioni di oggetti risorsa in un'unica operazione, ad esempio aggiornare le appartenenze per un gruppo di grandi dimensioni.
/ServiceProviderConfig Fornisce informazioni dettagliate sulle funzionalità dello standard SCIM supportate, ad esempio le risorse supportate e il 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

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

All'interno della specifica del protocollo SCIM 2.0, l'applicazione deve supportare questi requisiti:

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 id i relativi e sottoposti a query con username i relativi e externalIde i gruppi vengono sottoposti a query con displayName.
Filter excludedAttributes=members durante l'esecuzione di 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 che 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. Ogni risposta che restituisce una risorsa deve garantire che ogni risorsa abbia questa proprietà, ad eccezione di ListResponse 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 i valori dell'operazione PATCHop, come definito nella sezione 3.5.2. Microsoft Entra ID genera i valori di op come Add, Replace e Remove.
  • Microsoft Entra ID effettua richieste per recuperare un utente e un gruppo casuali per assicurarsi che l'endpoint e le credenziali siano validi. Viene eseguita anche come parte del flusso di test Connessione ion.
  • 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 di sottoattribute secondario "type" di attributi complessi multivalore devono essere univoci. Ad esempio, non possono essere presenti due indirizzi di posta elettronica diversi con il sottotipo "work".
  • 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-only usa gli operatori seguenti: eq, and
  • L'attributo su cui è possibile eseguire una query sulle risorse deve essere impostato come attributo corrispondente nell'applicazione, vedere Personalizzazione dei mapping degli attributi di provisioning utenti.

/Gli 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 userName eq "user@contoso.com" che email[type eq "work"].value eq "user@contoso.com" query.

/Gruppi:

  • I gruppi sono facoltativi, ma sono supportati solo se l'implementazione SCIM supporta le richieste PATCH .
  • I gruppi devono avere univocità sul valore "displayName" in modo che corrisponda all'ID Microsoft Entra 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 dello schema):

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

Diagram that shows the user deprovisioning sequence.

Provisioning e deprovisioning di gruppi

Il provisioning e il deprovisioning di gruppi sono facoltativi. Se implementata e abilitata, 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:

Diagram that shows the group deprovisioning sequence.

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 userName gli attributi 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_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@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_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@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_feed3ace-693c-4e5a-82e2-694be1b39934",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_22370c1a-9012-42b2-bf64-86099c2a1c22@testuser.com",
        "type": "work",
        "primary": true
    }]
}
Richiedi

GET /Users/5171a35d82074e068ce2

Risposta (utente non trovato. Il dettaglio non è obbligatorio, solo 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_dfeef4c5-5681-4387-b016-bdf221e82081"

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_dfeef4c5-5681-4387-b016-bdf221e82081",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_91b67701-697b-46de-b864-bd0bbe4f99c1@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_fbb9dda4-fcde-4f98-a68b-6c5599e17c27",
    "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_49dc1090-aada-4657-8434-4995c25a00f7@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 l'uso delle suite di crittografia seguenti, nell'ordine esatto specificato nell'esempio. Se si dispone solo di un certificato RSA, le suite di crittografia ECDSA installate non hanno 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 MICROSOFT Entra ID per consentire il traffico dal servizio di provisioning Microsoft Entra nell'applicazione. È necessario esaminare attentamente l'elenco di intervalli IP per 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 (locali, ospitate in Azure, ospitate in AWS e così via). I clienti possono distribuire un agente leggero, che fornisce connettività all'ID Entra Di Microsoft 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, è possibile iniziare a sviluppare l'endpoint SCIM. Invece di iniziare da zero e compilare completamente l'implementazione autonomamente, è possibile affidarsi a 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 .NET Core open source pubblicato dal team di provisioning di Microsoft Entra è una risorsa di questo tipo che può iniziare lo sviluppo. Compilare un endpoint SCIM, quindi testarlo. Usare la raccolta di test Postman forniti come parte del codice di riferimento o eseguire le richieste/risposte di esempio fornite.

Nota

Il codice di riferimento è progettato per iniziare a creare l'endpoint SCIM e viene fornito "AS IS". I contributi della community sono invitati a creare e gestire il 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, le richieste vengono convertite in chiamate ai metodi del provider, programmati per operare su un archivio identità.

Breakdown: A request translated into calls to the provider's methods

Il progetto Microsoft.SCIM.WebHostSample è un'applicazione Web principale di ASP.NET basata sul modello Vuoto . Consente di distribuire il codice di esempio come 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 di cui l'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 della modalità di esecuzione dell'applicazione Web principale di ASP.NET, rimane 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à emittente diversa da Microsoft Entra ID, copiare il token di connessione OAuth richiesto 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 l'ID Microsoft Entra come provider di identità possono convalidare questo token rilasciato dall'ID Microsoft Entra.

    • L'applicazione che riceve le richieste deve convalidare l'autorità emittente del token come ID Microsoft Entra per un tenant Microsoft Entra previsto.
    • Un'attestazione iss identifica l'autorità emittente del token. Ad esempio, "iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/". In questo esempio, l'indirizzo di base del valore dell'attestazione identifica https://sts.windows.net Microsoft Entra ID come autorità emittente, mentre il segmento di indirizzo relativo, 12345678-0000-0000-00000000000, è 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 iss attestazione con le richieste SCIM. L'ID applicazione per tutte le app personalizzate è 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Il token generato dall'ID Microsoft Entra 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 che le richieste a uno qualsiasi degli endpoint del servizio vengano autenticate usando il token di connessione rilasciato dall'ID Microsoft Entra 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/12345678-0000-0000-0000-000000000000/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

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

È inoltre necessario un token di connessione per usare i test Postman forniti ed eseguire il debug locale usando localhost. 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 che le richieste a uno qualsiasi degli endpoint del servizio vengano autenticate usando 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 una query sul servizio per un utente corrispondente

Microsoft Entra ID esegue una query sul servizio per un utente con un externalId valore di attributo corrispondente al valore dell'attributo mailNickname di un utente in Microsoft Entra ID. La query viene espressa come richiesta HTTP (Hypertext Transfer Protocol), ad esempio 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. Inoltre, l'attributo usato per la corrispondenza (che in questo caso è externalId) è 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 externalId valore di attributo corrispondente al valore dell'attributo mailNickname di un utente non restituisce alcun utente, Microsoft Entra ID richiede che il servizio effettua 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 Microsoft.SCIM.Core2EnterpriseUser classe . Questa classe è definita nella Microsoft.SCIM.Schemas libreria. Se la richiesta di provisioning dell'utente ha esito positivo, si prevede che l'implementazione del metodo restituisca un'istanza della Microsoft.SCIM.Core2EnterpriseUser classe . Il valore della Identifier proprietà viene impostato sull'identificatore univoco dell'utente appena sottoposto a provisioning.

Esempio 3. Eseguire una 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/54D382A4-2050-4C03-94D1-E769F1D15682 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 i seguenti:

  • Identifier: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Esempio 4. Eseguire una 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: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
  • parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(y).ComparisonValue: "2819c223-7f76-453a-919d-413861904646"
  • parameters.RequestedAttributePaths.ElementAt(0): "ID"
  • Parametri. 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/54D382A4-2050-4C03-94D1-E769F1D15682 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/2819c223-7f76-453a-919d-413861904646",
              "value":"2819c223-7f76-453a-919d-413861904646"}]}]}

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 aggiornare un utente, l'oggetto fornito come valore dell'argomento patch ha questi valori di proprietà:

Argomento Valore
ResourceIdentifier.Identifier "54D382A4-2050-4C03-94D1-E769F1D15682"
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/2819c223-7f76-453a-919d-413861904646
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 2819c223-7f76-453a-919d-413861904646

Esempio 6. Eseguire 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/54D382A4-2050-4C03-94D1-E769F1D15682 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: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

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

Microsoft Entra ID può essere configurato per effettuare automaticamente il provisioning di utenti e gruppi assegnati alle 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 di Microsoft Entra SCIM si basa sul servizio di provisioning utenti di Microsoft Entra, progettato per mantenere costantemente sincronizzati gli utenti tra Microsoft Entra ID 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

I passaggi descritti in questo articolo possono variare leggermente in base al portale da cui si inizia.

Le applicazioni che supportano il profilo SCIM descritto in questo articolo possono essere connesse all'ID Microsoft Entra usando la funzionalità "applicazione non raccolta" nella raccolta di applicazioni 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 come almeno un'applicazione Amministrazione istrator.

  2. Passare a Applicazioni di identità>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 shows the Microsoft Entra application gallery.

  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 of app provisioning page in the Microsoft Entra admin center.

  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à emittente diversa da Microsoft Entra ID, copiare il token di connessione OAuth richiesto 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 l'ID Microsoft Entra come provider di identità possono convalidare questo token rilasciato dall'ID Microsoft Entra.

    Nota

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

  10. Selezionare Test Connessione ion 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 ion 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 .

  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 su come leggere i 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. La pubblicazione dell'app nella raccolta di Microsoft Entra e la disponibilità del provisioning per altri utenti è semplice. Consultare i passaggi qui Microsoft collabora con l'utente per integrare l'applicazione nella raccolta, testare l'endpoint e rilasciare la documentazione sull'onboarding per i clienti.

Usare l'elenco di controllo per eseguire rapidamente l'onboarding dell'applicazione e i clienti hanno un'esperienza di distribuzione uniforme. Le informazioni vengono raccolte dall'utente 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)
  • Supporto dell'aggiornamento di più appartenenze a più gruppi con una singola 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 un utente sia presente. Sono facili da usare per gli 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 e l'autorizzazione deve essere completata di nuovo. È 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 token nell'interfaccia utente personalizzata della 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, URL del client per ottenere l'autorizzazione dal proprietario della risorsa tramite reindirizzamento dell'agente utente. L'utente viene reindirizzato a questo URL per l'autorizzazione dell'accesso.

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

  • L'ID client, il server di autorizzazione rilascia il client registrato un identificatore client, ovvero una stringa univoca che rappresenta le informazioni di registrazione fornite dal client. L'identificatore client non è un segreto; è 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.

È consigliabile, ma non necessario, supportare più segreti per semplificare il rinnovo senza tempi di inattività.

Come configurare il flusso di concessione del codice OAuth

  1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un'applicazione Amministrazione istrator.

  2. Passare a Identity>Applications Enterprise Applications>Application>Provisioning (Provisioning applicazioni aziendali>) e selezionare Authorize (Autorizza).

  3. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un'applicazione Amministrazione istrator.

  4. Passare a Applicazioni di identità>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 oppure il processo di provisioning viene messo in quarantena alla scadenza del token.

Per altri metodi di autenticazione e autorizzazione, inviare informazioni su 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 possano parlare con le funzionalità di integrazione. Brevemente i team, fornisci loro domande frequenti e includi 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. Assicurati di includere @Microsoft Entra ID in modo da poter retweet il tuo post. Esempio: Post di Twitter imprivata
  • Creare o aggiornare le pagine di marketing o il sito Web (ad esempio, pagina di integrazione, pagina partner, pagina dei prezzi e così via) per includere la disponibilità dell'integrazione congiunta. Esempio: Pagina di integrazione pingboard, pagina di integrazione di Smartsheet, pagina di prezzi 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 endpointSCIM di esempio Automatizzare il provisioning degli utenti e il deprovisioning nelle appSaaS Personalizzare i mapping degli attributi per il provisioning degli utenti Le espressioni di scrittura per imapping degliattributi Filtri di ambito per le notifichedi provisioningaccount di provisioning utenti Elenco di esercitazioni su come integrare app SaaS