Configurer l’approvisionnement à l’aide des API Microsoft Graph

Article
04/08/2024

Le centre d’administration Microsoft Entra constitue un moyen pratique pour configurer séparément l’approvisionnement d’applications individuelles. Cependant, si vous créez plusieurs instances d’une application, voire des centaines, ou migrez la configuration d’une application d’un environnement vers un autre, il peut être plus simple d’automatiser la création et la configuration d’applications avec les API Microsoft Graph. Cet article explique comment automatiser la configuration de l’approvisionnement à l’aide d’API. Cette méthode est couramment utilisée pour les applications telles que Amazon Web Services.

Cet article illustre le processus avec les API dans le point de terminaison bêta Microsoft Graph et l’Afficheur Microsoft Graph. Des API similaires sont également disponibles dans le point de terminaison Microsoft Graph v1.0. Pour obtenir un exemple de configuration de l’approvisionnement avec Graph v1.0 et PowerShell, consultez les étapes 6-13 de l’article Configurer la synchronisation entre clients à l’aide de PowerShell ou de l’API Microsoft Graph.

Vue d’ensemble de la procédure d’automatisation de la configuration de l’approvisionnement à l’aide des API Microsoft Graph

Étape	Détails
Étape 1. Créer l’application de galerie	Se connecter au client de l’API Récupérer le modèle de l’application de galerie Créer l’application de galerie
Étape 2. Créer un travail d’approvisionnement à partir d’un modèle	Récupérer le modèle pour le connecteur d’approvisionnement Créer le travail d’approvisionnement
Étape 3. Autoriser l’accès	Tester la connexion à l’application Enregistrer les informations d’identification
Étape 4. Démarrer le travail d’approvisionnement	Démarrage du travail
Étape 5. Surveiller l’approvisionnement	Vérifier l’état du travail d’approvisionnement Récupérer les journaux d’approvisionnement

Si vous effectuez l’approvisionnement sur une application locale, vous devez également installer et configurer l’agent d’approvisionnement et l’affecter à l’application.

Étape 1 : Créer l’application de galerie

Démarrez l’Afficheur Microsoft Graph.
Sélectionnez le bouton « Connexion avec Microsoft » et connectez-vous avec les informations d’identification d’administrateur général ou d’administrateur d’application Microsoft Entra.
Une fois connecté, les détails du compte d’utilisateur apparaissent dans le volet de gauche.

Récupérer l’identificateur du modèle de l’application de galerie

Les applications de la galerie d’applications Microsoft Entra disposent toutes d’un modèle d’application qui décrit leurs métadonnées. À l’aide de ce modèle, vous pouvez créer une instance de l’application et du principal de service dans votre locataire à des fins de gestion. Récupérer l’identificateur du modèle de l’application pour l’Accès à l’authentification unique AWS et, à partir de la réponse, enregistrer la valeur de la propriété d’identification à utiliser ultérieurement dans ce didacticiel.

Requête

GET https://graph.microsoft.com/beta/applicationTemplates?$filter=displayName eq 'AWS Single-Account Access'

response

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

}

Créer l’application de galerie

Utilisez l’ID de modèle récupéré pour votre application lors de la dernière étape pour créer une instance de l’application et du principal du service dans votre locataire.

Requête

POST https://graph.microsoft.com/beta/applicationTemplates/{applicationTemplateId}/instantiate
Content-type: application/json

{
  "displayName": "AWS Contoso"
}

response

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

Étape 2 : Créer un travail d’approvisionnement basé sur un modèle

Récupérer le modèle pour le connecteur d’approvisionnement

Les applications de la galerie dont l’approvisionnement est activé disposent de modèles destinés à simplifier la configuration. Utilisez la requête ci-dessous pour récupérer le modèle pour la configuration de l’approvisionnement. Notez que vous devrez fournir l’ID. L’ID est celui de la ressource servicePrincipal créée à l’étape précédente.

Requête

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/templates

response

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "aws",
            "factoryTag": "aws",
            "schema": {
                    "directories": [],
                    "synchronizationRules": []
                    }
        }
    ]
}

Créer le travail d’approvisionnement

Pour activer l’approvisionnement, vous devez créer un travail au préalable. Utilisez la requête suivante pour créer un travail d’approvisionnement. Spécifiez l’ID de modèle susmentionné en tant que modèle à utiliser pour le travail.

Requête

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
Content-type: application/json

{ 
    "templateId": "aws"
}

response

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

Étape 3 : Autoriser l’accès

Tester la connexion à l’application

Testez la connexion à l’application tierce. L’exemple suivant est destiné à une application nécessitant une clé secrète client et un jeton secret. Chaque application possède ses propres exigences. Les applications utilisent souvent une adresse de base à la place d’une clé secrète client. Pour déterminer les informations d’identification requises pour votre application, accédez à la page de configuration de l’approvisionnement de votre application, puis, en mode développeur, cliquez sur Tester la connexion. Le trafic réseau indique les paramètres utilisés pour les informations d’identification. Pour obtenir une liste complète des informations d’identification, consultez synchronizationJob: validateCredentials. La plupart des applications, telles qu’Azure Databricks, s’appuient sur BaseAddress et SecretToken. BaseAddress est désigné comme une URL de locataire dans le centre d’administration Microsoft Entra.

Requête

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/validateCredentials

{ 
    "credentials": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx" 
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

response

HTTP/1.1 204 No Content

Enregistrer vos informations d’identification

La configuration de l’approvisionnement nécessite l’établissement d’une approbation entre Microsoft Entra ID et l’application pour autoriser Microsoft Entra à appeler l’application tierce. L’exemple suivant est propre à une application nécessitant une clé secrète client et un jeton secret. Chaque application possède ses propres exigences. Consultez la documentation sur les API pour voir les options disponibles.

Requête

PUT https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets 

{ 
    "value": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx"
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

response

HTTP/1.1 204 No Content

Étape 4 : Démarrer le travail d’approvisionnement

Maintenant que le travail d’approvisionnement est configuré, utilisez la commande suivante pour démarrer le travail.

Requête

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/start

response

HTTP/1.1 204 No Content

Étape 5 : Superviser l’approvisionnement

Surveiller l’état du travail d’approvisionnement

Maintenant que le travail d’approvisionnement est en cours d’exécution, utilisez la commande suivante pour suivre la progression. Chaque travail de synchronisation dans la réponse inclut l’état du cycle d’approvisionnement actuel ainsi que les statistiques à ce jour, notamment le nombre d’utilisateurs et de groupes créés dans le système cible.

Requête

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs

response

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

Surveiller les événements d’approvisionnement à l’aide des journaux d’approvisionnement

Outre la supervision de l’état du travail d’approvisionnement, vous pouvez utiliser les journaux d’approvisionnement pour interroger tous les événements qui se produisent. Par exemple, interrogez un utilisateur particulier et déterminez s’il a été correctement approvisionné.

Requête

GET https://graph.microsoft.com/beta/auditLogs/provisioning

response

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

Configurer l’approvisionnement à l’aide des API Microsoft Graph

Étape 1 : Créer l’application de galerie

Récupérer l’identificateur du modèle de l’application de galerie

Requête

response

Créer l’application de galerie

Requête

response

Étape 2 : Créer un travail d’approvisionnement basé sur un modèle

Récupérer le modèle pour le connecteur d’approvisionnement

Requête

response

Créer le travail d’approvisionnement

Requête

response

Étape 3 : Autoriser l’accès

Tester la connexion à l’application

Requête

response

Enregistrer vos informations d’identification

Requête

response

Étape 4 : Démarrer le travail d’approvisionnement

Requête

response

Étape 5 : Superviser l’approvisionnement

Surveiller l’état du travail d’approvisionnement

Requête

response

Surveiller les événements d’approvisionnement à l’aide des journaux d’approvisionnement

Requête

response

Voir aussi

Ressources supplémentaires

Configurer l’approvisionnement à l’aide des API Microsoft Graph

Étape 1 : Créer l’application de galerie

Se connecter à l’afficheur Microsoft Graph (recommandé), à Postman ou à tout autre client d’API que vous utilisez

Récupérer l’identificateur du modèle de l’application de galerie

Requête

response

Créer l’application de galerie

Requête

response

Étape 2 : Créer un travail d’approvisionnement basé sur un modèle

Récupérer le modèle pour le connecteur d’approvisionnement

Requête

response

Créer le travail d’approvisionnement

Requête

response

Étape 3 : Autoriser l’accès

Tester la connexion à l’application

Requête

response

Enregistrer vos informations d’identification

Requête

response

Étape 4 : Démarrer le travail d’approvisionnement

Requête

response

Étape 5 : Superviser l’approvisionnement

Surveiller l’état du travail d’approvisionnement

Requête

response

Surveiller les événements d’approvisionnement à l’aide des journaux d’approvisionnement

Requête

response

Voir aussi

Ressources supplémentaires