Configurar o gerenciador de credenciais – API do Microsoft Graph

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

Este artigo orienta você nas etapas necessárias para criar uma conexão gerenciada com a API do Microsoft Graph dentro do Gerenciamento de API do Azure. O tipo de concessão do código de autorização é usado neste exemplo.

Você aprenderá como:

  • Criar um aplicativo do Microsoft Entra
  • Criar e configurar um provedor de credenciais no Gerenciamento de API
  • Configurar uma conexão
  • Criar uma API do Microsoft Graph no Gerenciamento de API e configurar uma política
  • Testar sua API do Microsoft Graph no Gerenciamento de API

Pré-requisitos

Etapa 1: criar um aplicativo do Microsoft Entra

Crie um aplicativo Microsoft Entra para a API e dê a ele as permissões apropriadas para as solicitações que você deseja chamar.

  1. Entre no portal do Azure com uma conta com permissões suficientes no locatário.

  2. Em Serviços do Azure, procure Microsoft Entra ID.

  3. No menu à esquerda, selecione Registros de aplicativo e escolha Novo registro.

  4. Na página Registrar um aplicativo, insira as configurações de registro do aplicativo:

    1. Em Nome, insira um nome relevante que será exibido aos usuários do aplicativo, como MicrosoftGraphAuth.

    2. Em Tipos de conta com suporte, selecione uma opção que atenda ao seu cenário, por exemplo, Contas somente neste diretório organizacional (locatário único).

    3. Defina a URI de Redirecionamento como Web e insira https://authorization-manager.consent.azure-apim.net/redirect/apim/<YOUR-APIM-SERVICENAME>, substituindo o nome do serviço de Gerenciamento de API em que você configurará o provedor de credenciais.

    4. Selecione Registrar.

      Captura de tela da criação de um registro de aplicativo do Microsoft Entra no portal.

  5. No menu à esquerda, selecione Permissões de API e selecione + Adicionar uma permissão. Captura de tela da adição de uma permissão de API no portal.

    1. Selecione Microsoft Graph e escolha Permissões delegadas.

      Observação

      Verifique se a permissão User.Read com o tipo Delegado já foi adicionada.

    2. Digite Equipe, expanda as opções Equipe e selecione Team.ReadBasic.All. Selecione Adicionar Permissões.
    3. Em seguida, selecione Conceder consentimento do administrador para o Diretório Padrão. O status das permissões é alterado para Concedido para o Diretório Padrão.

  6. No menu à esquerda, selecione Visão geral. Na página Visão geral, localize o valor de ID do aplicativo (cliente) e registre-o para uso na Etapa 2.

  7. No menu esquerdo, selecione Certificados e segredos e, em seguida, selecione + Novo segredo do cliente.
    Captura de tela da criação de um segredo do aplicativo no portal.

    1. Insira uma Descrição.
    2. Selecione uma opção para Expira.
    3. Selecione Adicionar.
    4. Copie o Valor do segredo do cliente antes de deixar a página. Você precisará dele na Etapa 2.

Etapa 2: Configurar um provedor de credenciais no Gerenciamento de API

  1. Entre no portal e vá para a instância do Gerenciamento de API.

  2. No menu à esquerda, selecione Gerenciador de credenciais e selecione + Criar.
    Captura de tela da criação de uma credencial de API no portal.

  3. Na página Criar provedor de credenciais, insira as seguintes configurações e selecione Criar:

    Configurações Valor
    Nome do provedor de credenciais Um nome de sua escolha, como MicrosoftEntraID-01
    Provedor de identidade Selecione Azure Active Directory v1
    Tipo de concessão Selecionar Código de autorização
    URL de Autorização Opcional para o provedor de identidade do Microsoft Entra ID. O padrão é https://login.microsoftonline.com.
    ID do Cliente Colar o valor copiado anteriormente do registro do aplicativo
    Segredo do cliente Colar o valor copiado anteriormente do registro do aplicativo
    URL de recursos https://graph.microsoft.com
    ID do locatário Opcional para o provedor de identidade do Microsoft Entra ID. O padrão é Comum.
    Escopos Opcional para o provedor de identidade do Microsoft Entra ID. Configurado automaticamente a partir das permissões de API do aplicativo do Microsoft Entra.

Etapa 3: Configurar uma conexão

Na guia Conexão, conclua as etapas para sua conexão com o provedor.

Observação

Quando você configura uma conexão, o Gerenciamento de API, por padrão, configura uma política de acesso que permite o acesso pela identidade gerenciada atribuída pelo sistema da instância. Esse acesso é suficiente para este exemplo. Você pode adicionar políticas de acesso adicionais conforme necessário.

  1. Insira um Nome de conexão e selecione Salvar.
  2. Em Etapa 2: Fazer logon na conexão (para o tipo de concessão de código de autorização), selecione o link para fazer logon no provedor de credenciais. Conclua as etapas para autorizar o acesso e retorne ao Gerenciamento de API.
  3. Em Etapa 3: Determinar quem terá acesso a essa conexão (política de acesso), o membro da identidade gerenciada está listado. Adicionar outros membros é opcional, dependendo do seu cenário.
  4. Selecione Concluir.

A nova conexão aparece na lista de conexões e mostra um status de Conectado. Se você quiser criar outra conexão para o provedor de credenciais, conclua as etapas anteriores.

Dica

Use o portal para adicionar, atualizar ou excluir conexões a um provedor de credenciais a qualquer momento. Para obter mais informações, confira Configurar várias conexões.

Observação

Se você atualizar suas permissões do Microsoft Graph após esta etapa, precisará repetir as Etapas 2 e 3.

Etapa 4: criar uma API do Microsoft Graph no Gerenciamento de API e configurar uma política

  1. Entre no portal e vá para a instância do Gerenciamento de API.

  2. No menu à esquerda, selecione APIs > + Adicionar API.

  3. Selecione HTTP ou insira as configurações a seguir. Em seguida, selecione Criar.

    Configuração Valor
    Nome de exibição msgraph
    URL do serviço da Web https://graph.microsoft.com/v1.0
    Sufixo da URL da API msgraph

  4. Navegue até a API recém-criada e selecione Adicionar Operação. Insira as configurações a seguir e selecione Salvar.

    Configuração Valor
    Nome de exibição getprofile
    URL para GET /me

  5. Siga as etapas anteriores para adicionar outra operação com as configurações a seguir.

    Configuração Valor
    Nome de exibição getJoinedTeams
    URL para GET /me/joinedTeams

  6. Selecione Todas as operações. Na seção Processamento de entrada, selecione o ícone (</>) (editor de código).

  7. Copie e cole o snippet a seguir. Atualize a política get-authorization-context com os nomes do provedor de credenciais e da conexão que você configurou nas etapas anteriores e selecione Salvar.

    • Substitua o nome do provedor de credenciais como o valor de provider-id
    • Substitua o nome da conexão como o valor de authorization-id
    <policies>
    <inbound>
        <base />
        <get-authorization-context provider-id="MicrosoftEntraID-01" authorization-id="first-connection" context-variable-name="auth-context" identity-type="managed" ignore-error="false" />
       <set-header name="Authorization" exists-action="override">
           <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>
       </set-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

A definição de política anterior consiste em duas partes:

  • A política get-authorization-context busca um token de autorização referenciando o provedor de credenciais e a conexão que foram criados anteriormente.
  • A política set-header cria um cabeçalho HTTP com o token de acesso buscado.

Etapa 5: testar a API

  1. Na guia Testar, selecione uma operação que você configurou.

  2. Selecione Enviar.

    Captura de tela do teste da API do Graph no portal.

    Uma resposta bem-sucedida retorna dados do usuário do Microsoft Graph.

Conteúdo relacionado