Configurare il provisioning usando le API Microsoft Graph
L'interfaccia di amministrazione di Microsoft Entra è un modo pratico per configurare il provisioning per singole app una alla volta. Tuttavia, se si crea un elevato numero, anche centinaia, di istanze di un'applicazione o si esegue la migrazione della configurazione dell'applicazione da un ambiente a un altro, può essere più semplice automatizzare la creazione e la configurazione delle app con le API Microsoft Graph. Questo articolo illustra come automatizzare la configurazione del provisioning tramite le API. Questo metodo viene comunemente usato per applicazioni come Amazon Web Services.
Questo articolo illustra il processo con le API nell'endpoint beta di Microsoft Graph e Microsoft Graph Explorer; API simili sono disponibili anche nell'endpoint Microsoft Graph v1.0. Per un esempio di configurazione del provisioning con Graph v1.0 e PowerShell, vedere i passaggi da 6 a 13 di Configurare la sincronizzazione tra tenant usando PowerShell o l'API Microsoft Graph.
Panoramica dei passaggi per l'uso delle API Microsoft Graph per automatizzare la configurazione del provisioning
| Procedi | Dettagli |
|---|---|
| Passaggio 1: Creare l'applicazione della raccolta | Accedere al client API Recuperare il modello di applicazione della raccolta Creare l'applicazione della raccolta |
| Passaggio 2. Creare un processo di provisioning basato sul modello | Recuperare il modello per il connettore di provisioning Creare il processo di provisioning |
| Passaggio 3. Autorizzare l'accesso | Testare la connessione all'applicazione Salvare le credenziali |
| Passaggio 4. Avviare il processo di provisioning | Avviare il processo |
| Passaggio 5. Monitorare il provisioning | Controllare lo stato del processo di provisioning Recuperare i log di provisioning |
Se si esegue il provisioning in un'applicazione locale, sarà necessario installare e configurare l'agente di provisioning e assegnare l'agente di provisioning all'applicazione.
Passaggio 1: Creare l'applicazione della raccolta
Accedere a Microsoft Graph Explorer (scelta consigliata) o a qualsiasi altro client API usato
- Avviare Microsoft Graph Explorer.
- Selezionare il pulsante "Accedi con Microsoft" e accedere con un utente con il ruolo Amministratore applicazioni.
- Una volta eseguito l'accesso, verranno visualizzati i dettagli dell'account utente nel riquadro sinistro.
Recuperare l'identificatore del modello di applicazione della raccolta
Le applicazioni nella raccolta di applicazioni di Microsoft Entra presentano un modello di applicazione che descrive i metadati per l'applicazione in questione. Usando questo modello, è possibile creare un'istanza dell'applicazione e un'entità servizio nel tenant per la gestione. Recuperare l'identificatore del modello di applicazione per AWS Single-Account Access e,dalla risposta, registrare il valore della proprietà id da usare più avanti in questa esercitazione.
Richiedi
GET https://graph.microsoft.com/beta/applicationTemplates?$filter=displayName eq 'AWS Single-Account Access'
Risposta
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"id": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
"displayName": "AWS Single-Account Access",
"homePageUrl": "http://aws.amazon.com/",
"supportedSingleSignOnModes": [
"password",
"saml",
"external"
],
"supportedProvisioningTypes": [
"sync"
],
"logoUrl": "https://az495088.vo.msecnd.net/app-logo/aws_215.png",
"categories": [
"developerServices"
],
"publisher": "Amazon",
"description": "Federate to a single AWS account and use SAML claims to authorize access to AWS IAM roles. If you have many AWS accounts, consider using the AWS Single Sign-On gallery application instead."
}
Creare l'applicazione della raccolta
Usare l'ID modello recuperato per l'applicazione nell'ultimo passaggio per creare un'istanza dell'applicazione e l'entità servizio nel tenant.
Richiedi
POST https://graph.microsoft.com/beta/applicationTemplates/{applicationTemplateId}/instantiate
Content-type: application/json
{
"displayName": "AWS Contoso"
}
Risposta
HTTP/1.1 201 OK
Content-type: application/json
{
"application": {
"objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
"displayName": "AWS Contoso",
"homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
"replyUrls": [
"https://signin.aws.amazon.com/saml"
],
"logoutUrl": null,
"samlMetadataUrl": null,
},
"servicePrincipal": {
"objectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
"appDisplayName": "AWS Contoso",
"applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
"appRoleAssignmentRequired": true,
"displayName": "My custom name",
"homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
"replyUrls": [
"https://signin.aws.amazon.com/saml"
],
"servicePrincipalNames": [
"93653dd4-aa3a-4323-80cf-e8cfefcc8d7d"
],
"tags": [
"WindowsAzureActiveDirectoryIntegratedApp"
],
}
}
Passaggio 2: Creare il processo di provisioning in base al modello
Recuperare il modello per il connettore di provisioning
Le applicazioni nella raccolta abilitate per il provisioning hanno modelli per semplificare la configurazione. Usare la richiesta seguente per recuperare il modello per la configurazione del provisioning. Si noti che sarà necessario fornire l'ID. L'ID è quello della risorsa servicePrincipal, creata nel passaggio precedente.
Richiedi
GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/templates
Risposta
HTTP/1.1 200 OK
{
"value": [
{
"id": "aws",
"factoryTag": "aws",
"schema": {
"directories": [],
"synchronizationRules": []
}
}
]
}
Creare il processo di provisioning
Per abilitare il provisioning, è prima necessario creare un processo. Usare la richiesta seguente per creare un processo di provisioning. Usare il templateId del passaggio precedente quando si specifica il modello da usare per il processo.
Richiedi
POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
Content-type: application/json
{
"templateId": "aws"
}
Risposta
HTTP/1.1 201 OK
Content-type: application/json
{
"id": "{jobId}",
"templateId": "aws",
"schedule": {
"expiration": null,
"interval": "P10675199DT2H48M5.4775807S",
"state": "Disabled"
},
"status": {
"countSuccessiveCompleteFailures": 0,
"escrowsPruned": false,
"synchronizedEntryCountByType": [],
"code": "NotConfigured",
"lastExecution": null,
"lastSuccessfulExecution": null,
"lastSuccessfulExecutionWithExports": null,
"steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
"steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
"quarantine": null,
"troubleshootingUrl": null
}
}
Passaggio 3: Autorizzare l'accesso
Testare la connessione all'applicazione
Testare la connessione con l'applicazione di terze parti. L'esempio seguente è relativo a un'applicazione che richiede un segreto client e un token segreto. Ogni applicazione ha i propri requisiti. Le applicazioni usano spesso un indirizzo di base al posto di un segreto client. Per determinare le credenziali necessarie per l'app, passare alla pagina di configurazione del provisioning per l'applicazione e, in modalità sviluppatore, fare clic su testare la connessione. Il traffico di rete mostrerà i parametri usati per le credenziali. Per un elenco completo delle credenziali, vedere synchronizationJob: validateCredentials. La maggior parte delle applicazioni, ad esempio Azure Databricks, si basa su BaseAddress e SecretToken. BaseAddress viene definito URL tenant nell'interfaccia di amministrazione di Microsoft Entra.
Richiedi
POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/validateCredentials
{
"credentials": [
{
"key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx"
},
{
"key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
}
]
}
Risposta
HTTP/1.1 204 No Content
Salvare le credenziali personali
Per configurare il provisioning è necessario stabilire un trust tra Microsoft Entra ID e l'applicazione per autorizzare Microsoft Entra ad avere la possibilità di chiamare l'applicazione di terze parti. L'esempio seguente è specifica per un'applicazione che richiede un segreto client e un token segreto. Ogni applicazione ha i propri requisiti. Esaminare la documentazione dell'API per le opzioni disponibili.
Richiedi
PUT https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets
{
"value": [
{
"key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx"
},
{
"key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
}
]
}
Risposta
HTTP/1.1 204 No Content
Passaggio 4: Avviare il processo di provisioning
Ora che il processo di provisioning è configurato, usare il comando seguente per avviare il processo.
Richiedi
POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/start
Risposta
HTTP/1.1 204 No Content
Passaggio 5: Monitorare il provisioning
Monitorare lo stato del processo di provisioning
Ora che il processo di provisioning è in esecuzione, usare il comando seguente per tenere traccia dell'avanzamento. Ogni processo di sincronizzazione nella risposta include lo stato del ciclo di provisioning corrente, nonché le statistiche aggiornate, ad esempio il numero di utenti e gruppi creati nel sistema di destinazione.
Richiedi
GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
Risposta
HTTP/1.1 200 OK
Content-type: application/json
{ "value": [
{
"id": "{jobId}",
"templateId": "aws",
"schedule": {
"expiration": null,
"interval": "P10675199DT2H48M5.4775807S",
"state": "Disabled"
},
"status": {
"countSuccessiveCompleteFailures": 0,
"escrowsPruned": false,
"synchronizedEntryCountByType": [],
"code": "Paused",
"lastExecution": null,
"lastSuccessfulExecution": null,
"progress": [],
"lastSuccessfulExecutionWithExports": null,
"steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
"steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
"quarantine": null,
"troubleshootingUrl": null
},
"synchronizationJobSettings": [
{
"name": "QuarantineTooManyDeletesThreshold",
"value": "500"
}
]
}
]
}
Monitorare gli eventi di provisioning usando i log di provisioning
Oltre a monitorare lo stato del processo di provisioning, è possibile usare i log di provisioning per eseguire una query per tutti gli eventi che si verificano. Ad esempio, eseguire una query per un determinato utente e determinare se è stato eseguito correttamente il provisioning.
Richiedi
GET https://graph.microsoft.com/beta/auditLogs/provisioning
Risposta
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#auditLogs/provisioning",
"value": [
{
"id": "gc532ff9-r265-ec76-861e-42e2970a8218",
"activityDateTime": "2019-06-24T20:53:08Z",
"tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"cycleId": "44576n58-v14b-70fj-8404-3d22tt46ed93",
"changeId": "eaad2f8b-e6e3-409b-83bd-e4e2e57177d5",
"action": "Create",
"durationInMilliseconds": 2785,
"sourceSystem": {
"id": "0404601d-a9c0-4ec7-bbcd-02660120d8c9",
"displayName": "Azure Active Directory",
"details": {}
},
"targetSystem": {
"id": "cd22f60b-5f2d-1adg-adb4-76ef31db996b",
"displayName": "AWS Contoso",
"details": {
"ApplicationId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
"ServicePrincipalDisplayName": "AWS Contoso"
}
},
"initiatedBy": {
"id": "",
"displayName": "Azure AD Provisioning Service",
"initiatorType": "system"
}
]
}
]
}