Configurar o provisionamento usando APIs do Microsoft Graph

  • Artigo

O centro de administração do Microsoft Entra é uma maneira conveniente de configurar o provisionamento de 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 do aplicativo com as APIs do Microsoft Graph. Este artigo descreve como automatizar a configuração de provisionamento por meio de APIs. Esse método é usado normalmente 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 como configurar o provisionamento com o Graph v1.0 e o PowerShell, consulte as etapas de 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

Etapa Detalhes
Etapa 1. Criar o aplicativo de galeria Entrar no cliente da API
Recuperar o modelo de aplicativo da galeria
Criar o aplicativo de galeria
Etapa 2. Criar trabalho de provisionamento com base no modelo Recuperar o modelo do conector de provisionamento
Criar o trabalho de provisionamento
Etapa 3. Autorizar o acesso Testar a conexão com o aplicativo
Salvar as credenciais
Etapa 4. Iniciar o trabalho de provisionamento Iniciar o trabalho
Etapa 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 atribui-lo ao aplicativo.

  1. Inicie o Microsoft Graph Explorer.
  2. Selecione o botão “Entrar com a Microsoft” e se conecte usando as credenciais do administrador de aplicativos ou do administrador global do Microsoft Entra.
  3. Depois de entrar, você verá os detalhes da conta de usuário no painel esquerdo.

Os aplicativos da galeria de aplicativos do Microsoft Entra têm um modelo de aplicativo que descreve os metadados do aplicativo. Usando esse modelo, é possível criar uma instância do aplicativo e a entidade de serviço em seu locatário para gerenciamento. Recupere o identificador do modelo do aplicativo para Acesso à Conta Única do AWS e na resposta, registre o valor da propriedade id para usar posteriormente neste tutorial.

Solicitação

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

Resposta

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 de modelo que você recuperou para o aplicativo na última etapa para criar uma instância do aplicativo e da entidade de serviço em seu locatário.

Solicitação

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

{
  "displayName": "AWS Contoso"
}

Resposta

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

Etapa 2: criar o trabalho de provisionamento com base no modelo

Recuperar o modelo do conector de provisionamento

Os aplicativos na galeria que estão 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. Observe que será necessário fornecer a ID. A ID é a do recurso servicePrincipal, criado na etapa anterior.

Solicitar

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

Resposta

HTTP/1.1 200 OK

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

Criar o trabalho de provisionamento

Para habilitar o provisionamento, primeiro é preciso criar um trabalho. Use a solicitação a seguir para criar um trabalho de provisionamento. Use a templateId da etapa anterior ao especificar o modelo a ser usado para o trabalho.

Solicitação

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

{ 
    "templateId": "aws"
}

Resposta

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 aplicativo tem requisitos próprios. Os aplicativos geralmente usam um endereço básico no lugar de um segredo do cliente. Para determinar quais credenciais seu aplicativo exige, vá para a página de configuração de provisionamento e, no modo de desenvolvedor, clique em Testar conexão. O tráfego de rede mostrará os parâmetros usados para as credenciais. Para ver uma lista completa de credenciais, confira synchronizationJob: validateCredentials. A maioria dos aplicativos, como Azure Databricks, baseia-se em um BaseAddress e SecretToken. O BaseAddress é chamado de URL do locatário no centro de administração do Microsoft Entra.

Solicitação

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

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

Resposta

HTTP/1.1 204 No Content

Salvar suas credenciais

Configurar o provisionamento requer estabelecer uma relação de confiança entre o Microsoft Entra ID 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 do cliente e um token secreto. Cada aplicativo tem requisitos próprios. Leia a documentação da API para ver as opções disponíveis.

Solicitação

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

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

Resposta

HTTP/1.1 204 No Content

Etapa 4: iniciar o trabalho de provisionamento

Agora que o trabalho de provisionamento está configurado, use o comando a seguir para iniciar o trabalho.

Solicitação

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

Resposta

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 comando a seguir 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.

Solicitar

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

Resposta

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 eles foram provisionados com êxito.

Solicitação

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

Resposta

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

Confira também