Esercitazione: Sviluppare e pianificare il provisioning per un endpoint SCIM in Azure Active Directory

Come sviluppatore di applicazioni, è possibile usare l'API di gestione utenti di System for Cross-Domain Identity Management (SCIM) per abilitare il provisioning automatico di utenti e gruppi tra l'applicazione e Azure Active Directory (Azure AD). Questo articolo illustra come creare un endpoint SCIM ed eseguire l'integrazione con il servizio di provisioning di Azure AD. La specifica SCIM offre uno schema utente comune per il provisioning. Se usato con standard federativi come SAML o OpenID Connect, SCIM offre agli amministratori una soluzione basata su standard end-to-end per la gestione degli accessi.

Provisioning da Azure AD a un'app con SCIM

SCIM 2.0 è una definizione standardizzata di due endpoint: un /Users endpoint e un /Groups endpoint. Usa gli endpoint dell'API REST comuni per creare, aggiornare ed eliminare oggetti. SCIM è costituito da uno schema pre-definito per gli attributi comuni, ad esempio nome del gruppo, nome utente, nome utente, cognome, 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 POST HTTP di un oggetto JSON nell'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 di Azure AD. Per avviare il provisioning di utenti e gruppi nell'applicazione, seguire questa procedura.

  1. Progettare lo schema utente e gruppo : identificare gli oggetti e gli attributi dell'applicazione per determinare come eseguire il mapping allo schema utente e gruppo supportato dall'implementazione SCIM di Azure AD.

  2. Informazioni sull'implementazione sciM di Azure AD: informazioni su come viene implementato il servizio di provisioning di Azure AD per modellare la gestione e le risposte della richiesta del protocollo SCIM.

  3. Compilare un endpoint SCIM: un endpoint deve essere compatibile con SCIM 2.0 per l'integrazione con il servizio di provisioning di Azure AD. Come opzione, usare librerie e esempi di codice 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 di Azure AD. Se l'organizzazione usa un'applicazione di terze parti per implementare un profilo SCIM 2.0 supportato da Azure AD, è possibile automatizzare rapidamente sia il provisioning che il deprovisioning di utenti e gruppi.

  5. [Facoltativo] Pubblicare l'applicazione nella raccolta di applicazioni di Azure AD: semplificare l'individuazione dell'applicazione da parte dei clienti e configurare facilmente il provisioning.

Diagramma che mostra i passaggi necessari per l'integrazione di un endpoint SCIM con Azure AD.

Progettare lo schema utente e gruppo

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 del processo e così via) necessari all'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 Azure AD)
  • 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 il messaggio di posta elettronica che il gestore dell'utente, usare lo schema principale per raccogliere il messaggio di posta elettronica dell'utente e lo schema utente aziendale per raccogliere il manager dell'utente.

Per progettare lo schema, seguire questa procedura:

  1. Elencare gli attributi richiesti dall'applicazione, quindi categorizzare 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, gestione, 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 allo schema utente che copre gli attributi mancanti. Vedere l'esempio seguente per un'estensione all'utente per consentire il provisioning di un utente tag.

  3. Eseguire il mapping degli attributi SCIM agli attributi utente in Azure AD. Se uno degli attributi definiti nell'endpoint SCIM non ha una controparte chiara nello schema utente di Azure AD, guidare l'amministratore del tenant per estendere lo schema o usare un attributo di estensione, come illustrato di seguito per la tags proprietà.

La tabella seguente elenca un esempio di attributi obbligatori:

Attributo dell'app richiesto Attributo SCIM mappato Attributo Di Azure AD mappato
loginName userName userPrincipalName
firstName name.givenName givenName
lastName name.familyName Cognome
workMail email[type eq "work"].value Posta elettronica
manager manager manager
tag urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag extensionAttribute1
status active isSoftDeleted (valore calcolato non archiviato per l'utente)

Il payload JSON seguente mostra 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 , e meta necessariidexternalId.

Consente di classificare tra /User e /Group per eseguire il mapping di tutti gli attributi utente predefiniti in Azure AD all'RFC SCIM, vedere come personalizzare gli attributi vengono mappati tra Azure AD e l'endpoint SCIM.

La tabella seguente elenca un esempio di attributi utente:

Utente di Azure AD 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
mobile 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 di Azure AD urn:ietf:params:scim:schemas:core:2.0:Group
displayName displayName
Membri di Membri di
objectId externalId

Nota

Non è necessario supportare sia gli utenti che i gruppi o tutti gli attributi illustrati qui, ma solo un riferimento al mapping degli attributi in Azure AD 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 una singola 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 gli attributi personalizzati o se lo schema cambia frequentemente perché consente a un client di recuperare automaticamente lo schema più aggiornato. Usare l'endpoint /Bulk per supportare i gruppi.

Informazioni sull'implementazione SCIM di Azure AD

Per supportare un'API di gestione utenti SCIM 2.0, questa sezione descrive come viene implementato il servizio di provisioning di Azure AD e illustra come modellare la gestione e le risposte delle richieste del protocollo SCIM.

Importante

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

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 in base al valore di id e le query vengono eseguite in base a username e externalId per gli utenti e in base a displayName per i gruppi.
Filtro excludedAttributes=members durante l'esecuzione di query sulla risorsa del gruppo Sezione 3.4.2.2
Elenco di supporto per utenti e paginazione 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.
Supportare l'endpoint /Schemas Sezione 7 L'endpoint di individuazione dello schema verrà usato per individuare altri attributi.
Accettare un singolo token di connessione per l'autenticazione e l'autorizzazione di Azure AD per l'applicazione.

Usare le linee guida generali per l'implementazione di un endpoint SCIM per garantire la compatibilità con Azure AD:

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 di quello 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 inviati da Azure AD 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 per gli elementi strutturali in SCIM, in particolare i valori dell'operazione PATCHop , come definito nella sezione 3.5.2. Azure AD genera i valori di op come Add, Replace e Remove.
  • Microsoft Azure AD 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 nel portale di Azure.
  • Supportare HTTPS nell'endpoint SCIM.
  • Gli attributi complessi e multivalore personalizzati sono supportati, ma Azure AD non dispone di molte strutture di dati complesse da cui eseguire il pull dei dati in questi casi. È possibile eseguire facilmente il mapping di attributi complessi di tipo nome/valore associato semplice, ma il flusso dei dati a attributi complessi con tre o più attributi secondari non è supportato in questo momento.
  • I valori dell'attributo 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 content-Type: application/scim+json

Recupero delle risorse:

/Users:

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

/Groups:

  • I gruppi sono facoltativi, ma sono supportati solo se l'implementazione SCIM supporta le richieste PATCH .
  • I gruppi devono avere un'univocità nel valore "displayName" per la corrispondenza con Azure AD e l'applicazione SCIM. L'univocità non è un requisito del protocollo SCIM, ma è un requisito per l'integrazione di un endpoint SCIM con Azure AD.

/Schemas (individuazione dello schema):

  • Richiesta/risposta di esempio
  • L'individuazione dello schema non è attualmente supportata nell'applicazione SCIM personalizzata non della raccolta, ma viene usata in determinate applicazioni della raccolta. In futuro, l'individuazione dello schema verrà usata come unico metodo per aggiungere altri attributi allo schema di un'applicazione SCIM della raccolta esistente.
  • Se un valore non è presente, non inviare valori Null.
  • I valori delle proprietà devono essere maiuscole/minuscole camel, ad esempio readWrite.
  • Deve restituire una risposta di elenco.
  • La richiesta /schemas verrà effettuata dal servizio di provisioning di Azure AD ogni volta che un utente salva la configurazione del provisioning nel portale di Azure o ogni volta che un utente passa alla pagina di provisioning di modifica nel portale di Azure. Gli altri attributi individuati verranno 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. Non comporta la rimozione degli attributi.

Provisioning e deprovisioning utenti

Il diagramma seguente mostra i messaggi inviati da Azure AD 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 dell'utente.

Provisioning e deprovisioning di gruppi

Il provisioning e il deprovisioning di gruppi sono facoltativi. Quando implementata e abilitata, la figura seguente mostra i messaggi inviati da Azure AD 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 esempi di richieste SCIM generate dal servizio di provisioning di Azure Active Directory (Azure AD) e risposte previste di esempio. 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 informazioni su come e quando il servizio di provisioning utenti di Azure AD genera le operazioni descritte di seguito, vedere la sezione Cicli di provisioning: iniziale e incrementale in Come funziona il provisioning.

Operazioni relative agli utenti

Operazioni relative ai gruppi

Individuazione dello schema

Operazioni relative agli utenti

  • È possibile eseguire query sugli utenti in base agli attributi userName o emails[type eq "work"].

Crea utente

Richiesta

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

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

Richiesta

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

GET /Users/5171a35d82074e068ce2

Risposta (utente non trovato. Il dettaglio non è obbligatorio, ma solo lo stato.
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "404",
    "detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}

Ottenere un utente tramite query

Richiesta

GET /Users?filter=userName eq "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081"

Risposta

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

Richiesta

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

Risposta

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]

Richiesta

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

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]

Richiesta

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

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

Richiesta

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "Operations": [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}
Risposta
{
    "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.

Richiesta

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

Risposta

HTTP/1.1 204 (Nessun contenuto)

Operazioni relative ai gruppi

  • I gruppi dovranno essere sempre creati con un elenco di membri vuoto.
  • È possibile eseguire query sui gruppi in base all'attributo displayName.
  • 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.

Creare un gruppo

Richiesta

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

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

Richiesta

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

Risposta

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

Richiesta

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

Risposta

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]

Richiesta

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

HTTP/1.1 204 (Nessun contenuto)

Aggiornare un gruppo [aggiungere membri]

Richiesta

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

HTTP/1.1 204 (Nessun contenuto)

Aggiornare un gruppo [rimuovere membri]

Richiesta

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

HTTP/1.1 204 (Nessun contenuto)

Eliminare un gruppo

Richiesta

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Risposta

HTTP/1.1 204 (Nessun contenuto)

Individuazione dello schema

Individuare lo schema

Richiesta

GET /Schemas

Risposta

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

Le uniche versioni del protocollo TLS accettabili sono TLS 1.2 e TLS 1.3. Non sono consentite altre versioni di TLS, né alcuna versione di SSL.

  • 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. Se si dispone solo di un certificato RSA, i pacchetti di crittografia ECDSA installati 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 di Azure AD attualmente opera sotto gli intervalli di indirizzi IP per AzureActiveDirectory, come indicato qui. È possibile aggiungere gli intervalli di indirizzi IP elencati sotto il tag AzureActiveDirectory per consentire il traffico dal servizio di provisioning di Azure AD all'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 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.

Azure AD 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à ad Azure AD senza aprire porte in ingresso, in un server nella rete privata. Fare clic qui per altre informazioni.

Creare un endpoint SCIM

Dopo aver progettato lo schema e aver compreso l'implementazione SCIM di Azure AD, è possibile iniziare a sviluppare l'endpoint SCIM. Invece di iniziare da zero e creare 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 di .NET Core open source pubblicato dal team di provisioning di Azure AD è una risorsa di questo tipo che può iniziare a sviluppare. Dopo aver compilato l'endpoint SCIM, è necessario testarlo. È possibile usare la raccolta di test Postman forniti come parte del codice di riferimento o eseguire le richieste/risposte di esempio fornite in precedenza.

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 e le richieste vengono convertite in chiamate ai metodi del provider, che saranno programmati per eseguire operazioni su un archivio identità.

Dettaglio: conversione di una richiesta in chiamate ai metodi del provider

Il progetto Microsoft.SCIM.WebHostSample è un'applicazione Web ASP.NET Core, 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 utilizzabile durante lo sviluppo, che viene installato durante il completamento dell'installazione. A seconda di come viene eseguita, l'applicazione Web ASP.NET Core sarà 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: Imporre HTTPS in ASP.NET Core

Gestione dell'autenticazione dell'endpoint

Le richieste dal servizio di provisioning di Azure AD includono un token di connessione OAuth 2.0. Il token di connessione è un token di sicurezza rilasciato da un server di autorizzazione, ad esempio Azure AD ed è attendibile dall'applicazione. È possibile configurare il servizio di provisioning di Azure AD per usare uno dei token seguenti:

  • Un token di orso di lunga durata. Se l'endpoint SCIM richiede un token di connessione OAuth da un'autorità di certificazione diversa da Azure AD, 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 di Azure AD. Se il campo Token segreto è vuoto, Azure AD include un token di connessione OAuth rilasciato da Azure AD con ogni richiesta. Le app che usano Azure AD come provider di identità possono convalidare il token rilasciato da Azure AD.

    • L'applicazione che riceve le richieste deve convalidare l'autorità emittente del token come azure AD per un tenant di Azure AD previsto.
    • Nel token l'autorità emittente viene identificata da un'attestazione iss . Ad esempio: "iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/". In questo esempio, l'indirizzo di base del valore dell'attestazione identifica Azure AD come autorità di certificazione, mentre il segmento di indirizzi relativo, https://sts.windows.net 12345678-0000-0000-00000000000, è un identificatore univoco del tenant di Azure AD 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 richieste SCIM. L'ID applicazione per tutte le app personalizzate è 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Il token generato dal servizio di provisioning di Azure AD dovrà essere usato solo a scopo di 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 degli endpoint del servizio vengano autenticate usando il token di connessione rilasciato da Azure AD 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 l'uso dei 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 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 un utente corrispondente

Azure AD esegue una query sul servizio per un utente con un externalId valore di attributo corrispondente al valore dell'attributo mailNickname di un utente in Azure AD. La query viene espressa come richiesta HTTP (Hypertext Transfer Protocol), ad esempio questo esempio, in cui jyoung è un esempio di mailNickname di un utente in Azure AD.

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 Azure AD.

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

Nel codice di esempio la richiesta viene tradotta in una chiamata al metodo QueryAsync del provider del servizio. Ecco la firma di questo 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, Azure AD richiede che il servizio effettua il provisioning di un utente corrispondente a quello di Azure AD. Ecco un esempio di tale richiesta:

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 tradotta in una chiamata al metodo CreateAsync del provider del servizio. Ecco la firma di questo 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 a un provisioning utente il valore dell'argomento risorsa è un'istanza della classe Microsoft.SCIM.Core2EnterpriseUser definita nella libreria Microsoft.SCIM.Schemas. Se la richiesta di provisioning dell'utente ha esito positivo, è previsto che l'implementazione del metodo restituisca un'istanza della classe Microsoft.SCIM.Core2EnterpriseUser, con il valore della proprietà Identifier impostato sull'identificatore univoco dell'utente di cui è appena stato effettuato il provisioning.

Esempio 3. Eseguire query sullo stato corrente di un utente

Per aggiornare un utente noto per esistere in un archivio identità front-end da uno SCIM, Azure AD procede richiedendo lo stato corrente di tale utente 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 tradotta in una chiamata al metodo RetrieveAsync del provider del servizio. Ecco la firma di questo 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 parameters sono analoghi ai 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

Se un attributo di riferimento deve essere aggiornato, Azure AD esegue una query sul servizio per determinare se il valore corrente dell'attributo di riferimento nell'archivio identità anteriore dal servizio corrisponde già al valore di tale attributo in Azure AD. Per gli utenti, l'unico attributo il cui valore corrente viene sottoposto a query con questa modalità è l'attributo manager. Ecco un esempio di una richiesta per determinare se l'attributo di gestione di un oggetto utente ha attualmente un determinato valore: nel codice di esempio la richiesta viene tradotta 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. Oppure 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 Azure AD a un endpoint SCIM di aggiornare un utente

Ecco un esempio di una richiesta da Azure AD 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 tradotta in una chiamata al metodo UpdateAsync del provider del servizio. Ecco la firma di questo 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 "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 eseguire il deprovisioning di un utente da un archivio identità front-end da un endpoint SCIM, Azure AD 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 tradotta in una chiamata al metodo DeleteAsync del provider del servizio. Ecco la firma di questo 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 di Azure AD

È possibile configurare Azure AD 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 Comprendere l'implementazione SCIM di Azure AD.

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

Importante

L'implementazione SCIM di Azure AD è basata sul servizio di provisioning utenti di Azure AD, progettato per mantenere gli utenti costantemente sincronizzati tra Azure AD 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 di Azure AD. Per altre informazioni, vedere la sezione Cicli di provisioning: iniziale e incrementale in Come funziona il provisioning.

Introduzione

Le applicazioni che supportano il profilo SCIM descritto in questo articolo possono essere connesse ad Azure AD usando la funzionalità "applicazione non della raccolta" nella raccolta di applicazioni di Azure AD. Una volta stabilita la connessione, Azure AD esegue un processo di sincronizzazione ogni 40 minuti in cui interroga l'endpoint SCIM dell'applicazione in merito agli utenti e ai gruppi assegnati e li crea o li modifica in base alle istruzioni di assegnazione.

Per connettere un'applicazione che supporta SCIM:

  1. Accedere al portale di Azure AD. È possibile accedere a una versione di valutazione gratuita per Azure AD con licenze P2 iscrivendosi al programma per sviluppatori

  2. Selezionare Applicazioni aziendali nel riquadro sinistro. Verrà visualizzato un elenco di tutte le app configurate, incluse le app aggiunte dalla raccolta.

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

  4. 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 di Azure AD:

    Screenshot che mostra la raccolta di applicazioni di Azure AD.

    Nota

    Se si usa l'esperienza precedente della raccolta di app, seguire la guida alla schermata seguente.

    Lo screenshot seguente mostra l'esperienza della raccolta di app precedenti di Azure AD:

    Screenshot che mostra l'esperienza della raccolta di app precedenti di Azure AD

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

  6. Nel menu Modalità di provisioning selezionare Automatica.

    Lo screenshot seguente mostra la configurazione delle impostazioni di provisioning nel portale di Azure:

    Screenshot della pagina di provisioning delle app nel portale di Azure.

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

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

    Nota

    Non è consigliabile lasciare vuoto questo campo e basarsi su un token generato da Azure AD. Questa opzione è disponibile principalmente a scopo di test.

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

    Nota

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

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

  11. 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 Azure AD 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.

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

  13. Al termine della configurazione, impostare Stato del provisioning su .

  14. Selezionare Salva per avviare il servizio di provisioning di Azure AD.

  15. 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 Azure AD, vedere l'esercitazione relativa alla 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 crea un'applicazione che verrà usata da più tenant, è possibile renderla disponibile nella raccolta di applicazioni di Azure AD. È facile per le organizzazioni individuare l'applicazione e configurare il provisioning. Pubblicare l'app nella raccolta di Azure AD e rendere il provisioning disponibile ad altri è semplice. Consultare i passaggi qui Microsoft collaborerà all'integrazione dell'applicazione nella raccolta, al test dell'endpoint e al rilascio di documentazione sull'onboarding utilizzabile dai clienti.

Usare l'elenco di controllo per eseguire rapidamente l'onboarding dell'applicazione e i clienti hanno un'esperienza di distribuzione senza problemi. Queste informazioni verranno 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 di seguito (obbligatorio)
  • 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 gruppi con una singola PATCH
  • Documentare pubblicamente l'endpoint SCIM

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

Metodo di autorizzazione Vantaggi Svantaggi Supporto
Nome utente e password (non consigliato o supportato da Azure AD) 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 sono molto più brevi rispetto alle password e hanno un meccanismo di aggiornamento automatico che non ha token di connessione di lunga durata. 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 dovrà essere completata nuovamente. È 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 sono molto più brevi rispetto alle password e hanno un meccanismo di aggiornamento automatico che non ha token di connessione di lunga durata. 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 l'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 Azure AD. 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 del 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.

  • 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; viene esposto al proprietario della risorsa e non deve essere usato 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.

Procedure consigliate (consigliate, ma non obbligatorie):

  • Supportare più URL di reindirizzamento. Gli amministratori possono configurare il provisioning sia da "portal.azure.com" che da "aad.portal.azure.com". Il supporto di più URL di reindirizzamento garantirà agli utenti la possibilità di ottenere l'autorizzazione dell'accesso da uno dei due portali.
  • Supportare più segreti per un semplice rinnovo, senza tempi di inattività.

Come configurare il flusso di concessione del codice OAuth

  1. Accedere al portale di Azure, passare ad Applicazioni>> aziendaliProvisioning applicazioni e selezionare Autorizza.

    1. Il portale di Azure reindirizza l'utente 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 di nuovo al portale di Azure e fornisce il codice di concessione

    4. Il servizio di provisioning di Azure AD 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

  2. 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 della raccolta. In questo modo è possibile verificare la compatibilità del server SCIM con il servizio di provisioning di Azure AD 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 verrà 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 l'avvio:

  • Assicurarsi che i team di vendita e di supporto clienti siano consapevoli, pronti e possano comunicare con le funzionalità di integrazione. Brevemente, i team forniscono domande frequenti e includono 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 Azure AD Press Release
  • Sfruttare i social media, come Twitter, Facebook o LinkedIn, per promuovere l'integrazione presso i clienti. Assicurarsi di includere @AzureAD per consentire a Microsoft di fare retweet del post. Esempio: post di imprivata su Twitter.
  • Creare o aggiornare le pagine di marketing o il sito Web (ad esempio, pagina di integrazione, pagina dei partner, pagina dei prezzi e così via) per includere la disponibilità dell'integrazione congiunta. Esempio: pagina relativa alle integrazioni di Pingboard, pagina sull'integrazione di Smartsheet e 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 Azure AD.
  • Avvisare i clienti della nuova integrazione tramite la comunicazione ai clienti (newsletter mensili, campagne di posta elettronica, note sulla versione del prodotto).

Passaggi successivi