Microsoft Graph API를 사용하여 프로비저닝 구성

아티클
04/06/2024

Microsoft Entra 관리 센터는 한 번에 하나씩 개별 앱에 대한 프로비전을 구성하는 편리한 방법입니다. 그러나 애플리케이션 인스턴스를 여러 개 또는 수백 개 만들거나 애플리케이션 구성을 한 환경에서 다른 환경으로 마이그레이션하는 경우 Microsoft Graph API를 사용하여 앱 만들기 및 구성을 자동화하는 것이 더 쉬울 수 있습니다. 이 문서에서는 API를 통해 프로비저닝 구성을 자동화하는 방법을 설명합니다. 이 방법은 Amazon Web Services와 같은 애플리케이션에서 일반적으로 사용됩니다.

이 문서에서는 Microsoft Graph 베타 엔드포인트 및 Microsoft Graph Explorer의 API를 사용하는 프로세스를 보여 줍니다. 유사한 API는 Microsoft Graph v1.0 엔드포인트에서도 사용할 수 있습니다. Graph v1.0 및 PowerShell을 사용하여 프로비저닝을 구성하는 예제는 PowerShell 또는 Microsoft Graph API를 사용하여 테넌트 간 동기화 구성의 6-13단계를 참조하세요.

Microsoft Graph API를 사용하여 프로비저닝 구성을 자동화하는 단계 개요

단계	세부 정보
1단계 갤러리 애플리케이션 만들기	API 클라이언트에 로그인 갤러리 애플리케이션 템플릿 검색 갤러리 애플리케이션 만들기
2단계. 템플릿을 기준으로 프로비저닝 작업 만들기	프로비저닝 커넥터에 대한 템플릿 검색 프로비저닝 작업 만들기
3단계: 액세스 권한 부여	애플리케이션에 대한 연결 테스트 자격 증명 저장
4단계. 프로비저닝 작업 시작	작업 시작
5단계 프로비저닝 모니터링	프로비저닝 작업 상태 확인 프로비저닝 로그 검색

온-프레미스 애플리케이션에 프로비전하는 경우 프로비전 에이전트를 설치 및 구성하고 프로비전 에이전트를 애플리케이션에 할당해야 합니다.

1단계: 갤러리 애플리케이션 만들기

Microsoft Graph Explorer를 시작합니다.
“Microsoft에 로그인” 단추를 선택하고 Microsoft Entra 전역 관리자 또는 앱 관리자 자격 증명을 사용하여 로그인합니다.
로그인에 성공하면 왼쪽 창에 사용자 계정 세부 정보가 표시됩니다.

갤러리 애플리케이션 템플릿 식별자 검색

Microsoft Entra 애플리케이션 갤러리의 각 애플리케이션에는 해당 애플리케이션의 메타데이터를 설명하는 애플리케이션 템플릿이 있습니다. 이 템플릿을 사용하여 테넌트에서 관리를 위해 애플리케이션 및 서비스 주체의 인스턴스를 만들 수 있습니다. AWS Single-Account Access에 대한 애플리케이션 템플릿의 식별자를 검색하고 응답에서 이 자습서의 후반부에서 사용할 id 속성 값을 기록해 둡니다.

Request

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

응답

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

}

갤러리 애플리케이션 만들기

전 단계에서 애플리케이션에 대해 검색한 템플릿 ID를 사용하여 테넌트에서 애플리케이션 및 서비스 주체의 인스턴스를 만듭니다.

Request

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

{
  "displayName": "AWS Contoso"
}

응답

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

2단계: 템플릿을 기준으로 프로비저닝 작업 만들기

프로비저닝 커넥터에 대한 템플릿 검색

프로비저닝을 위해 설정된 갤러리의 애플리케이션에는 구성을 간소화하기 위한 템플릿이 있습니다. 아래 요청을 사용하여 프로비저닝 구성에 대한 템플릿을 검색합니다. ID를 제공해야 합니다. ID는 이전 단계에서 만든 servicePrincipal 리소스의 ID입니다.

Request

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

응답

HTTP/1.1 200 OK

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

프로비저닝 작업 만들기

프로비저닝을 사용하도록 설정하려면 먼저 작업을 만들어야 합니다. 다음 요청을 사용하여 프로비저닝 작업을 만듭니다. 작업에 사용할 템플릿을 지정할 때 이전 단계의 templateId을 사용합니다.

Request

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

{ 
    "templateId": "aws"
}

응답

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

3단계: 액세스 권한 부여

애플리케이션에 대한 연결 테스트

타사 애플리케이션에 대한 연결을 테스트합니다. 다음 예제는 클라이언트 암호 및 비밀 토큰이 필요한 애플리케이션에 대한 것입니다. 각 애플리케이션에는 자체 요구 사항이 있습니다. 애플리케이션은 종종 클라이언트 암호 대신 기본 주소를 사용합니다. 앱에 필요한 자격 증명을 확인하려면 애플리케이션의 프로비저닝 구성 페이지로 이동하고 개발자 모드에서 연결 테스트를 클릭합니다. 네트워크 트래픽은 자격 증명에 사용되는 매개 변수를 표시합니다. 자격 증명의 전체 목록은 synchronizationJob: validateCredentials를 참조하세요. Azure Databricks와 같은 대부분의 애플리케이션은 BaseAddress 및 SecretToken을 사용합니다. BaseAddress를 Microsoft Entra 관리 센터에서는 테넌트 URL이라고 합니다.

Request

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

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

응답

HTTP/1.1 204 No Content

자격 증명 저장

프로비저닝을 구성하려면 Microsoft Entra ID와 애플리케이션 간에 트러스트를 설정하여 타사 애플리케이션을 호출할 수 있는 권한을 Microsoft Entra에 부여해야 합니다. 다음 예제는 클라이언트 암호 및 비밀 토큰이 필요한 애플리케이션과 관련이 있습니다. 각 애플리케이션에는 자체 요구 사항이 있습니다. API 설명서를 검토하여 사용 가능한 옵션을 확인합니다.

Request

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

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

응답

HTTP/1.1 204 No Content

4단계: 프로비저닝 작업 시작

이제 프로비저닝 작업이 구성되었으므로 다음 명령을 사용하여 작업을 시작합니다.

Request

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

응답

HTTP/1.1 204 No Content

5단계: 프로비저닝 모니터링

프로비저닝 작업 상태 모니터링

이제 프로비전 작업이 실행 중이므로 다음 명령을 사용하여 진행률을 추적합니다. 응답의 각 동기화 작업에는 현재 프로비전 주기의 상태 대상 시스템에서 만든 사용자 및 그룹 수와 같은 현재까지의 통계가 포함됩니다.

Request

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

응답

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

프로비저닝 로그를 사용하여 프로비저닝 이벤트 모니터링

프로비저닝 작업의 상태를 모니터링하는 것 외에도 프로비저닝 로그를 사용하여 발생하는 모든 이벤트를 쿼리할 수 있습니다. 예를 들어, 특정 사용자를 쿼리하고 성공적으로 프로비저닝되었는지 확인합니다.

Request

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

응답

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

Microsoft Graph API를 사용하여 프로비저닝 구성

1단계: 갤러리 애플리케이션 만들기

갤러리 애플리케이션 템플릿 식별자 검색

Request

응답

갤러리 애플리케이션 만들기

Request

응답

2단계: 템플릿을 기준으로 프로비저닝 작업 만들기

프로비저닝 커넥터에 대한 템플릿 검색

Request

응답

프로비저닝 작업 만들기

Request

응답

3단계: 액세스 권한 부여

애플리케이션에 대한 연결 테스트

Request

응답

자격 증명 저장

Request

응답

4단계: 프로비저닝 작업 시작

Request

응답

5단계: 프로비저닝 모니터링

프로비저닝 작업 상태 모니터링

Request

응답

프로비저닝 로그를 사용하여 프로비저닝 이벤트 모니터링

Request

응답

참고 항목

추가 리소스

Microsoft Graph API를 사용하여 프로비저닝 구성

1단계: 갤러리 애플리케이션 만들기

Microsoft Graph Explorer(권장), Postman 또는 그 밖의 API 클라이언트에 로그인

갤러리 애플리케이션 템플릿 식별자 검색

Request

응답

갤러리 애플리케이션 만들기

Request

응답

2단계: 템플릿을 기준으로 프로비저닝 작업 만들기

프로비저닝 커넥터에 대한 템플릿 검색

Request

응답

프로비저닝 작업 만들기

Request

응답

3단계: 액세스 권한 부여

애플리케이션에 대한 연결 테스트

Request

응답

자격 증명 저장

Request

응답

4단계: 프로비저닝 작업 시작

Request

응답

5단계: 프로비저닝 모니터링

프로비저닝 작업 상태 모니터링

Request

응답

프로비저닝 로그를 사용하여 프로비저닝 이벤트 모니터링

Request

응답

참고 항목

추가 리소스