Proteja sua API usando um conector de API em fluxos de usuários de inscrição de autoatendimento do Microsoft Entra External ID

Aplica-se a: Locatários da força de trabalho Locatários externos (saiba mais)

Ao integrar uma API REST em um fluxo de usuário de inscrição de autoatendimento do Microsoft Entra External ID, você deve proteger seu ponto de extremidade da API REST com autenticação. A autenticação da API REST garante que apenas os serviços que possuem credenciais adequadas, como o Microsoft Entra ID, possam fazer chamadas para o seu ponto final. Este artigo vai explorar como proteger a API REST.

Pré-requisitos

Conclua as etapas descritas na guia Passo a passo: adicionar um conector de API a um fluxo de usuário de entrada.

Você pode proteger o ponto de extremidade de API usando a autenticação básica HTTP ou a autenticação de certificado de cliente HTTPS. Em qualquer caso, você fornece as credenciais que o Microsoft Entra ID usa ao chamar o ponto de extremidade de API. O ponto de extremidade de API verifica as credenciais e executa decisões de autorização.

Autenticação básica HTTP

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

A autenticação básica HTTP é definida em RFC 2617. A autenticação Básica funciona da seguinte maneira: o Microsoft Entra ID envia uma solicitação HTTP com as credenciais do cliente (username e password) no cabeçalho Authorization. As credenciais são formatadas como a cadeia de caracteres username:password codificada em base64. Em seguida, sua API é responsável por verificar esses valores para tomar outras decisões de autorização.

Para configurar um conector de API com autenticação básica HTTP, siga estas etapas:

1. Entre no centro de administração do Microsoft Entra como, no mínimo, Administrador de Usuários.
2. Navegue até Identidade>Identidades Externas>Visão geral.
3. Selecione Todos os conectores de API e o Conector de API que deseja configurar.
4. Para o Tipo de autenticação, selecione Básico.
5. Forneça o nome de usuário e a senha do seu ponto de extremidade da API REST.
6. Selecione Save.

Autenticação de certificado do cliente HTTPS

A autenticação de certificado de cliente é uma autenticação mútua baseada em certificado, em que o cliente, o Microsoft Entra ID, fornece seu certificado de cliente ao servidor para provar sua identidade. Isso acontece como parte do handshake SSL. Sua API é responsável por validar os certificados pertencentes a um cliente válido, como o Microsoft Entra ID e por tomar decisões de autorização. O certificado do cliente é um certificado digital X.509.

Importante

Nos ambientes de produção, o certificado precisa ser assinado por uma autoridade de certificação.

Criar um certificado

Opção 1: usar o Azure Key Vault (recomendado)

Para criar um certificado, você pode usar o Azure Key Vault, que tem opções para certificados autoassinados e integrações com provedores de emissor do certificado para certificados assinados. As configurações recomendadas incluem:

• Entidade: CN=<yourapiname>.<tenantname>.onmicrosoft.com
• Tipo de conteúdo: PKCS #12
• Tipo de ação de tempo de vida: Email all contacts at a given percentage lifetime ou Email all contacts a given number of days before expiry
• Tipo de chave: RSA
• Tamanho da chave: 2048
• Chave Privada Exportável: Yes (para exportar o arquivo .pfx)

Depois, você pode exportar o certificado.

Opção 2: preparar um certificado autoassinado usando o PowerShell

Se você ainda não tiver um certificado, será possível usar um certificado autoassinado. Um certificado autoassinado é um certificado de segurança que não é assinado por uma autoridade de certificação (AC) e não fornece as garantias de segurança de um certificado assinado por uma AC.

Windows

No Windows, use o cmdlet New-SelfSignedCertificate no PowerShell para gerar um certificado.

1. Execute o seguinte comando do PowerShell para gerar um certificado autoassinado. Modifique o argumento -Subject conforme apropriado para o aplicativo e o nome do locatário do Azure AD B2C, como contosowebapp.contoso.onmicrosoft.com. Você também pode ajustar a data -NotAfter para especificar uma expiração diferente para o certificado.

   New-SelfSignedCertificate `
       -KeyExportPolicy Exportable `
       -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
       -KeyAlgorithm RSA `
       -KeyLength 2048 `
       -KeyUsage DigitalSignature `
       -NotAfter (Get-Date).AddMonths(12) `
       -CertStoreLocation "Cert:\CurrentUser\My"
   

2. No Windows, pesquise e selecione Gerenciar certificados de usuário

3. Em Certificados – Usuário Atual, selecione Pessoal>Certificados>yourappname.yourtenant.onmicrosoft.com.

4. Selecione o certificado e, em seguida, selecione Ação>Todas as Tarefas>Exportar.

5. Selecione Próximo>Sim, exportar a chave privada>Próximo.

6. Aceite os padrões para Formato de arquivo para exportação e selecione Próximo.

7. Habilite a opção Senha, insira uma senha para o certificado e selecione Próximo.

8. Para especificar um local para salvar seu certificado, selecione Procurar e navegue até um diretório de sua preferência.

9. Na janela Salvar como, insira um Nome de arquivo e, em seguida, selecione Salvar.

10. Selecione Avançar>Concluir.

Para o Azure AD B2C aceitar a senha do arquivo .pfx, a senha deve estar criptografada com a opção TripleDES-SHA1 no utilitário de exportação do repositório de certificados do Windows, em oposição ao AES256-SHA256.

macOS

No macOS, use o Assistente de Certificado no acesso do conjunto de chaves para gerar um certificado.

1. Siga as instruções sobre como criar certificados autoassinados no acesso ao conjunto de chaves em um Mac.
2. No aplicativo de acesso do conjunto de chaves no Mac, selecione o certificado que você criou.
3. Selecione Arquivo>Exportar Itens.
4. Selecione um nome de arquivo para salvar o certificado. Por exemplo: self-signed-certificate.p12.
5. Para Formato de Arquivo, selecione Troca de Informações Pessoais (.p12) .
6. Selecione Salvar.
7. Insira uma senha nas caixas Senha e Verificar.
8. Substitua a extensão do arquivo para .pfx. Por exemplo; self-signed-certificate.pfx.

Configurar seu Conector de API

Para configurar um conector de API com autenticação do certificado do cliente, siga estas etapas:

1. Entre no centro de administração do Microsoft Entra como, no mínimo, Administrador de Usuários.
2. Navegue até Identidade>Identidades Externas>Visão geral.
3. Selecione Todos os conectores de API e o Conector de API que deseja configurar.
4. Para o Tipo de autenticação, selecione Certificado.
5. Na caixa Carregar certificado, selecione o arquivo de certificado .pfx com uma chave privada.
6. Na caixa Inserir Senha, digite a senha do certificado.
7. Selecione Save.

Tomar decisões de autorização

A API deve implementar a autorização com base em certificados de cliente enviados para proteger os pontos de extremidade de API. Para o Serviço de Aplicativo do Azure e o Azure Functions, confira Configurar a autenticação mútua TLS para saber como habilitar e validar o certificado do código de API. Como alternativa, você pode usar o Gerenciamento de API do Azure como uma camada na frente de qualquer serviço de API para verificar as propriedades de certificado do cliente em relação aos valores desejados.

Como renovar certificados

Recomendamos definir alertas de lembrete para quando o certificado vence. Você precisará gerar um novo certificado e repetir as etapas acima quando os certificados usados estiverem prestes a vencer. Para "distribuir" o uso de um novo certificado, o serviço de API pode continuar aceitando certificados novos e antigos por um período temporário enquanto o novo certificado é implantado.

Para carregar um novo certificado em um conector de API existente, selecione o conector de API em Conectores de API e escolha Carregar novo certificado. O certificado carregado mais recentemente que não tenha vencido e cuja data de início já tenha decorrido será automaticamente usado pelo Microsoft Entra ID.

Autenticação da chave de API

Alguns serviços usam um mecanismo de "chave de API" para ocultar o acesso aos pontos de extremidade HTTP durante o desenvolvimento, exigindo que o chamador inclua uma chave exclusiva como um cabeçalho HTTP ou um parâmetro de consulta HTTP. Para o Azure Functions, faça isso incluindo o code como um parâmetro de consulta na URL do Ponto de Extremidade do conector de API. Por exemplo, https://contoso.azurewebsites.net/api/endpoint?code=0123456789.

Esse não é um mecanismo que deve ser usado sozinho em produção. Portanto, a configuração para a autenticação básica ou de certificado é sempre necessária. Se você não quiser implementar nenhum método de autenticação (não recomendado) para fins de desenvolvimento, escolha a autenticação 'básica' na configuração do conector de API e use valores temporários para username e password que a API poderá desconsiderar enquanto você implementa a autorização adequada.

Próximas etapas

• Introdução aos nossos exemplos de início rápido.