Configurar o provisionamento usando APIs do Microsoft Graph
O centro de administração do Microsoft Entra é uma maneira conveniente de configurar o provisionamento para aplicativos individuais, um de cada vez. Mas se você estiver criando várias — ou até centenas — de instâncias de um aplicativo ou migrando a configuração do aplicativo de um ambiente para outro, pode ser mais fácil automatizar a criação e a configuração de aplicativos com as APIs do Microsoft Graph. Este artigo descreve como automatizar a configuração de provisionamento por meio de APIs. Esse método é comumente usado para aplicativos como o Amazon Web Services.
Este artigo ilustra o processo com APIs no ponto de extremidade beta do Microsoft Graph e no Microsoft Graph Explorer, APIs semelhantes também estão disponíveis no ponto de extremidade do Microsoft Graph v1.0. Para obter um exemplo de configuração do provisionamento com o Graph v1.0 e o PowerShell, consulte as etapas 6 a 13 de Configurar a sincronização entre locatários usando o PowerShell ou a API do Microsoft Graph.
Visão geral das etapas para usar APIs do Microsoft Graph para automatizar a configuração de provisionamento
| Passo | Detalhes |
|---|---|
| Passo 1. Criar o aplicativo de galeria | Entrar no cliente de API Recuperar o modelo de aplicativo de galeria Criar o aplicativo de galeria |
| Passo 2. Criar trabalho de provisionamento com base no modelo | Recuperar o modelo para o conector de provisionamento Criar o trabalho de provisionamento |
| Passo 3. Autorizar acesso | Testar a conexão com o aplicativo Salve as credenciais |
| Passo 4. Iniciar o trabalho de provisionamento | Iniciar a tarefa |
| Passo 5. Monitorar o provisionamento | Verificar o status do trabalho de provisionamento Recuperar os logs de provisionamento |
Se você estiver provisionando para um aplicativo local, também precisará instalar e configurar o agente de provisionamento e atribuir o agente de provisionamento ao aplicativo.
Etapa 1: Criar o aplicativo de galeria
Entre no Microsoft Graph Explorer (recomendado), Postman ou qualquer outro cliente de API que você usa
- Inicie o Microsoft Graph Explorer.
- Selecione o botão "Entrar com a Microsoft" e entre com um usuário com a função de administrador de aplicativos .
- Após o início de sessão bem-sucedido, verá os detalhes da conta de utilizador no painel esquerdo.
Recuperar o identificador do modelo de aplicativo de galeria
Cada aplicativo na galeria de aplicativos do Microsoft Entra tem um modelo de aplicativo que descreve os metadados desse aplicativo. Usando esse modelo, você pode criar uma instância do aplicativo e da entidade de serviço em seu locatário para gerenciamento. Recupere o identificador do modelo de aplicativo para o AWS Single-Account Access e, a partir da resposta, registre o valor da propriedade id para usar posteriormente neste tutorial.
Pedir
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."
}
Criar o aplicativo de galeria
Use a ID do modelo recuperada para seu aplicativo na última etapa para criar uma instância do aplicativo e da entidade de serviço em seu locatário.
Pedir
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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"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": "bbbbbbbb-1111-2222-3333-cccccccccccc",
"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"
],
}
}
Etapa 2: Criar o trabalho de provisionamento com base no modelo
Recuperar o modelo para o conector de provisionamento
Os aplicativos na galeria habilitados para provisionamento têm modelos para simplificar a configuração. Use a solicitação abaixo para recuperar o modelo para a configuração de provisionamento. Tenha em atenção que terá de fornecer o documento de identificação. A ID é a do recurso servicePrincipal, criado na etapa anterior.
Pedir
GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/templates
Response
HTTP/1.1 200 OK
{
"value": [
{
"id": "aws",
"factoryTag": "aws",
"schema": {
"directories": [],
"synchronizationRules": []
}
}
]
}
Criar o trabalho de provisionamento
Para habilitar o provisionamento, primeiro você precisará criar um trabalho. Use a solicitação a seguir para criar um trabalho de provisionamento. Use o templateId da etapa anterior ao especificar o modelo a ser usado para o trabalho.
Pedir
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
}
}
Etapa 3: Autorizar o acesso
Testar a conexão com o aplicativo
Teste a conexão com o aplicativo de terceiros. O exemplo a seguir é para um aplicativo que requer um segredo do cliente e um token secreto. Cada aplicação tem os seus próprios requisitos. Os aplicativos geralmente usam um endereço base no lugar de um segredo do cliente. Para determinar quais credenciais seu aplicativo requer, vá para a página de configuração de provisionamento para seu aplicativo e, no modo de desenvolvedor, clique em testar conexão. O tráfego de rede mostrará os parâmetros usados para credenciais. Para obter uma lista completa de credenciais, consulte synchronizationJob: validateCredentials. A maioria dos aplicativos, como o Azure Databricks, depende de um BaseAddress e SecretToken. O BaseAddress é referido como um URL de inquilino no centro de administração do Microsoft Entra.
Pedir
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
Guarde as suas credenciais
A configuração do provisionamento requer o estabelecimento de uma relação de confiança entre a ID do Microsoft Entra e o aplicativo para autorizar o Microsoft Entra a ter a capacidade de chamar o aplicativo de terceiros. O exemplo a seguir é específico para um aplicativo que requer um segredo de cliente e um token secreto. Cada aplicação tem os seus próprios requisitos. Consulte a documentação da API para ver as opções disponíveis.
Pedir
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
Etapa 4: Iniciar o trabalho de provisionamento
Agora que o trabalho de provisionamento está configurado, use o seguinte comando para iniciá-lo.
Pedir
POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/start
Response
HTTP/1.1 204 No Content
Etapa 5: Monitorar o provisionamento
Monitorar o status do trabalho de provisionamento
Agora que o trabalho de provisionamento está em execução, use o seguinte comando para acompanhar o progresso. Cada trabalho de sincronização na resposta inclui o status do ciclo de provisionamento atual, bem como estatísticas até o momento, como o número de usuários e grupos que foram criados no sistema de destino.
Pedir
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"
}
]
}
]
}
Monitorar eventos de provisionamento usando os logs de provisionamento
Além de monitorar o status do trabalho de provisionamento, você pode usar os logs de provisionamento para consultar todos os eventos que estão ocorrendo. Por exemplo, consulte um usuário específico e determine se ele foi provisionado com êxito.
Pedir
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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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": "00001111-aaaa-2222-bbbb-3333cccc4444",
"ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
"ServicePrincipalDisplayName": "AWS Contoso"
}
},
"initiatedBy": {
"id": "",
"displayName": "Azure AD Provisioning Service",
"initiatorType": "system"
}
]
}
]
}
Consulte também
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários