Partilhar via

Configurar o provisionamento usando APIs do Microsoft Graph

  • Artigo

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.

  1. Inicie o Microsoft Graph Explorer.
  2. Selecione o botão "Entrar com a Microsoft" e entre com um usuário com a função de administrador de aplicativos .
  3. Após o início de sessão bem-sucedido, verá os detalhes da conta de utilizador no painel esquerdo.

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

}

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