Compartilhar via


Configurar um provedor de declaração personalizado para um evento de emissão de token

Este artigo descreve como configurar um provedor de declarações personalizadas para um evento de início de emissão de token. Usando uma API REST do Azure Functions existente, você registrará uma extensão de autenticação personalizada e adicionará atributos que você espera que ela analise da API REST. Para testar a extensão de autenticação personalizada, você registrará um aplicativo de amostra do OpenID Connect para obter um token e exibir as declarações.

Pré-requisitos

Etapa 1: registrar uma extensão de autenticação personalizada

Agora você configurará uma extensão de autenticação personalizada, que será usada pelo Microsoft Entra ID para chamar sua função do Azure. A extensão de autenticação personalizada contém informações sobre o ponto de extremidade da API REST, as declarações que ela analisa da API REST e como autenticar na API REST. Siga estas etapas para registrar uma extensão de autenticação personalizada em seu aplicativo de funções do Azure.

Observação

Você pode ter no máximo 100 políticas de extensão personalizadas.

Registrar uma extensão de autenticação personalizada

  1. Entre no portal do Microsoft Azure como, no mínimo, Administrador de Aplicativos e Administrador de Autenticação.
  2. Pesquise e selecione o Microsoft Entra ID e selecione Aplicativos empresariais.
  3. Selecione Extensões de autenticação personalizadas e, em seguida, Criar uma extensão personalizada.
  4. Em Básico, selecione o tipo de evento TokenIssuanceStart e selecione Avançar.
  5. Em Configuração do ponto de extremidade, preencha as seguintes propriedades:
    • Nome – um nome para sua extensão de autenticação personalizada. Por exemplo, Evento de emissão de token.
    • URL de destino – o {Function_Url} da URL da função do Azure. Navegue até a página de visão geral do aplicativo de funções do Azure e selecione a função que você criou. Na página Visão geral da função, selecione Obter a URL da Função e use o ícone de cópia para copiar a URL customauthenticationextension_extension (Chave do sistema).
    • Descrição – uma descrição para suas extensões de autenticação personalizadas.
  6. Selecione Avançar.
  7. Em Autenticação de API, selecione a opção Criar registro de aplicativo para criar um registro de aplicativo que represente seu aplicativo de funções.
  8. Dê um nome ao aplicativo, por exemplo, API de eventos de autenticação do Azure Functions.
  9. Selecione Avançar.
  10. Em Declarações, insira os atributos que você espera que sua extensão de autenticação personalizada analise da API REST e que serão mesclados no token. Adicione os códigos a seguir:
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
  11. Selecione Avançar e, em seguida, Criar, que registra a extensão de autenticação personalizada e o registro do aplicativo associado.
  12. Observe a ID do aplicativo em Autenticação da API, que é necessária para configurar a autenticação nas suas Funções do Azure no seu aplicativo de Funções do Azure.

Depois que a extensão de autenticação personalizada for criada, você precisará conceder permissões à API. A extensão de autenticação personalizada usa client_credentials para autenticar no Aplicativo de Funções do Azure usando a permissão Receive custom authentication extension HTTP requests.

  1. Abra a página Visão Geral da sua nova extensão de autenticação personalizada. Anote a ID do Aplicativo em Autenticação da API, pois ele será necessário ao adicionar um provedor de identidade.

  2. Em Autenticação da API, selecione Conceder permissão.

  3. Uma nova janela será aberta e, uma vez conectada, ela solicitará permissões para receber solicitações HTTP de extensão de autenticação personalizada. Isso permite que a extensão de autenticação personalizada se autentique na sua API. Selecione Aceitar.

    Captura de tela que mostra como fornecer o consentimento do administrador.

Etapa 2: Configurar um aplicativo do OpenID Connect para receber tokens enriquecidos

Para obter um token e testar a extensão de autenticação personalizada, você pode usar o aplicativo https://jwt.ms. É um aplicativo da Web de propriedade da Microsoft que exibe o conteúdo decodificado de um token (o conteúdo do token nunca sai do seu navegador).

2.1 Registrar um aplicativo Web de teste

Siga estas etapas para registrar o aplicativo Web jwt.ms :

  1. Na página inicial no portal do Azure, selecione Microsoft Entra ID.

  2. Selecione Registros de aplicativo>Novo registro.

  3. Insira um Nome para o aplicativo. Por exemplo, Meu aplicativo de teste.

  4. Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional.

  5. Na lista suspensa Selecionar uma plataforma no URI de redirecionamento, selecione Web e, em seguida, insira https://jwt.ms na caixa de texto URL.

  6. Selecione Registrar para concluir o registro do aplicativo.

    Captura de tela que mostra como selecionar o tipo de conta com suporte e o URI de redirecionamento.

  7. Na página Visão geral do registro do seu aplicativo, copie o ID do aplicativo (cliente). A ID do aplicativo é referenciada como o {App_to_enrich_ID} nas etapas posteriores. No Microsoft Graph, ela é referenciada pela propriedade appId.

    Captura de tela que mostra como copiar a ID do aplicativo.

2.2 Habilitar fluxo implícito

O aplicativo de teste jwt.ms usa o fluxo implícito. Habilite o fluxo implícito no registro do Meu aplicativo de teste:

  1. Em Gerenciar, selecione Autenticação.
  2. Na seção Concessão implícita e fluxos híbridos, selecione a caixa de seleção Tokens de ID (usados para fluxos implícitos e híbridos).
  3. Selecione Salvar.

2.3 Habilitar o seu aplicativo para uma política de mapeamento de declarações

Uma política de mapeamento de declarações é usada para selecionar quais atributos retornados da extensão de autenticação personalizada são mapeados para o token. Para permitir que os tokens sejam aprimorados, você deve habilitar explicitamente o registro do aplicativo para aceitar declarações mapeadas:

  1. No registro do Meu aplicativo de teste, em Gerenciar, selecione Manifesto.
  2. No manifesto, localize o atributo acceptMappedClaims e defina o valor como true.
  3. Defina o requestedAccessTokenVersion para 2.
  4. Selecione Salvar para salvar as alterações.

O snippet JSON a seguir demonstra como configurar essas propriedades.

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"requestedAccessTokenVersion": 2,  
    ...
}

Aviso

Não defina a propriedade acceptMappedClaims como true para aplicativos multilocatário, pois isso poderá permitir que atores mal-intencionados criem políticas de mapeamento de declarações para seu aplicativo. Em vez disso, configure uma chave de assinatura personalizada.

Continue na próxima etapa, Atribuir um provedor de declarações personalizado ao seu aplicativo.

Etapa 3: Atribuir um provedor de declarações personalizado ao seu aplicativo

Para que os tokens sejam emitidos com declarações recebidas da extensão de autenticação personalizada, você deve atribuir um provedor de declarações personalizadas ao seu aplicativo. Isso é feito com base no público-alvo do token, de modo que o provedor deve ser atribuído ao aplicativo cliente para receber declarações em um token de ID e ao aplicativo de recursos para receber declarações em um token de acesso. O provedor de declarações personalizadas depende da extensão de autenticação personalizada configurada com o ouvinte de evento Início de emissão de token. Você pode escolher se todas, ou um subconjunto das declarações do provedor de declarações personalizadas, serão mapeadas para o token.

Observação

Você só pode criar 250 atribuições exclusivas entre aplicativos e extensões personalizadas. Se você quiser aplicar a mesma chamada de extensão personalizada a vários aplicativos, recomendamos usar authenticationEventListeners API do Microsoft Graph para criar ouvintes para vários aplicativos. Sem suporte no portal do Azure.

Siga estas etapas para conectar o Meu aplicativo de teste à sua extensão de autenticação personalizada:

Para atribuir a extensão de autenticação personalizada como uma fonte de provedores de declarações personalizadas;

  1. Na página inicial no portal do Azure, selecione Microsoft Entra ID.

  2. Selecione aplicativos empresariais e, em seguida, em Gerenciar, selecione Todos os aplicativos. Localize e selecione Meu aplicativo de teste na lista.

  3. Na página Visão geral do Meu aplicativo de Teste, navegue até Gerenciar e selecione Logon único.

  4. Em Atributos e Declarações, selecione Editar.

    Captura de tela que mostra como configurar declarações de aplicativos.

  5. Expanda o menu Configurações avançadas.

  6. Ao lado de Provedor de declarações personalizado, selecione Configurar.

  7. Expanda a caixa suspensa Provedor de declarações personalizadas e selecione o evento de emissão de token criado anteriormente.

  8. Selecione Salvar.

Em seguida, aloque os atributos do provedor de declarações personalizadas, que devem ser emitidos no token como declarações:

  1. Selecione Adicionar nova declaração para adicionar uma nova declaração. Forneça um nome para a declaração que você deseja que seja emitida, por exemplo, dateOfBirth.

  2. Em Origem, selecione Atributo e escolha customClaimsProvider.dateOfBirth na caixa suspensa Atributo de Origem.

    Captura de tela que mostra como adicionar um mapeamento de declarações ao seu aplicativo.

  3. Selecione Salvar.

  4. Repita esse processo para adicionar os atributos customClaimsProvider.customRoles, customClaimsProvider.apiVersion e customClaimsProvider.correlationId e o nome correspondente. É uma boa ideia fazer a correspondência entre o nome da declaração e o nome do atributo.

Etapa 4: proteger sua função do Azure

A extensão de autenticação personalizada do Microsoft Entra utiliza o fluxo de servidor para o servidor para obter um token de acesso que é enviado no cabeçalho HTTP Authorization para sua função do Azure. Ao publicar sua função no Azure, especialmente em um ambiente de produção, você precisa validar o token enviado no cabeçalho de autorização.

Para proteger sua função do Azure, siga estas etapas para integrar a autenticação do Microsoft Entra, para validar tokens de entrada com o registro de aplicativos API de eventos de autenticação do Azure Functions. Escolha uma das guias a seguir com base no seu tipo de locatário.

Observação

Se o aplicativo de funções do Azure estiver hospedado em um locatário do Azure diferente do locatário no qual sua extensão de autenticação personalizada está registrada, escolha a guia Open ID Connect.

4.1 Usar o provedor de identidade do Microsoft Entra

Use as etapas a seguir para adicionar o Microsoft Entra como um provedor de identidade ao seu aplicativo Azure Function.

  1. No portal do Azure, localize e selecione o aplicativo de funções publicado anteriormente.

  2. Em Configurações, selecione Autenticação.

  3. Selecione Adicionar provedor de identidade.

  4. Selecione Microsoft como provedor de identidade.

  5. Selecione Força de trabalho como o tipo de locatário.

  6. Em Registro de aplicativo, selecione Escolher um registro de aplicativo existente neste diretório para o Tipo de registro de aplicativo e escolha o registro de aplicativo API de eventos de autenticação do Azure Functions que você criou anteriormente ao registrar o provedor de declarações personalizado.

  7. Insira a seguinte URL do emissor, https://login.microsoftonline.com/{tenantId}/v2.0, em que {tenantId} é a ID do locatário da sua força de trabalho.

  8. Em Requisito de aplicativo cliente, selecione Permitir solicitações de aplicativos cliente específicos e insira 99045fe1-7639-4a75-9d4a-577b6ca3810f.

  9. Em Requisito de locatário, selecione Permitir solicitações de locatários específicos e insira a ID do locatário da força de trabalho.

  10. Em Solicitações não autenticadas, selecione HTTP 401 Não autorizado como provedor de identidade.

  11. Desmarque a opção Repositório de tokens.

  12. Selecione Adicionar para adicionar autenticação à função do Azure.

    Captura de tela que mostra como adicionar autenticação ao aplicativo de funções enquanto estiver em um locatário da força de trabalho.

4.2 Usando o provedor de identidade do OpenID Connect

Se você tiver configurado o provedor de identidade da Microsoft, ignore esta etapa. Caso contrário, se a função do Azure estiver hospedada em um locatário diferente do locatário no qual sua extensão de autenticação personalizada está registrada, siga estas etapas para proteger sua função:

Criar um segredo do cliente

  1. Na página inicial do portal do Azure, selecione Microsoft Entra ID>Registros de aplicativo.
  2. Selecione o registro de aplicativo API de eventos de autenticação Azure Functionsque você criou anteriormente.
  3. Selecione Certificados e segredos>Segredos do cliente>Novo segredo do cliente.
  4. Selecione uma expiração para o segredo ou especifique um tempo de vida personalizado, adicione uma descrição e selecione Adicionar.
  5. Registre o valor do segredo para uso no código do aplicativo cliente. Esse valor secreto nunca será exibido novamente depois que você sair dessa página.

Adicione o provedor de identidade do OpenID Connect ao seu aplicativo de funções do Azure.

  1. Localize e selecione o aplicativo de funções que você publicou anteriormente.

  2. Em Configurações, selecione Autenticação.

  3. Selecione Adicionar provedor de identidade.

  4. Selecione OpenID Connect como provedor de identidade.

  5. Forneça um nome, como Microsoft Entra ID da Contoso.

  6. Na Entrada de metadados, insira a URL a seguir para a URL do Documento. Substitua o {tenantId} por seu locatário do Microsoft Entra ID.

    https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
    
  7. Em Registro de aplicativo, insira a ID do aplicativo (ID do cliente) do registro do aplicativo da API de eventos de autenticação do Azure Functions que você criou anteriormente.

  8. Retorne à Função do Azure e, em Registro do aplicativo, insira Segredo do cliente.

  9. Desmarque a opção Repositório de tokens.

  10. Selecione Adicionar para adicionar o provedor de identidade do OpenID Connect.

Etapa 5: Testar o aplicativo

Para testar seu provedor de declarações personalizado, siga estas etapas:

  1. Abra um novo navegador privado e entre pela URL a seguir.

    https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
    
  2. Substitua {tenantId} pela ID do locatário, pelo nome do locatário ou por um dos nomes de domínio verificados. Por exemplo, contoso.onmicrosoft.com.

  3. Substitua {App_to_enrich_ID} pela ID do cliente Meu aplicativo de teste.

  4. Depois de fazer logon, você receberá o token decodificado em https://jwt.ms. Valide se as declarações da função do Azure são apresentadas no token decodificado, por exemplo, dateOfBirth.

Confira também