Partilhar via

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

  • Artigo

Aplica-se a:Círculo verde com um símbolo de marca de verificação branco. Locatários da força deCírculo branco com um símbolo X cinzento. trabalho Locatários externos (saiba mais)

Ao integrar uma API REST em um fluxo de usuário de inscrição de autoatendimento de ID Externa do Microsoft Entra, 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 tenham credenciais adequadas, como o Microsoft Entra ID, possam fazer chamadas para o seu ponto de extremidade. Este artigo explora como proteger a API REST.

Pré-requisitos

Conclua as etapas no Passo a passo: Adicionar um conector de API a um guia de fluxo de usuário de inscrição.

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

Autenticação básica HTTP

Gorjeta

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

A autenticação básica HTTP é definida no RFC 2617. A autenticação básica funciona da seguinte forma: o Microsoft Entra ID envia uma solicitação HTTP com as credenciais do cliente (username e password) no Authorization cabeçalho. As credenciais são formatadas como a cadeia de caracteres username:passwordcodificada em base64. Sua API é responsável por verificar esses valores para executar 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 pelo menos um Administrador de Usuário.
  2. Navegue até Visão>geral de identidades>externas.
  3. Selecione Todos os conectores de API e, em seguida, selecione o Conector de API que você deseja configurar.
  4. Para o Tipo de autenticação, selecione Básico.
  5. Forneça o nome de usuário e a senha do ponto de extremidade da API REST. Captura de tela da configuração de autenticação básica para um conector de API.
  6. Selecione Guardar.

Autenticação de certificado de cliente HTTPS

A autenticação de certificado de cliente é uma autenticação baseada em certificado mútuo, onde o cliente, 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 executar decisões de autorização. O certificado do cliente é um certificado digital X.509.

Importante

Em ambientes de produção, o certificado deve ser assinado por uma autoridade de certificação.

Criar um certificado

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

  • Assunto: CN=<yourapiname>.<tenantname>.onmicrosoft.com
  • Tipo de conteúdo: PKCS #12
  • Tipo de Acton vitalício: 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 poder exportar .pfx o arquivo)

Em seguida, você pode exportar o certificado.

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

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

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 -Subject argumento conforme apropriado para seu aplicativo e nome de locatário do Azure AD B2C, como contosowebapp.contoso.onmicrosoft.com. Você também pode ajustar a -NotAfter data 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 computador Windows, procure e selecione Gerenciar certificados de usuário

  3. Em Certificados - Usuário Atual, selecione Certificados Pessoais>>yourappname.yourtenant.onmicrosoft.com.

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

  5. Selecione Avançar>Sim, exportar a chave>privada Avançar.

  6. Aceite os padrões para Exportar Formato de Arquivo e selecione Avançar.

  7. Ative a opção Senha , digite uma senha para o certificado e selecione Avançar.

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

  9. Na janela Guardar Como, introduza um Nome de ficheiro e, em seguida, selecione Guardar.

  10. Selecione Seguinte>Concluir.

Para que o Azure AD B2C aceite a senha do arquivo .pfx, a senha deve ser criptografada com a opção TripleDES-SHA1 no utilitário Exportação do Windows Certificate Store, em oposição a AES256-SHA256.

Configurar o conector da API

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

  1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Usuário.
  2. Navegue até Visão>geral de identidades>externas.
  3. Selecione Todos os conectores de API e, em seguida, selecione o Conector de API que você deseja configurar.
  4. Para o Tipo de autenticação, selecione Certificado.
  5. Na caixa Carregar certificado, selecione o arquivo .pfx do certificado com uma chave privada.
  6. Na caixa Inserir Senha, digite a senha do certificado. Captura de tela da configuração de autenticação de certificado para um conector de API.
  7. Selecione Guardar.

Executar decisões de autorização

Sua API deve implementar a autorização com base nos certificados de cliente enviados para proteger os pontos de extremidade da API. Para o Serviço de Aplicativo do Azure e o Azure Functions, consulte configurar a autenticação mútua TLS para saber como habilitar e validar o certificado do seu 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 do certificado do cliente em relação aos valores desejados.

Renovação de certificados

É recomendável definir alertas de lembrete para quando o certificado expirar. Você precisará gerar um novo certificado e repetir as etapas acima quando os certificados usados estiverem prestes a expirar. Para "rolar" o uso de um novo certificado, seu serviço de API pode continuar a aceitar certificados antigos e novos por um período temporário de tempo 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 selecione Carregar novo certificado. O certificado carregado mais recentemente que não expirou e cuja data de início passou será automaticamente usado pelo Microsoft Entra ID.

Captura de ecrã de um novo certificado, quando já existir.

Autenticação de chave de API

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

Este não é um mecanismo que deva ser usado sozinho na produção. Portanto, a configuração para autenticação básica ou de certificado é sempre necessária. Se você não deseja implementar nenhum método de autenticação (não recomendado) para fins de desenvolvimento, você pode selecionar a autenticação 'básica' na configuração do conector da API e usar valores temporários para username e password que sua API pode desconsiderar enquanto implementa a autorização adequada.

Próximos passos