Configurare il provisioning usando le API Microsoft Graph

  • Articolo

L'interfaccia di amministrazione di Microsoft Entra è un modo pratico per configurare il provisioning per singole app una alla volta. Tuttavia, se si creano diverse istanze di un'applicazione o 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 in Microsoft Graph Explorer. Le API simili sono disponibili anche nell'endpoint di 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 con 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.

  1. Avviare Microsoft Graph Explorer.
  2. Selezionare il pulsante "Accedi con Microsoft" e accedere con le credenziali di Microsoft Entra Global Amministrazione istrator o App Amministrazione.
  3. Una volta eseguito l'accesso, verranno visualizzati i dettagli dell'account utente nel riquadro sinistro.

Le applicazioni nella raccolta di applicazioni Microsoft Entra dispongono di un modello di applicazione che descrive i metadati per tale applicazione. 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."    

}

Usare l'ID modello recuperato per l'applicazione nell'ultimo passaggio per creare un'istanza dell'applicazione e dell'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": "cbc071a6-0fa5-4859-8g55-e983ef63df63",
        "appId": "92653dd4-aa3a-3323-80cf-e8cfefcc8d5d",
        "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": "f47a6776-bca7-4f2e-bc6c-eec59d058e3e",
        "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 specificare 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 requisiti specifici. 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 Test 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

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 è specifico di un'applicazione che richiede un segreto client e un token segreto. Ogni applicazione ha requisiti specifici. Esaminare la documentazione dell'API per visualizzare 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 dello stato di avanzamento. Ogni processo di sincronizzazione nella risposta include lo stato del ciclo di provisioning corrente, nonché le statistiche fino alla data, 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 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": "7928d5b5-7442-4a97-ne2d-66f9j9972ecn",
            "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": "f2764360-e0ec-5676-711e-cd6fc0d4dd61",
                    "ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
                    "ServicePrincipalDisplayName": "AWS Contoso"
                }
            },
            "initiatedBy": {
                "id": "",
                "displayName": "Azure AD Provisioning Service",
                "initiatorType": "system"
            }
            ]
       }
    ]
}

Vedi anche