Konfigurera etablering med hjälp av Microsoft Graph-API:er

  • Artikel

Administrationscentret för Microsoft Entra är ett praktiskt sätt att konfigurera etablering för enskilda appar en i taget. Men om du skapar flera eller till och med hundratals instanser av ett program, eller migrerar programkonfiguration från en miljö till en annan, kan det vara enklare att automatisera skapandet och konfigurationen av appar med Microsoft Graph-API:erna. Den här artikeln beskriver hur du automatiserar etableringskonfigurationen via API:er. Den här metoden används ofta för program som Amazon Web Services.

Den här artikeln illustrerar processen med API:er i Microsoft Graph-betaslutpunkten och Microsoft Graph Explorer. Liknande API:er finns också i Microsoft Graph v1.0-slutpunkten. Ett exempel på hur du konfigurerar etablering med Graph v1.0 och PowerShell finns i steg 6–13 i Konfigurera synkronisering mellan klientorganisationer med PowerShell eller Microsoft Graph API.

Översikt över steg för att använda Microsoft Graph-API:er för att automatisera etableringskonfigurationen

Steg Details
Steg 1. Skapa galleriprogrammet Logga in på API-klienten
Hämta galleriprogrammallen
Skapa galleriprogrammet
Steg 2. Skapa etableringsjobb baserat på mall Hämta mallen för etableringsanslutningsappen
Skapa etableringsjobbet
Steg 3. Auktorisera åtkomst Testa anslutningen till programmet
Spara autentiseringsuppgifterna
Steg 4. Starta etableringsjobb Starta jobbet
Steg 5. Övervaka etablering Kontrollera status för etableringsjobbet
Hämta etableringsloggarna

Om du etablerar till ett lokalt program måste du även installera och konfigurera etableringsagenten och tilldela etableringsagenten till programmet.

  1. Starta Microsoft Graph Explorer.
  2. Välj knappen "Logga in med Microsoft" och logga in med microsoft entra global administratör eller appadministratörsautentiseringsuppgifter.
  3. När inloggningen lyckades visas information om användarkontot i den vänstra rutan.

Program i Microsoft Entra-programgalleriet har var och en en programmall som beskriver metadata för programmet. Med den här mallen kan du skapa en instans av programmet och tjänstens huvudnamn i klientorganisationen för hantering. Hämta identifieraren för programmallen för åtkomst med ett enda AWS-konto och från svaret registrerar du värdet för den ID-egenskap som ska användas senare i den här självstudien.

Begär

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

}

Använd mall-ID:t som hämtades för ditt program i det sista steget för att skapa en instans av programmet och tjänstens huvudnamn i klientorganisationen.

Begär

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

Steg 2: Skapa etableringsjobbet baserat på mallen

Hämta mallen för etableringsanslutningsappen

Program i galleriet som är aktiverade för etablering har mallar för att effektivisera konfigurationen. Använd begäran nedan för att hämta mallen för etableringskonfigurationen. Observera att du måste ange ID:t. ID:t är servicePrincipal-resursen som skapades i föregående steg.

Begär

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

Response

HTTP/1.1 200 OK

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

Skapa etableringsjobbet

För att aktivera etablering måste du först skapa ett jobb. Använd följande begäran för att skapa ett etableringsjobb. Använd templateId från föregående steg när du anger mallen som ska användas för jobbet.

Begär

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

Steg 3: Auktorisera åtkomst

Testa anslutningen till programmet

Testa anslutningen till programmet från tredje part. Följande exempel är för ett program som kräver en klienthemlighet och en hemlig token. Varje program har sina egna krav. Program använder ofta en basadress i stället för en klienthemlighet. Om du vill ta reda på vilka autentiseringsuppgifter din app kräver går du till konfigurationssidan för ditt program och klickar på Testa anslutning i utvecklarläge. Nätverkstrafiken visar de parametrar som används för autentiseringsuppgifter. En fullständig lista över autentiseringsuppgifter finns i synkroniseringsjobb: validateCredentials. De flesta program, till exempel Azure Databricks, förlitar sig på en BaseAddress och SecretToken. BaseAddress kallas en klient-URL i administrationscentret för Microsoft Entra.

Begär

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

Spara dina autentiseringsuppgifter

För att konfigurera etablering krävs att ett förtroende upprättas mellan Microsoft Entra-ID och programmet för att ge Microsoft Entra möjlighet att anropa programmet från tredje part. Följande exempel är specifikt för ett program som kräver en klienthemlighet och en hemlig token. Varje program har sina egna krav. Granska API-dokumentationen för att se tillgängliga alternativ.

Begär

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

Steg 4: Starta etableringsjobbet

Nu när etableringsjobbet har konfigurerats använder du följande kommando för att starta jobbet.

Begär

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

Response

HTTP/1.1 204 No Content

Steg 5: Övervaka etablering

Övervaka status för etableringsjobbet

Nu när etableringsjobbet körs använder du följande kommando för att spåra förloppet. Varje synkroniseringsjobb i svaret innehåller status för den aktuella etableringscykeln samt statistik hittills, till exempel antalet användare och grupper som har skapats i målsystemet.

Begär

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

Övervaka etableringshändelser med hjälp av etableringsloggarna

Förutom att övervaka statusen för etableringsjobbet kan du använda etableringsloggarna för att fråga efter alla händelser som inträffar. Fråga till exempel efter en viss användare och ta reda på om de har etablerats.

Begär

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

Se även