Proteger uma API de Gerenciamento de API do Azure com Azure AD B2C

Saiba como restringir o acesso à sua API do Gerenciamento de API do Azure para clientes que se autenticaram com o Azure AD B2C (Azure Active Directory B2C). Siga as instruções neste artigo para criar e testar uma política de entrada no Gerenciamento de API do Azure que restringe o acesso apenas às solicitações que incluem um token de acesso válido emitido pelo Azure AD B2C.

Pré-requisitos

Antes de começar, confirme se tem os seguintes recursos implantados:

Obter a ID do aplicativo Azure AD B2C

Ao proteger uma API no Gerenciamento de API do Azure com Azure AD B2C, você precisa de vários valores para a política de entrada que você cria no Gerenciamento de API do Azure. Primeiro, registre a ID de um aplicativo que você criou anteriormente em seu locatário do Azure AD B2C. Se você estiver usando o aplicativo criado para atender aos pré-requisitos, use a ID do aplicativo para webapp1.

Para registrar um aplicativo no locatário do Azure AD B2C, você pode usar a nossa nova experiência unificada de Registros de aplicativo ou a nossa experiência herdada Aplicativos. Saiba mais sobre a nova experiência de registros.

  1. Entre no portal do Azure.
  2. Verifique se você está usando o diretório que contém seu locatário do Azure AD B2C. Selecione o ícone Diretórios + assinaturas na barra de ferramentas do portal.
  3. Na página Configurações do portal | Diretórios + assinaturas, encontre o diretório Azure Active Directory B2C na lista Nome do diretório e, em seguida, selecione Alternar.
  4. No painel à esquerda, selecione Azure AD B2C. Como alternativa, você pode selecionar Todos os serviços e, em seguida, pesquisar e selecionar Azure AD B2C.
  5. Selecione Registros de aplicativo e a guia Aplicativos próprios.
  6. Registre o valor na coluna ID do aplicativo (cliente) para webapp1 ou outro aplicativo que você criou anteriormente.

Obter um ponto de extremidade do emissor do token

Em seguida, obtenha a URL de configuração conhecida para um dos seus fluxos de usuário do Azure AD B2C. Você também precisa do URI de ponto de extremidade do emissor do token para o qual você deseja dar suporte no Gerenciamento de API do Azure.

  1. No portal do Azure, vá até o locatário do Azure AD B2C.

  2. Em Políticas, selecione Fluxos dos usuários.

  3. Selecione uma política existente (por exemplo, B2C_1_signupsignin1) e, em seguida, selecione Executar fluxo de usuário.

  4. Registre a URL no hiperlink exibido no título Executar fluxo de usuário próximo à parte superior da página. Essa URL é o ponto de extremidade de descoberta conhecido do OpenID Connect para o fluxo do usuário, e você o usará na próxima seção ao configurar a política de entrada no Gerenciamento de API do Azure.

    Captura de tela do hiperlink de URI conhecido na página “Executar fluxo de usuário” do portal do Azure.

  5. Selecione o hiperlink para ir até a página de configuração conhecida do OpenID Connect.

  6. Na página que é aberta no navegador, registre o valor issuer. Por exemplo:

    https://<tenant-name>.b2clogin.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0/

    Você usará esse valor na próxima seção quando configurar sua API no Gerenciamento de API do Azure.

Agora você deve ter duas URLs registradas para uso na próxima seção: a URL do ponto de extremidade de configuração conhecida do OpenID Connect e o URI do emissor. Por exemplo:

https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/B2C_1_signupsignin1/v2.0/.well-known/openid-configuration
https://<tenant-name>.b2clogin.com/99999999-0000-0000-0000-999999999999/v2.0/

Configurar a política de entrada no Gerenciamento de API do Azure

Agora você está pronto para adicionar a política de entrada no Gerenciamento de API do Azure que valida chamadas de API. Ao adicionar uma política de validação JWT (token Web JSON) que verifica o público e o emissor em um token de acesso, você poderá garantir que somente chamadas de API com um token válido sejam aceitas.

  1. No portal do Azure, vá para sua instância de Gerenciamento de API do Azure.

  2. Selecione APIs.

  3. Selecione a API que você deseja proteger com o Azure AD B2C.

  4. Selecione a guia Design.

  5. Em Processamento de entrada, selecione </> para abrir o editor de código de política.

  6. Coloque a marca <validate-jwt> a seguir dentro da política de <inbound> e faça o seguinte:

    a. Atualize o valor url no elemento <openid-config> com a URL de configuração conhecida de sua política.
    b. Atualize o elemento <audience> com a ID do aplicativo que você criou anteriormente em seu locatário B2C (por exemplo, webapp1).
    c. Atualize o elemento <issuer> com o ponto de extremidade do emissor do token que você registrou anteriormente.

    <policies>
        <inbound>
            <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
                <openid-config url="https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/B2C_1_signupsignin1/v2.0/.well-known/openid-configuration" />
                <audiences>
                    <audience>44444444-0000-0000-0000-444444444444</audience>
                </audiences>
                <issuers>
                    <issuer>https://<tenant-name>.b2clogin.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
                </issuers>
            </validate-jwt>
            <base />
        </inbound>
        <backend> <base /> </backend>
        <outbound> <base /> </outbound>
        <on-error> <base /> </on-error>
    </policies>
    

Validar o acesso à API segura

Para garantir que somente chamadores autenticados possam acessar sua API, valide a configuração do Gerenciamento de API do Azure chamando a API com Postman.

Para chamar a API, você precisa de um token de acesso emitido pelo Azure AD B2C e uma chave de assinatura do Gerenciamento de API.

Obter um token de acesso

Primeiro, você precisa de um token que foi emitido pelo Azure AD B2C para usar no cabeçalho Authorization no Postman. Você pode obter um usando o recurso Executar agora do fluxo de usuários de inscrição/entrada que criou como um dos pré-requisitos.

  1. No portal do Azure, vá até o locatário do Azure AD B2C.

  2. Em Políticas, selecione Fluxos dos usuários.

  3. Selecione um fluxo de usuários de inscrição/entrada existente, (por exemplo, B2C_1_signupsignin1).

  4. Para Aplicativo, selecione webapp1.

  5. Para URL de resposta, selecione https://jwt.ms.

  6. Selecione Executar fluxo de usuário.

    Captura de tela do painel “Executar fluxo de usuário” para o fluxo de usuário de assinatura/login no portal do Azure.

  7. Conclua o processo de conexão. Você deve ser redirecionado para https://jwt.ms.

  8. Registre o valor de token codificado exibido no navegador. Você usa esse valor de token para o cabeçalho de autorização no Postman.

    Captura de tela do valor do token codificado exibido no jwt.ms.

Obter uma chave de assinatura de API

Um aplicativo cliente (neste caso, o Postman) que chama uma API publicada deve incluir uma chave de assinatura de Gerenciamento de API válida em suas solicitações HTTP para a API. Para obter uma chave de assinatura a fim de incluir em sua solicitação HTTP do Postman:

  1. No portal do Azure, vá até a sua instância de serviço do Gerenciamento de API do Azure.
  2. Selecione Assinaturas.
  3. Selecione elipses ( ... ) ao lado de Produto: ilimitado e, em seguida, selecione Mostrar/ocultar chaves.
  4. Registre a Chave primária para o produto. Use essa chave para o cabeçalho de Ocp-Apim-Subscription-Key em sua solicitação HTTP no Postman.

Captura de tela da página “Chave de assinatura” no portal do Azure, com a opção “Mostrar/ocultar chaves” selecionada.

Testar uma chamada à API segura

Com o token de acesso e a chave de assinatura do Gerenciamento de API registrada, agora você está pronto para testar se configurou corretamente o acesso seguro à API.

  1. Crie uma solicitação GET no Postman. Para a URL de solicitação, especifique o ponto de extremidade da lista de palestrantes da API que você publicou como um dos pré-requisitos. Por exemplo:

    https://contosoapim.azure-api.net/conference/speakers

  2. Em seguida, adicione os seguintes cabeçalhos:

    Chave Valor
    Authorization O valor de token codificado que você registrou anteriormente, prefixado com Bearer (inclua o espaço após “portador”)
    Ocp-Apim-Subscription-Key A chave de assinatura do Gerenciamento de API do Azure que você registrou anteriormente.

    O seu URL de solicitação GET e os Cabeçalhos devem ser semelhantes aos mostrados na imagem a seguir:

    Captura de tela da interface do usuário do Postman mostrando a URL de solicitação GET e os cabeçalhos.

  3. No Postman, selecione o botão Enviar para executar a solicitação. Se você tiver configurado tudo corretamente, deverá receber uma resposta JSON com uma coleção de palestrantes (mostrados aqui truncados):

    {
      "collection": {
        "version": "1.0",
        "href": "https://conferenceapi.azurewebsites.net:443/speakers",
        "links": [],
        "items": [
          {
            "href": "https://conferenceapi.azurewebsites.net/speaker/1",
            "data": [
              {
                "name": "Name",
                "value": "Scott Guthrie"
              }
            ],
            "links": [
              {
                "rel": "http://tavis.net/rels/sessions",
                "href": "https://conferenceapi.azurewebsites.net/speaker/1/sessions"
              }
            ]
          },
    [...]
    

Testar uma chamada à API não segura

Agora que você fez uma solicitação bem-sucedida, teste o caso de falha para garantir que as chamadas para sua API com um token inválido sejam rejeitadas conforme o esperado. Uma maneira de executar o teste é adicionar ou alterar alguns caracteres no valor do token e, em seguida, executar a mesma solicitação GET de antes.

  1. Adicione vários caracteres ao valor do token para simular um token inválido. Por exemplo, você pode adicionar “INVALID” ao valor do token, conforme mostrado aqui:

    Captura de tela da seção Cabeçalhos da interface do usuário do Postman mostrando a cadeia de caracteres INVALID adicionada ao token.

  2. Selecione o botão Enviar para executar a solicitação. Com um token inválido, o resultado esperado é um código de status não-autorizado 401:

    {
        "statusCode": 401,
        "message": "Unauthorized. Access token is missing or invalid."
    }
    

Caso você veja o código de status 401, verificou que somente os chamadores com um token de acesso válido emitido pelo Azure AD B2C podem fazer solicitações bem-sucedidas para sua API de Gerenciamento de API do Azure.

Suporte a vários aplicativos e emissores

Normalmente, vários aplicativos interagem com uma única API REST. Para habilitar sua API para aceitar tokens destinados a vários aplicativos, adicione as IDs de aplicativo ao elemento <audiences> na política de entrada do Gerenciamento de API.

<!-- Accept tokens intended for these recipient applications -->
<audiences>
    <audience>44444444-0000-0000-0000-444444444444</audience>
    <audience>66666666-0000-0000-0000-666666666666</audience>
</audiences>

Da mesma forma, para dar suporte a vários emissores de token, adicione os URIs de ponto de extremidade ao elemento <issuers> na política de entrada do Gerenciamento de API.

<!-- Accept tokens from multiple issuers -->
<issuers>
    <issuer>https://<tenant-name>.b2clogin.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
    <issuer>https://login.microsoftonline.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
</issuers>

Migrar para b2clogin.com

Se você tiver uma API de Gerenciamento de APIs do Azure que valida tokens emitidos pelo ponto de extremidade herdado login.microsoftonline.com, deverá migrar a API e os aplicativos que o chamam para usar tokens emitidos pelo b2clogin.com.

Você pode seguir este processo geral para executar uma migração em etapas:

  1. Adicione suporte a sua política de entrada do Gerenciamento de API para tokens emitidos por b2clogin.com e login.microsoftonline.com.
  2. Atualize seus aplicativos um de cada vez para obter tokens do ponto de extremidade b2clogin.com.
  3. Depois que todos os aplicativos estiverem obtendo corretamente tokens de b2clogin.com, remova o suporte para tokens emitidos por login.microsoftonline.com da API.

O exemplo de política de entrada do Gerenciamento de API a seguir ilustra como aceitar tokens que são emitidos por b2clogin.com e login.microsoftonline.com. Além disso, a política dá suporte a solicitações de API de dois aplicativos.

<policies>
    <inbound>
        <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
            <openid-config url="https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/B2C_1_signupsignin1/v2.0/.well-known/openid-configuration" />
            <audiences>
                <audience>44444444-0000-0000-0000-444444444444</audience>
                <audience>66666666-0000-0000-0000-666666666666</audience>
            </audiences>
            <issuers>
                <issuer>https://login.microsoftonline.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
                <issuer>https://<tenant-name>.b2clogin.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
            </issuers>
        </validate-jwt>
        <base />
    </inbound>
    <backend> <base /> </backend>
    <outbound> <base /> </outbound>
    <on-error> <base /> </on-error>
</policies>

Próximas etapas

Para obter informações adicionais sobre as políticas do Gerenciamento de API, confira o índice de referência da política do Gerenciamento de API.

Você pode encontrar informações sobre como migrar APIs da Web baseadas em OWIN e seus aplicativos para b2clogin.com, confira Migrar uma API da Web baseada em OWIN para b2clogin.com.