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

Le portail Azure constitue un moyen pratique pour configurer séparément l’approvisionnement d’applications individuelles. Cependant, si vous créez plusieurs ou même des centaines d’instances d’une application, 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.

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
  1. Démarrez l’Afficheur Microsoft Graph.
  2. Cliquez sur le bouton « Se connecter avec Microsoft » et connectez-vous à l’aide des informations d’identification d’administrateur de l’application ou d’administrateur global d’Azure AD.
  3. Une fois connecté, les détails du compte d’utilisateur apparaissent dans le volet de gauche.

Les applications de la galerie d’applications Azure AD disposent toutes d’un modèle d’application qui décrit les métadonnées de cette dernière. À 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."    

}

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/{id}/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 fait référence à la ressource précédente, qui, dans ce cas, est la ressource servicePrincipal.

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

Requête

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{id}/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 d’établir une relation de confiance entre Azure AD et l’application. Autorisez l’accès à 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. 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 du cycle d’approvisionnement actuel. Elle vous permet également de voir les statistiques à jour, notamment le nombre d’utilisateurs et de groupes qui ont été créés dans le système cible.

Requête

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

response

HTTP/1.1 200 OK
Content-type: application/json

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

Voir aussi