Inrichten configureren met behulp van Microsoft Graph-API's

Artikel
04/06/2024

Het Microsoft Entra-beheercentrum is een handige manier om inrichting voor afzonderlijke apps één voor één te configureren. Maar als u meerdere of zelfs honderden exemplaren van een toepassing maakt of toepassingsconfiguratie migreert van de ene omgeving naar de andere, kan het eenvoudiger zijn om het maken en configureren van apps te automatiseren met de Microsoft Graph-API's. In dit artikel wordt uitgelegd hoe u de inrichtingsconfiguratie automatiseert via API's. Deze methode wordt vaak gebruikt voor toepassingen zoals Amazon Web Services.

Dit artikel illustreert het proces met API's in het bèta-eindpunt van Microsoft Graph en Microsoft Graph Explorer. Vergelijkbare API's zijn ook beschikbaar in het Microsoft Graph v1.0-eindpunt. Zie stap 6-13 van Synchronisatie tussen tenants configureren met PowerShell of Microsoft Graph API voor een voorbeeld van het configureren van inrichting met Graph v1.0 en PowerShell.

Overzicht van de stappen voor het gebruik van Microsoft Graph-API's om de inrichtingsconfiguratie te automatiseren

Stap	DETAILS
Stap 1. De galerietoepassing maken	Aanmelden bij de API-client De galerietoepassingssjabloon ophalen De galerietoepassing maken
Stap 2. De inrichtingstaak maken op basis van de sjabloon	De sjabloon voor de inrichtingsconnector ophalen De inrichtingstaak maken
Stap 3. Toegang autoriseren	De verbinding met de toepassing testen De referenties opslaan
Stap 4. De inrichtingstaak starten	Taak starten
Stap 5. Het inrichten bewaken	De status van de inrichtingstaak controleren De inrichtingslogboeken ophalen

Als u inricht voor een on-premises toepassing, moet u ook de inrichtingsagent installeren en configureren en de inrichtingsagent toewijzen aan de toepassing.

Stap 1: De galerietoepassing maken

Start de verkenner van Microsoft Graph.
Selecteer de knop Aanmelden met Microsoft en meld u aan met de referenties van Microsoft Entra Global Beheer istrator of App Beheer.
Nadat u zich hebt aangemeld, ziet u in het linkerdeelvenster de details van het gebruikersaccount.

De id van de galerietoepassingssjabloon ophalen

Toepassingen in de Microsoft Entra-toepassingsgalerie hebben elk een toepassingssjabloon die de metagegevens voor die toepassing beschrijft. Met deze sjabloon kunt u een exemplaar van de toepassing en service-principal maken in uw tenant voor beheer. Haal de id van de toepassingssjabloon voor AWS Single-Account Access en noteer de waarde van de id-eigenschap in het antwoord zodat u de waarde later in deze zelfstudie kunt gebruiken.

Aanvragen

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

}

De galerietoepassing maken

Gebruik de sjabloon-id die u tijdens de laatste stap hebt opgehaald voor uw toepassing om een exemplaar van de toepassing en service-principal te maken in uw tenant.

Aanvragen

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

Stap 2: De inrichtingstaak maken op basis van de sjabloon

De sjabloon voor de inrichtingsconnector ophalen

Toepassingen in de galerie die zijn ingeschakeld voor inrichting, hebben sjablonen om de configuratie te stroomlijnen. Gebruik de onderstaande aanvraag om de sjabloon voor de inrichtingsconfiguratie op te halen. Houd er rekening mee dat u de id moet opgeven. De id is die van de servicePrincipal-resource die u in de vorige stap hebt gemaakt.

Aanvragen

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

Response

HTTP/1.1 200 OK

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

De inrichtingstaak maken

Als u inrichting wilt inschakelen, moet u eerst een taak maken. Gebruik de volgende aanvraag om een inrichtingstaak te maken. Gebruik de templateId uit de vorige stap om de sjabloon op te geven die moet worden gebruikt voor de taak.

Aanvragen

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

Stap 3: Toegang autoriseren

De verbinding met de toepassing testen

Test de verbinding met de toepassing van derden. Het volgende voorbeeld is voor een toepassing waarvoor een clientgeheim en een geheim token is vereist. Elke toepassing heeft zijn eigen vereisten. Toepassingen gebruiken vaak een basisadres in plaats van een clientgeheim. Als u wilt bepalen welke referenties uw app vereist, gaat u naar de configuratiepagina voor de inrichting voor uw toepassing en klikt u in de ontwikkelaarsmodus op Verbinding testen. In het netwerkverkeer worden de parameters weergegeven die worden gebruikt voor de referenties. Zie synchronizationJob: validateCredentials voor een volledige lijst met referenties. De meeste toepassingen, zoals Azure Databricks, zijn afhankelijk van een BaseAddress en SecretToken. BaseAddress wordt een tenant-URL genoemd in het Microsoft Entra-beheercentrum.

Aanvragen

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

Uw referenties opslaan

Voor het configureren van inrichting moet een vertrouwensrelatie tussen Microsoft Entra-id en de toepassing tot stand worden gebracht om Microsoft Entra te autoriseren om de toepassing van derden aan te roepen. Het volgende voorbeeld is specifiek voor een toepassing waarvoor een clientgeheim en een geheim token vereist zijn. Elke toepassing heeft zijn eigen vereisten. Raadpleeg de API-documentatie om de beschikbare opties te bekijken.

Aanvragen

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

Stap 4: De inrichtingstaak starten

Nu de inrichtingstaak is geconfigureerd, gebruikt u de volgende opdracht om de taak te starten.

Aanvragen

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

Response

HTTP/1.1 204 No Content

Stap 5: Het inrichten bewaken

Bewaak de status van de inrichtingstaak

Nu de inrichtingstaak wordt uitgevoerd, gebruikt u de volgende opdracht om de voortgang bij te houden. Elke synchronisatietaak in het antwoord bevat de status van de huidige inrichtingscyclus en statistieken tot op heden, zoals het aantal gebruikers en groepen dat in het doelsysteem is gemaakt.

Aanvragen

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

Gebeurtenissen voor inrichten bewaken met behulp van de inrichtingslogboeken

Naast het bewaken van de status van de inrichtingstaak, kunt u de inrichtingslogboeken gebruiken om te zoeken naar alle gebeurtenissen die zich voordoen. Voer bijvoorbeeld een query uit voor een bepaalde gebruiker en bepaal of deze zijn ingericht.

Aanvragen

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

Inrichten configureren met behulp van Microsoft Graph-API's

Stap 1: De galerietoepassing maken

De id van de galerietoepassingssjabloon ophalen

Aanvragen

Response

De galerietoepassing maken

Aanvragen

Response

Stap 2: De inrichtingstaak maken op basis van de sjabloon

De sjabloon voor de inrichtingsconnector ophalen

Aanvragen

Response

De inrichtingstaak maken

Aanvragen

Response

Stap 3: Toegang autoriseren

De verbinding met de toepassing testen

Aanvragen

Response

Uw referenties opslaan

Aanvragen

Response

Stap 4: De inrichtingstaak starten

Aanvragen

Response

Stap 5: Het inrichten bewaken

Bewaak de status van de inrichtingstaak

Aanvragen

Response

Gebeurtenissen voor inrichten bewaken met behulp van de inrichtingslogboeken

Aanvragen

Response

Zie ook

Aanvullende resources

Inrichten configureren met behulp van Microsoft Graph-API's

Stap 1: De galerietoepassing maken

Meld u aan bij Microsoft Graph Explorer (aanbevolen), Postman of een andere API-client die u gebruikt

De id van de galerietoepassingssjabloon ophalen

Aanvragen

Response

De galerietoepassing maken

Aanvragen

Response

Stap 2: De inrichtingstaak maken op basis van de sjabloon

De sjabloon voor de inrichtingsconnector ophalen

Aanvragen

Response

De inrichtingstaak maken

Aanvragen

Response

Stap 3: Toegang autoriseren

De verbinding met de toepassing testen

Aanvragen

Response

Uw referenties opslaan

Aanvragen

Response

Stap 4: De inrichtingstaak starten

Aanvragen

Response

Stap 5: Het inrichten bewaken

Bewaak de status van de inrichtingstaak

Aanvragen

Response

Gebeurtenissen voor inrichten bewaken met behulp van de inrichtingslogboeken

Aanvragen

Response

Zie ook

Aanvullende resources