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

Este artigo descreve como configurar um provedor de declarações personalizado 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 espera que ela analise a partir da sua API REST. Para testar a extensão de autenticação personalizada, você registrará um aplicativo OpenID Connect de exemplo para obter um token e visualizar as declarações.

Pré-requisitos

• Uma assinatura do Azure com a capacidade de criar o Azure Functions. Se você não tiver uma conta existente do Azure, inscreva-se para uma avaliação gratuita ou use os benefícios da Assinatura do Visual Studio ao criar uma conta.
• Um aplicativo do Azure Function com uma função de gatilho HTTP configurada para um evento de início de emissão de token. Se você não tiver uma, siga as etapas em criar uma função de gatilho HTTP de evento de início de emissão de token.
• Uma compreensão básica dos conceitos abordados em Visão geral das extensões de autenticação personalizadas.
• Um locatário do Microsoft Entra ID. Você pode usar um cliente ou locatário da força de trabalho para este guia de instruções.
  • Para locatários externos, use um fluxo de usuário de inscrição e entrada.

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 seu ponto de extremidade da API REST, as declarações que ele 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 Azure Function.

Nota

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

Portal do Azure

Registrar uma extensão de autenticação personalizada

1. Entre no portal do Azure como pelo menos um Administrador de Aplicativo e Administrador de Autenticação.
2. Procure e selecione Microsoft Entra ID e selecione Aplicações empresariais.
3. Selecione Extensões de autenticação personalizadas e, em seguida, selecione Criar uma extensão personalizada.
4. Em Noções básicas, selecione o tipo de evento TokenIssuanceStart e selecione Avançar.
5. Em Configuração do ponto final, 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 - A {Function_Url} URL da sua função do Azure. Navegue até a página Visão geral do seu aplicativo Azure Function e selecione a função que você criou. Na página Visão geral da função, selecione Obter URL da função e use o ícone de cópia para copiar a URL.
   • Descrição - Uma descrição para suas extensões de autenticação personalizadas.
6. Selecione Seguinte.
7. Em Autenticação de API, selecione a opção Criar novo registro deaplicativo para criar um registro de aplicativo que represente seu aplicativo de função.
8. Dê um nome ao aplicativo, por exemplo , API de eventos de autenticação do Azure Functions.
9. Selecione Seguinte.
10. Em Declarações, insira os atributos que você espera que sua extensão de autenticação personalizada analise da sua API REST e serão mesclados no token. Adicione as seguintes declarações:
    • datadenascimento
    • 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 de API, que é necessária para definir variáveis de ambiente em seu aplicativo Azure Function.

Microsoft Graph

Registar uma aplicação

1. Entre no Graph Explorer usando uma conta cujo locatário doméstico é o locatário no qual você deseja gerenciar sua extensão de autenticação personalizada. Essa conta deve ter privilégios para criar e gerenciar um registro de aplicativo no locatário.

2. Execute a seguinte solicitação.

   POST https://graph.microsoft.com/v1.0/applications
   Content-type: application/json
   
   {
       "displayName": "authenticationeventsAPI"
   }
   

3. A partir da resposta, registre o valor de id e appId do registro do aplicativo recém-criado. Esses valores são referenciados neste artigo como {authenticationeventsAPI_ObjectId} e {authenticationeventsAPI_AppId} respectivamente.

Crie uma entidade de serviço no locatário para o registro do aplicativo authenticationeventsAPI.

Enquanto estiver no Graph Explorer, execute a seguinte solicitação. Substitua {authenticationeventsAPI_AppId} pelo valor de appId que você registrou na etapa anterior.

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json
    
{
    "appId": "{authenticationeventsAPI_AppId}"
}

Definir o URI da ID do aplicativo, a versão do token de acesso e o acesso necessário aos recursos

Atualize o aplicativo recém-criado para definir o valor de URI da ID do aplicativo, a versão do token de acesso e o acesso ao recurso necessário.

No Graph Explorer, execute a seguinte solicitação.

• Defina o valor de URI do ID do aplicativo na propriedade identifierUris . Substitua {Function_Url_Hostname} pelo nome do host do {Function_Url} que você gravou anteriormente.
• Defina o {authenticationeventsAPI_AppId} valor com o appId que você registrou anteriormente.
• Um exemplo de valor é api://authenticationeventsAPI.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444. Anote esse valor, pois você o usará mais adiante neste artigo no lugar de {functionApp_IdentifierUri}.

POST https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}
Content-type: application/json

{
"identifierUris": [
    "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
],    
"api": {
    "requestedAccessTokenVersion": 2,
    "acceptMappedClaims": null,
    "knownClientApplications": [],
    "oauth2PermissionScopes": [],
    "preAuthorizedApplications": []
},
"requiredResourceAccess": [
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                "type": "Role"
            }
        ]
    }
]
}

Registrar uma extensão de autenticação personalizada

Para registrar a extensão de autenticação personalizada, associe-a ao registro do aplicativo para a Função do Azure e ao ponto de extremidade {Function_Url}da Função do Azure.

1. No Graph Explorer, execute a seguinte solicitação. Substitua {Function_Url} pelo nome do host do seu aplicativo Azure Function. Substitua {functionApp_IdentifierUri} pelo identifierUri usado na etapa anterior.

   • Você precisa da permissão delegada CustomAuthenticationExtension.ReadWrite.All .

   POST https://graph.microsoft.com/beta/identity/customAuthenticationExtensions
   Content-type: application/json
   
   {
       "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtension",
       "displayName": "onTokenIssuanceStartCustomExtension",
       "description": "Fetch additional claims from custom user store",
       "endpointConfiguration": {
           "@odata.type": "#microsoft.graph.httpRequestEndpoint",
           "targetUrl": "{Function_Url}"
       },
       "authenticationConfiguration": {
           "@odata.type": "#microsoft.graph.azureAdTokenAuthentication",
           "resourceId": "{functionApp_IdentifierUri}"
       },
       "claimsForTokenConfiguration": [
           {
               "claimIdInApiResponse": "DateOfBirth"
           },
           {
               "claimIdInApiResponse": "CustomRoles"
           }
       ]
   }
   

2. Registre o id valor do objeto do provedor de declarações personalizado criado. Você usará o valor posteriormente neste tutorial no lugar de {customExtensionObjectId}.

1.2 Conceder consentimento de administrador

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ção do Azure usando a Receive custom authentication extension HTTP requests permissão.

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

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

3. Uma nova janela é aberta e, uma vez conectado, ele solicita 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 em sua API. Selecione Aceitar.

   

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

Para obter um token e testar a extensão de autenticação personalizada, você pode usar o https://jwt.ms aplicativo. É um aplicativo 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 Registar uma aplicação Web de teste

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

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

2. Selecione Registos de>aplicações Novo registo.

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

4. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional.

5. Na lista suspensa Selecione uma plataforma no URI de redirecionamento, selecione Web e digite https://jwt.ms a caixa de texto URL.

6. Selecione Registrar para concluir o registro do aplicativo.

   

7. Na página Visão geral do registro do aplicativo, copie a ID do aplicativo (cliente). O ID do aplicativo é chamado de {App_to_enrich_ID} nas etapas posteriores. No Microsoft Graph, ele é referenciado pela propriedade appId .

   

2.2 Ativar fluxo implícito

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

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

2.3 Habilitar 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 no token. Para permitir que os tokens sejam aumentados, você deve habilitar explicitamente o registro do aplicativo para aceitar declarações mapeadas:

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

O trecho JSON a seguir demonstra como configurar essas propriedades.

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

Aviso

Não defina acceptMappedClaims a propriedade como true para aplicativos multilocatário, o que pode 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.

Inquilino da força de trabalho

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

Inquilino externo

3.4 Associar seu aplicativo a um fluxo de usuário

Para locatários externos, você precisa associar seu aplicativo a um fluxo de usuário. Um fluxo de usuário define os métodos de autenticação que um cliente pode usar para entrar em seu aplicativo e as informações que ele precisa fornecer durante a inscrição. Certifique-se de concluir as etapas em Adicionar um aplicativo a um fluxo de usuário antes de continuar a adicionar Meu aplicativo de teste ao fluxo de usuário.

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 personalizado ao seu aplicativo. Isso se baseia no público do token, portanto, o provedor deve ser atribuído ao aplicativo cliente para receber declarações em um token de ID e ao aplicativo de recurso 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 eventos de início de emissão de token. Você pode escolher se todas, ou um subconjunto de declarações, do provedor de declarações personalizadas são mapeadas no token.

Nota

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

Siga estas etapas para conectar o aplicativo My Test com sua extensão de autenticação personalizada:

Portal do Azure

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

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

2. SelecioneAplicativos corporativos e, em Gerenciar, selecione Todos os aplicativos. Localize e selecione Meu aplicativo de teste na lista.

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

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

   

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 personalizado e selecione o evento de emissão de token criado anteriormente.

8. Selecione Guardar.

Em seguida, atribua 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 emitir, por exemplo , dateOfBirth.

2. Em Source, selecione Attribute e escolha customClaimsProvider.dateOfBirth na caixa suspensa Source attribute .

   

3. Selecione Guardar.

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

Microsoft Graph

Primeiro, crie um ouvinte de eventos para disparar uma extensão de autenticação personalizada para o aplicativo My Test usando o evento de início de emissão de token.

1. Entre no Graph Explorer usando uma conta cujo locatário residencial é o locatário no qual você deseja gerenciar sua extensão de autenticação personalizada.

2. Execute a seguinte solicitação. Substitua {App_to_enrich_ID} pelo ID do aplicativo My Test gravado anteriormente. Substitua {customExtensionObjectId} pelo ID da extensão de autenticação personalizada registrada anteriormente.

   • Você precisa da permissão delegada EventListener.ReadWrite.All .

   POST https://graph.microsoft.com/beta/identity/authenticationEventListeners
   Content-type: application/json
   
   {
       "@odata.type": "#microsoft.graph.onTokenIssuanceStartListener",
       "conditions": {
           "applications": {
               "includeAllApplications": false,
               "includeApplications": [
                   {
                       "appId": "{App_to_enrich_ID}"
                   }
               ]
           }
       },
       "priority": 500,
       "handler": {
           "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtensionHandler",
           "customExtension": {
               "id": "{customExtensionObjectId}"
           }
       }
   }
   

Em seguida, crie a política de mapeamento de declarações, que descreve quais declarações podem ser emitidas para um aplicativo de um provedor de declarações personalizado.

1. Ainda no Graph Explorer, execute a seguinte solicitação. Você precisará da permissão delegada Policy.ReadWrite.ApplicationConfiguration .

   POST https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies
   Content-type: application/json
   
   {
       "definition": [
           "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"CustomClaimsProvider\",\"ID\":\"DateOfBirth\",\"JwtClaimType\":\"dob\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CustomRoles\",\"JwtClaimType\":\"my_roles\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CorrelationId\",\"JwtClaimType\":\"correlationId\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"ApiVersion\",\"JwtClaimType\":\"apiVersion \"},{\"Value\":\"tokenaug_V2\",\"JwtClaimType\":\"policy_version\"}]}}"
       ],
       "displayName": "MyClaimsMappingPolicy",
       "isOrganizationDefault": false
   }
   

2. Registre o ID gerado na resposta, mais tarde é referido como {claims_mapping_policy_ID}.

Obtenha o ID do objeto principal do serviço:

1. Execute a seguinte solicitação no Graph Explorer. Substitua {App_to_enrich_ID} pelo appId de Meu aplicativo de teste.

   GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='{App_to_enrich_ID}')
   

Registre o valor de id.

Atribua a política de mapeamento de declarações à entidade de serviço de Meu Aplicativo de Teste.

1. Execute a seguinte solicitação no Graph Explorer. Você precisará da permissão delegada Policy.ReadWrite.ApplicationConfiguration e Application.ReadWrite.All .

   POST https://graph.microsoft.com/v1.0/servicePrincipals/{test_App_Service_Principal_ObjectId}/claimsMappingPolicies/$ref
   Content-type: application/json
   
   {
       "@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/{claims_mapping_policy_ID}"
   }
   

Etapa 4: Proteger sua função do Azure

A extensão de autenticação personalizada do Microsoft Entra usa o fluxo de servidor para 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 seu registro de aplicativo de API de eventos de autenticação do Azure Functions. Escolha uma das seguintes guias com base no seu tipo de locatário.

Nota

Se o aplicativo de função 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 Usando o provedor de identidade Microsoft Entra

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

Inquilino da força de trabalho

1. No portal do Azure, localize e selecione o aplicativo de função que você publicou anteriormente.

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

3. Selecione Adicionar provedor de identidade.

4. Selecione Microsoft como o 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 de API de eventos de autenticação do Azure Functions que você criou anteriormente ao registrar o provedor de declarações personalizado.

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

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

9. Desmarque a opção Loja de tokens.

10. Selecione Adicionar para adicionar autenticação à sua Função do Azure.

    

Inquilino externo

1. No portal do Azure, localize e selecione o aplicativo de função que você publicou anteriormente.

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

3. Selecione Adicionar provedor de identidade.

4. Selecione Microsoft como o provedor de identidade.

5. Selecione Cliente como o tipo de locatário.

6. Em Registro de aplicativo, insira o client_id registro do aplicativo de API de eventos de autenticação do Azure Functions que você criou anteriormente ao registrar o provedor de declarações personalizado.

7. Para o URL do emissor, insira o seguinte URL https://{domainName}.ciamlogin.com/{tenant_id}/v2.0, onde

   • {domainName} é o nome de domínio do seu locatário externo, no formato {domainName}.contoso.com.
   • {tenantId} é o ID do inquilino do seu inquilino externo.

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

9. Desmarque a opção Loja de tokens.

10. Selecione Adicionar para adicionar autenticação à sua Função do Azure.

    

4.2 Usando o provedor de identidade OpenID Connect

Se você configurou 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 Registros do aplicativo Microsoft Entra ID>.
2. Selecione o registro do aplicativo de API de eventos de autenticação do Azure Functions que você criou anteriormente.
3. Selecione Certificados & 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. Este valor secreto nunca mais é apresentado depois de sair desta página.

Adicione o provedor de identidade OpenID Connect ao seu aplicativo Azure Function.

1. Encontre e selecione o aplicativo de função que você publicou anteriormente.

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

3. Selecione Adicionar provedor de identidade.

4. Selecione OpenID Connect como o provedor de identidade.

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

6. Na entrada Metadados, insira a seguinte URL para a URL do documento. Substitua o pelo seu ID de locatário do {tenantId} Microsoft Entra.

   https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
   

7. No Registro do aplicativo, insira a ID do aplicativo (ID do cliente) dos eventos de autenticação do Azure Functions Registro do aplicativo da API que você criou anteriormente.

8. Retorne à Função do Azure, sob o registro do aplicativo, insira o segredo do cliente.

9. Desmarque a opção Loja de tokens.

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

Etapa 5: Testar o aplicativo

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

Inquilino da força de trabalho

1. Abra um novo navegador privado e navegue e inicie sessão através do seguinte URL.

   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} pelo seu ID de inquilino, nome de inquilino ou um dos seus nomes de domínio verificados. Por exemplo, contoso.onmicrosoft.com.

3. Substitua {App_to_enrich_ID} pelo ID do cliente do aplicativo My Test.

4. Depois de iniciar sessão, ser-lhe-á apresentado o seu token descodificado em https://jwt.ms. Valide se as declarações da Função do Azure são apresentadas no token decodificado, por exemplo, dateOfBirth.

Inquilino externo

1. Abra um novo navegador privado e navegue e inicie sessão através do seguinte URL.

   https://{domainName}.ciamlogin.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 {domainName} pelo seu nome de domínio, por exemplo, contoso.

3. Substitua {tenantId} pelo seu ID de inquilino, nome de inquilino ou um dos seus nomes de domínio verificados. Por exemplo, contoso.onmicrosoft.com.

4. Substitua {App_to_enrich_ID} pelo ID do cliente do aplicativo My Test.

5. Percorra o fluxo de usuário de entrada que você configurou e aceite as permissões solicitadas.

6. Depois de iniciar sessão, ser-lhe-á apresentado o seu token descodificado em https://jwt.ms. Valide se as declarações da Função do Azure são apresentadas no token decodificado, por exemplo, dateOfBirth.

Consulte também

• Configurar um aplicativo SAML para receber tokens com declarações de um repositório externo
• Referência do provedor de declarações personalizadas
• Solucionar problemas da API de extensões de autenticação personalizadas