Introdução às APIs de Gerenciamento do Office 365

  • Artigo

Quando você cria um aplicativo que precisa de acesso a serviços protegidos, como as APIs de Gerenciamento do Office 365, é necessário criar uma maneira de informar ao serviço se o aplicativo tem direito de acesso. As APIs de Gerenciamento de Office 365 usam Microsoft Entra ID para fornecer serviços de autenticação que você pode usar para conceder direitos para seu aplicativo acessá-los.

Há quatro etapas principais:

  1. Registre seu aplicativo no Microsoft Entra ID. Para permitir o acesso do aplicativo às APIs de Gerenciamento de Office 365, você precisa registrar seu aplicativo no Microsoft Entra ID. Isso permite que você estabeleça uma identidade para o aplicativo e especifique os níveis de permissão necessários para acessar as APIs.

  2. Obter o consentimento do administrador do locatário do Office 365. Um administrador do locatário do Office 365 deve conceder explicitamente o consentimento para permitir que seu aplicativo acesse os dados de locatário por meio das APIs de Gerenciamento do Office 365. O processo de consentimento é uma experiência baseada no navegador que exige que o administrador do locatário entre na interface do usuário de consentimento Microsoft Entra e examine as permissões de acesso que seu aplicativo está solicitando e, em seguida, conceda ou negue a solicitação. Após o consentimento, a IU redireciona o usuário de volta ao aplicativo com um código de autorização na URL. Seu aplicativo faz uma chamada de serviço a serviço para Microsoft Entra ID trocar esse código de autorização por um token de acesso, que contém informações sobre o administrador do locatário e seu aplicativo. A ID do locatário deve ser extraída do token de acesso e armazenada para uso futuro.

  3. Solicite tokens de acesso de Microsoft Entra ID. Usando as credenciais do aplicativo conforme configurado em Microsoft Entra ID, seu aplicativo solicita tokens de acesso adicionais para um locatário consentido em uma base contínua, sem a necessidade de mais interação de administrador de locatário. Esses tokens de acesso são chamados de tokens somente aplicativo porque não incluem informações sobre o administrador do locatário.

  4. Chamar as APIs de Gerenciamento do Office 365. Os tokens de acesso somente aplicativo são passados ​​para as APIs de Gerenciamento do Office 365 para autenticar e autorizar seu aplicativo.

O diagrama a seguir mostra a sequência de solicitações de consentimento e token de acesso.

Fluxo de autorizações de introdução às APIs de Gerenciamento

Importante

Para poder acessar dados por meio da API de Atividade de Gerenciamento do Office 365, habilite o log de auditoria unificado para a sua organização do Office 365. Para fazer isso, ative o log de auditoria do Office 365. Para obter instruções, confira Ativar ou desativar a pesquisa de log de auditoria do Office 365.

A habilitação do log de auditoria unificado não é necessária se você usa apenas a API de Comunicações de Serviço do Office 365.

Registrar seu aplicativo no Microsoft Entra ID

As APIs de Gerenciamento de Office 365 usam Microsoft Entra ID para fornecer autenticação segura para Office 365 dados de locatário. Para acessar as APIs de Gerenciamento de Office 365, você precisa registrar seu aplicativo no Microsoft Entra ID e, como parte da configuração, você especificará os níveis de permissão que seu aplicativo precisa para acessar as APIs.

Pré-requisitos

Para registrar seu aplicativo no Microsoft Entra ID, você precisa de uma assinatura para Office 365 e uma assinatura do Azure associada à sua assinatura Office 365. Você pode usar assinaturas de avaliação do Office 365 e do Azure para começar. Confira mais detalhes em Bem-vindo ao Programa para Desenvolvedores do Office 365.

Use o Portal do Azure para registrar seu aplicativo no Microsoft Entra ID

Depois de ter um locatário da Microsoft com as assinaturas adequadas, você pode registrar seu aplicativo no Microsoft Entra ID.

  1. Entre noportal do Azure, usando as credenciais do seu locatário da Microsoft que tem a assinatura do Office 365 que você deseja usar. Você também pode acessar o Portal do Azure através de um link que aparece no painel de navegação esquerdo no Centro de administração do Microsoft 365.

  2. No painel de navegação esquerdo, selecione Microsoft Entra ID (1).

    Página principal do Portal Azure

  3. Na página Microsoft Entra ID, selecione Registros de aplicativo (2) e selecione Novo registro (3).

    Registros de aplicativo página no Microsoft Entra ID

  4. Na página de Registros de Aplicativo, selecione Novo registro.

    Uma nova página aparecerá para você iniciar o registro do aplicativo.

  5. Na página Registrar um aplicativo, faça o seguinte:

    Processo de registro do aplicativo

    1. Nomeie seu aplicativo.

    2. Escolha quem pode usar o aplicativo e acessar a API.

    3. Forneça um URL de redirecionamento para o redirecionamento do usuário após a autenticação, se necessário.

  6. Clique em Registrar para registrar o novo aplicativo.

Configurar as propriedades do aplicativo no Microsoft Entra ID

Agora que seu aplicativo está registrado, há várias propriedades importantes que você deve especificar que determinam como seu aplicativo funciona dentro de Microsoft Entra ID e como os administradores de locatário concederão consentimento para permitir que seu aplicativo acesse seus dados usando as APIs de Gerenciamento de Office 365.

Para obter mais informações sobre Microsoft Entra configuração do aplicativo em geral, consulte Propriedades do Objeto de Aplicativo.

  1. ID do cliente. Esse valor é gerado automaticamente por Microsoft Entra ID. Seu aplicativo usará esse valor ao solicitar o consentimento de administradores de locatários e ao solicitar tokens somente de aplicativo de Microsoft Entra ID.

  2. O aplicativo é multilocatário. Essa propriedade deve ser definida como SIM para permitir que os administradores de locatários deem consentimento para que o aplicativo acesse seus dados usando as APIs de Gerenciamento do Office 365. Se essa propriedade for definida como NÃO, seu aplicativo só poderá acessar os dados do seu próprio locatário.

  3. URL de resposta. Esta é a URL para a qual um administrador de locatários será redirecionado após dar o consentimento para que o aplicativo acesse seus dados usando as APIs de Gerenciamento do Office 365. Você pode configurar várias URLs de resposta, conforme necessário. O Azure define automaticamente a primeira para corresponder à URL de logon especificada quando você criou o aplicativo, mas é possível alterar esse valor conforme necessário.

Escolha Salvar depois de fazer uma alteração nessas propriedades.

Gerar uma nova chave para o aplicativo

As chaves, também conhecidas como segredos do cliente, são usadas ao trocar um código de autorização por um token de acesso.

  1. Na página Microsoft Entra ID no portal do Azure, selecione Registros de aplicativo e selecione seu aplicativo.

    Selecione o aplicativo que você acabou de registrar

  2. Depois que a página do aplicativo for exibida, selecione Certificados e segredos (1) no painel esquerdo. Nesta página, você pode fazer o upload de certificados e criar novos segredos do cliente (2).

    A página de Certificados e segredos do aplicativo

  3. Na página Certificados e segredos (1), selecione Novo segredo do cliente (2), digite uma descrição e selecione a duração da sua chave (3) e, em seguida, selecione Adicionar (4).

    Criar um segredo do cliente

  4. Depois de criar o segredo do cliente, o valor será exibido em Segredos do cliente (2). Clique no ícone da área de transferência (3) para copiar o valor do segredo do cliente para a área de transferência.

    Copie o valor do segredo do cliente para a área de transferência e salve-o para uso posterior

    Importante

    O Azure só exibe o valor do segredo do cliente no momento em que você o gera inicialmente. Você não pode voltar a esta página e recuperar o valor do segredo do cliente mais tarde. Certifique-se de copiá-lo e salvá-lo em um local seguro para que você possa utilizá-lo mais tarde.

Configurar um certificado X.509 para habilitar as chamadas de serviço a serviço

Um aplicativo que está sendo executado em segundo plano, como um daemon ou serviço, pode usar credenciais de cliente para solicitar tokens de acesso somente aplicativo sem solicitar repetidamente o consentimento do administrador do locatário após o consentimento inicial.

Confira mais informações em Chamadas de serviço a serviço usando credenciais do cliente.

Você deve configurar um certificado X.509 com seu aplicativo para ser usado como credenciais do cliente ao solicitar tokens de acesso somente aplicativo de Microsoft Entra ID. Há duas etapas para o processo:

  • Obter um certificado X.509. Você pode usar um certificado autoassinado ou um certificado emitido pela autoridade de certificação confiável publicamente.

  • Modificar o manifesto do seu aplicativo para incluir a impressão digital e a chave pública do seu certificado.

As instruções a seguir mostram como usar a ferramenta makecert do Visual Studio ou do Windows SDK para gerar um certificado autoassinado e exportar a chave pública para um arquivo codificado em base64.

  1. Na linha de comando, execute o seguinte:

     makecert -r -pe -n "CN=MyCompanyName MyAppName Cert" -b 03/15/2015 -e 03/15/2017 -ss my -len 2048

    Observação

    Quando você estiver gerando o certificado X.509, verifique se o tamanho da chave é pelo menos 2048. Comprimentos de chave mais curtos não são aceitos como chaves válidas.

  2. Abra o snap-in do MMC dos Certificados e conecte-se à sua conta de usuário.

  3. Localize o novo certificado na pasta Pessoal e exporte a chave pública para um arquivo codificado em base64 (por exemplo, mycompanyname.cer). Seu aplicativo usará esse certificado para se comunicar com Microsoft Entra ID, portanto, certifique-se de manter o acesso à chave privada também.

    Observação

    Você pode usar o Windows PowerShell para extrair a chave pública codificada por impressão digital e base64. Outras plataformas fornecem ferramentas semelhantes para recuperar propriedades de certificados.

  4. Em um prompt Windows PowerShell, insira e execute o seguinte:

     $cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
 $cer.Import("mycer.cer")
 $bin = $cer.GetRawCertData()
 $base64Value = [System.Convert]::ToBase64String($bin)
 $bin = $cer.GetCertHash()
 $base64Thumbprint = [System.Convert]::ToBase64String($bin)
 $keyid = [System.Guid]::NewGuid().ToString()

  5. Armazene os valores para $base64Thumbprint, $base64Value e $keyid a serem usados ​​quando você atualizar o manifesto do aplicativo no próximo conjunto de etapas.

    Usando os valores extraídos do certificado e da ID da chave gerada, agora você deve atualizar o manifesto do aplicativo em Microsoft Entra ID.

  6. No Portal do Azure, acesse Registros de aplicativos>Todos os aplicativos , selecione seu aplicativo e, em seguida, selecione Manifesto no painel esquerdo.

  7. Na barra de navegação superior da página Manifesto (1), selecione Baixar (2).

    Baixe o manifesto para que você possa editá-lo

  8. Abra o manifesto baixado em um editor e substitua a propriedade keyCredentials vazia pelo seguinte JSON:

       "keyCredentials": [
     {
         "customKeyIdentifier" : "$base64Thumbprint_from_above",
         "keyId": "$keyid_from_above",
         "type": "AsymmetricX509Cert",
         "usage": "Verify",
         "value": "$base64Value_from_above"
     }
 ],

    Observação

    A propriedade KeyCredentials é uma coleção, possibilitando o upload de vários certificados X.509 para cenários de sobreposição ou a exclusão de certificados para cenários de comprometimento.

  9. Salve suas alterações e faça o upload do manifesto atualizado escolhendo Gerenciar Manifesto na barra de comandos, escolhendo Carregar Manifesto, navegando até o arquivo de manifesto atualizado e selecionando-o.

Especificar as permissões que o aplicativo requer para acessar as APIs de Gerenciamento do Office 365

Por fim, você precisa especificar exatamente quais permissões seu aplicativo requer das APIs de Gerenciamento do Office 365. Para isso, adicione acesso às APIs de Gerenciamento do Office 365 ao seu aplicativo e especifique as permissões necessárias.

  1. No Portal do Azure, acesse Registros de aplicativos>Todos os aplicativos, selecione seu aplicativo e, em seguida, selecione Permissões de API (1) no painel esquerdo. Clique em Adicionar uma permissão (2) para exibir a página do submenu Solicitação de permissão de API (3).

    Adicionar permissões de API

  2. Na guia APIs da Microsoft, selecione APIs de Gerenciamento do Office 365 (4).

    Selecione as APIs de Gerenciamento do Office 365 na guia de APIs da Microsoft

  3. Na página de submenu, selecione os seguintes tipos de permissões (3) exigidos pelo aplicativo e clique em Adicionar permissões

    Selecione os tipos de permissões para seu aplicativo

    1. Permissões delegadas. Permite que seu aplicativo cliente execute operações em nome do usuário conectado, como a leitura de email ou a modificação do perfil do usuário.

    2. Permissões de Aplicativos. Permissões que possibilitam que o aplicativo cliente se autentique como ele mesmo sem interação ou consentimento do usuário, como um aplicativo usado por serviços em segundo plano ou aplicativos daemon.

  4. As APIs de Gerenciamento do Office agora aparecem na lista de aplicativos para os quais seu aplicativo exige permissões. Em Permissões do aplicativo e Permissões delegadas, se necessário, selecione as permissões exigidas pelo aplicativo. Confira mais detalhes sobre cada permissão na referência da API específica.

    Permissões de API para seu aplicativo

  5. Selecione Conceder consentimento de administrador para “nome do locatário" para consentir com as permissões concedidas ao seu aplicativo.

Agora que o aplicativo está configurado com as permissões necessárias para usar as APIs de Gerenciamento do Office 365, um administrador de locatário deve conceder explicitamente ao seu aplicativo essas permissões para acessar os dados de seus locatários usando as APIs. Para conceder o consentimento, o administrador do locatário deve entrar no Microsoft Entra ID usando a URL especialmente construída a seguir, na qual eles podem revisar as permissões solicitadas do aplicativo. Esta etapa não é necessária ao usar as APIs para acessar dados de seu próprio locatário.

https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fmanage.office.com&client_id={your_client_id}&redirect_uri={your_redirect_url }

A URL de redirecionamento deve corresponder ou ser um sub-caminho em uma das URLs de resposta configuradas para seu aplicativo em Microsoft Entra ID.

Por exemplo:

https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fmanage.office.com&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e&redirect_uri=http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F

Você pode testar a URL de consentimento colando-a em um navegador e entrando usando as credenciais de um administrador do Office 365 para um locatário que não seja o usado para registrar o aplicativo. Você verá a solicitação para conceder ao seu aplicativo permissão para usar as APIs de Gerenciamento do Office.

Página de consentimento de permissões

Depois de escolher Aceitar, você será redirecionado para a página especificada, e haverá um código na cadeia de caracteres de consulta.

Por exemplo:

http://www.mycompany.com/myapp/?code=AAABAAAAvPM1KaPlrEqdFSB...

Seu aplicativo usa esse código de autorização para obter um token de acesso de Microsoft Entra ID, do qual a ID do locatário pode ser extraída. Depois de extrair e armazenar a ID do locatário, você poderá obter os tokens de acesso subsequentes sem exigir que o administrador do locatário se conecte.

Solicitar tokens de acesso de Microsoft Entra ID

Há dois métodos para solicitar tokens de acesso de Microsoft Entra ID:

  • O Fluxo de Concessão do Código de Autorização envolve um administrador do locatário que dá o consentimento explícito, que retorna um código de autorização para o aplicativo. Seu aplicativo então troca o código de autorização por um token de acesso. Este método é necessário para obter o consentimento inicial de que seu aplicativo precisa para acessar os dados do locatário usando a API, e esse primeiro token de acesso é necessário para obter e armazenar o ID do locatário.

  • O Fluxo de Concessão de Credenciais do Cliente permite que seu aplicativo solicite tokens de acesso subsequentes à medida que os antigos expirem, sem exigir que o administrador do locatário faça login e dê explicitamente o consentimento. Esse método deve ser usado para aplicativos que são executados continuamente em segundo plano chamando as APIs depois que o consentimento inicial do administrador do locatário é dado.

Solicitar um token de acesso usando o código de autorização

Depois que um administrador de locatário concede consentimento, seu aplicativo recebe um código de autorização como um parâmetro de cadeia de caracteres de consulta quando Microsoft Entra ID redireciona o administrador de locatário para sua URL designada.

http://www.mycompany.com/myapp/?code=AAABAAAAvPM1KaPlrEqdFSB...

Seu aplicativo faz um POST HTTP REST para Microsoft Entra ID para trocar o código de autorização por um token de acesso. Como a ID do locatário ainda não é conhecida, o POST será para o ponto de extremidade "comum", que não possui a ID do locatário incorporada à URL:

https://login.windows.net/common/oauth2/token

O corpo do POST contém o seguinte:

resource=https%3A%2F%2Fmanage.office.com&client_id=a6099727-6b7b-482c-b509-1df309acc563 &redirect_uri= http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F &client_secret={your_client_key}&grant_type=authorization_code&code= AAABAAAAvPM1KaPlrEqdFSB...

Solicitação de amostra

POST https://login.windows.net/common/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.windows.net
Content-Length: 944

resource=https%3A%2F%2Fmanage.office.com&client_id=a6099727-6b7b-482c-b509-1df309acc563 &redirect_uri= http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F &client_secret={your_client_key}&grant_type=authorization_code&code=AAABAAAAvPM1KaPlrEqdFSB...

O corpo da resposta incluirá várias propriedades, inclusive o token de acesso.

Resposta de amostra

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 3265

{"expires_in":"3599","token_type":"Bearer","scope":"ActivityFeed.Read ActivityReports.Read ServiceHealth.Read","expires_on":"1438290275","not_before":"1438286375","resource":"https://manage.office.com","access_token":"eyJ0eX...","refresh_token":"AAABAAA...","id_token":"eyJ0eXAi..."}

O token de acesso retornado é um token JWT que inclui informações sobre o administrador que deu o consentimento e o aplicativo que está solicitando acesso. A seguir temos um exemplo de um token não codificado. O aplicativo deve extrair a ID de locatário "tid" desse token e armazená-la para que ela possa ser usada para solicitar tokens de acesso adicionais à medida que eles expiram, sem interação administrativa posterior.

Token de amostra

{
  "aud": "https://manage.office.com",
  "iss": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "iat": 1427246416,
  "nbf": 1427246416,
  "exp": 1427250316,
  "ver": "1.0",
  "tid": "41463f53-8812-40f4-890f-865bf6e35190",
  "amr": [
    "pwd"
  ],
  "oid": "1cef1fdb-ff52-48c4-8e4e-dfb5ea83d357",
  "upn": "admin@contoso.onmicrosoft.com",
  "puid": "1003BFFD8EC47CA6",
  "sub": "7XpD5OWAXM1OWmKiVKh1FOkKXV4N3OSRol6mz1pxxhU",
  "given_name": "John",
  "family_name": "Doe",
  "name": "Contoso, Inc.",
  "unique_name": "admin@contoso.onmicrosoft.com",
  "appid": "a6099727-6b7b-482c-b509-1df309acc563",
  "appidacr": "1",
  "scp": "ActivityFeed.Read ServiceHealth.Read",
  "acr": "1"
}

Solicitar um token de acesso usando credenciais de cliente

Depois que a ID do locatário for conhecida, seu aplicativo poderá fazer chamadas de serviço em serviço para Microsoft Entra ID para solicitar tokens de acesso adicionais à medida que expirarem. Esses tokens incluem informações apenas sobre o aplicativo solicitante e não sobre o administrador que originalmente deu o consentimento. Chamadas de serviço a serviço requerem que seu aplicativo use um certificado X.509 para criar uma declaração de cliente na forma de um token de portador JWT assinado em SHA256 codificado em base64.

Quando desenvolve seu aplicativo no .NET, você pode usar a Biblioteca de Autenticação do Azure AD (ADAL) para criar declarações de clientes. Outras plataformas de desenvolvimento devem ter bibliotecas semelhantes.

Um token JWT não codificado consiste em um cabeçalho e o conteúdo com as seguintes propriedades.

HEADER:

{
  "alg": "RS256",
  "x5t": "{thumbprint of your X.509 certificate used to sign the token",
}

PAYLOAD:

{
  "aud": "https://login.windows.net/{tenantid}/oauth2/token",
  "iss": "{your app client ID}",
  "sub": "{your app client ID}",
  "jti": "{random GUID}",
  "nbf": "{epoch time, before which the token is not valid}",
  "exp": "{epoch time, after which the token is not valid}"
}

Token JWT de amostra

HEADER:

{
  "alg": "RS256",
  "x5t": "YyfshJC3rPQ-kpGo5dUaiY5t3iU",
}

PAYLOAD:

{
  "aud": "https://login.windows.net/41463f53-8812-40f4-890f-865bf6e35190/oauth2/token",
  "iss": "a6099727-6b7b-482c-b509-1df309acc563",
  "sub": "a6099727-6b7b-482c-b509-1df309acc563",
  "jti": "0ce254c4-81b1-4a2e-8436-9a8c3b49dfb9",
  "nbf": 1427248048,
  "exp": 1427248648,
}

A declaração do cliente é então passada para Microsoft Entra ID como parte de uma chamada de serviço para serviço para solicitar um token de acesso. Ao usar as credenciais do cliente para solicitar um token de acesso, use um HTTP POST para um ponto de extremidade específico do locatário, onde a ID do locatário previamente extraída e armazenada é incorporada na URL.

https://login.windows.net/{tenantid}/oauth2/token

O corpo do POST contém o seguinte:

resource=https%3A%2F%2Fmanage.office.com&client_id={your_app_client_id}&grant_type=client_credentials&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion={encoded_signed_JWT_token}

Solicitação de amostra

POST https://login.windows.net/41463f53-8812-40f4-890f-865bf6e35190/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.windows.net
Content-Length: 994

resource=https%3A%2F%2Fmanage.office.com&client_id= a6099727-6b7b-482c-b509-1df309acc563&grant_type=client_credentials &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Ill5ZnNoSkMzclBRLWtwR281ZFVhaVk1dDNpVSJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ud2luZG93cy5uZXRcLzQxNDYzZjUzLTg4MTItNDBmNC04OTBmLTg2NWJmNmUzNTE5MFwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQyNzI0ODY0OCwiaXNzIjoiYTYwOTk3MjctNmI3Yi00ODJjLWI1MDktMWRmMzA5YWNjNTYzIiwianRpIjoiMGNlMjU0YzQtODFiMS00YTJlLTg0MzYtOWE4YzNiNDlkZmI5IiwibmJmIjoxNDI3MjQ4MDQ4LCJzdWIiOiJhNjA5OTcyNy02YjdiLTQ4MmMtYjUwOS0xZGYzMDlhY2M1NjMifQ.vfDrmCjiXgoj2JrTkwyOpr-NOeQTzlXQcGlKGNpLLe0oh4Zvjdcim5C7E0UbI3Z2yb9uKQdx9G7GeqS-gVc9kNV_XSSNP4wEQj3iYNKpf_JD2ikUVIWBkOg41BiTuknRJAYOMjiuBE2a6Wyk-vPCs_JMd7Sr-N3LiNZ-TjluuVzWHfok_HWz_wH8AzdoMF3S0HtrjNd9Ld5eI7MVMt4OTpRfh-Syofi7Ow0HN07nKT5FYeC_ThBpGiIoODnMQQtDA2tM7D3D6OlLQRgLfI8ir73PVXWL7V7Zj2RcOiooIeXx38dvuSwYreJYtdphmrDBZ2ehqtduzUZhaHL1iDvLlw

A resposta será a mesma de antes, mas o token não terá as mesmas propriedades porque não contém propriedades do administrador que deu o consentimento.

Resposta de amostra

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1276

{"token_type":"Bearer","expires_in":"3599","expires_on":"1431659094","not_before":"1431655194","resource":"https://manage.office.com","access_token":"eyJ0eXAiOiJKV1QiL..."}

Token de acesso de amostra

{
  "aud": "https://manage.office.com",
  "iss": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "iat": 1431655194,
  "nbf": 1431655194,
  "exp": 1431659094,
  "ver": "1.0",
  "tid": "41463f53-8812-40f4-890f-865bf6e35190",
  "roles": [
    "ServiceHealth.Read",
    "ActivityFeed.Read"
  ],
  "oid": "67cb0334-e242-4783-8028-0f39132fb5ad",
  "sub": "67cb0334-e242-4783-8028-0f39132fb5ad",
  "idp": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "appid": "a6099727-6b7b-482c-b509-1df309acc563",
  "appidacr": "1"
}

Criar seu aplicativo

Agora que você registrou seu aplicativo no Microsoft Entra ID e o configurou com as permissões necessárias, você está pronto para criar seu aplicativo. Veja a seguir alguns dos principais aspectos a serem considerados ao projetar e criar seu aplicativo.

  • A experiência de consentimento. Para obter o consentimento de seus clientes, você deve direcioná-los em um navegador para o site Microsoft Entra, usando a URL especialmente construída descrita anteriormente, e você deve ter um site para o qual Microsoft Entra ID redirecionará o administrador assim que concederem o consentimento. Este site deve extrair o código de autorização da URL e usá-lo para solicitar um token de acesso do qual possa obter a ID do locatário.

  • Armazenamento da ID do locatário em seu sistema. Isso será necessário ao solicitar tokens de acesso de Microsoft Entra ID e ao chamar as APIs de Gerenciamento do Office.

  • Gerenciar tokens de acesso. Você precisará de um componente que solicite e gerencie tokens de acesso conforme necessário. Se seu aplicativo chamar as APIs periodicamente, ele poderá solicitar tokens sob demanda ou, se chamar as APIs continuamente para recuperar dados, poderá solicitar tokens em intervalos regulares (por exemplo, a cada 45 minutos).

  • Implementar um ouvinte do webhook. Conforme necessário pela API específica que você está usando.

  • Recuperação e armazenamento de dados. Você precisará de um componente que recupere dados para cada locatário, usando a pesquisa contínua ou em resposta às notificações do webhook, dependendo da API específica que estiver usando.