Sobre as credenciais de API e o gerenciador de credenciais

Para ajudá-lo a gerenciar o acesso a APIs de back-end, sua instância de Gerenciamento de API inclui um gerenciador de credenciais. Use o gerenciador de credenciais para gerenciar, armazenar e controlar o acesso às credenciais de API de sua instância de Gerenciamento de API.

Observação

  • Atualmente, você pode usar o gerenciador de credenciais para configurar e gerenciar conexões (anteriormente chamadas autorizações) para APIs do OAuth 2.0 de back-end.
  • Nenhuma alteração interruptiva é introduzida com o gerenciador de credenciais. Provedores de credenciais e conexões do OAuth 2.0 usam as APIs e o provedor de recursos de autorização do Gerenciamento de API existente.

Conexões gerenciadas para APIs do OAuth 2.0

Usando o gerenciador de credenciais, você pode simplificar muito o processo de autenticação e autorização de usuários, grupos e entidades de serviço em um ou mais serviços de back-end ou SaaS que usam o OAuth 2.0. Usando o gerenciador de credenciais do Gerenciamento de API, configure facilmente o OAuth 2.0, consinta, adquira tokens, armazene tokens em um repositório de credenciais e atualize tokens sem escrever uma única linha de código. Use políticas de acesso para delegar a autenticação à instância de Gerenciamento de API, entidades de serviço, usuários ou grupos. Para obter informações sobre o OAuth 2.0, consulte Plataforma de identidade da Microsoft e fluxo de código de autorização do OAuth 2.0.

Esse recurso permite que as APIs sejam expostas com ou sem uma chave de assinatura, use as autorizações do OAuth 2.0 para os serviços de back-end e reduza os custos de desenvolvimento para aumentar, implementar e manter recursos de segurança com integrações de serviço.

Diagram of API Management credential manager and supported SaaS identity providers.

Casos de uso de exemplo

Usando conexões do OAuth gerenciadas no Gerenciamento de API, os clientes podem se conectar facilmente a provedores de SaaS ou serviços de back-end que estão usando o OAuth 2.0. Estes são alguns exemplos:

  • Conecte-se facilmente a um back-end SaaS anexando o token de autorização armazenado e fazendo solicitações de proxy

  • Faça solicitações de proxy para um aplicativo Web do Serviço de Aplicativo do Azure ou back-end do Azure Functions anexando o token de autorização, que posteriormente pode enviar solicitações a um back-end SaaS aplicando lógica de transformação

  • Faça solicitações de proxy para back-ends de federação GraphQL anexando vários tokens de acesso para executar a federação facilmente

  • Exponha um ponto de extremidade de token de recuperação, adquira um token armazenado em cache e chame um back-end SaaS em nome do usuário a partir de qualquer computação, por exemplo, um aplicativo de console ou daemon do Kubernetes. Combine seu SDK SaaS favorito em um idioma com suporte.

  • Cenários autônomos do Azure Functions ao se conectar a vários back-ends SaaS.

  • O Durable Functions se aproxima dos Aplicativos Lógicos com a conectividade SaaS.

  • Com as conexões do OAuth 2.0, todas as APIs no Gerenciamento de API podem atuar como um conector personalizado dos Aplicativos Lógicos.

Como funciona o gerenciador de credenciais?

As credenciais de token no gerenciador de credenciais consistem em duas partes: gerenciamento e runtime.

  • A parte de gerenciamento no gerenciador de credenciais cuida da configuração de um provedor de credenciais para tokens do OAuth 2.0, habilitando o fluxo de consentimento para o provedor de identidade e configurando uma ou mais conexões ao provedor de credenciais para acesso às credenciais. Para obter detalhes, consulte Gerenciamento de conexões.

  • A parte de runtime usa a política get-authorization-context para buscar e armazenar os tokens de acesso e atualização da conexão. Quando uma chamada chega no Gerenciamento de API e a política get-authorization-context é executada, ela primeiro valida se o token de autorização existente é válido. Se o token de autorização tiver expirado, o Gerenciamento de API usará um fluxo do OAuth 2.0 para atualizar os tokens armazenados a partir do provedor de identidade. Em seguida, o token de acesso será usado para autorizar o acesso ao serviço de back-end. Para obter detalhes, consulte Runtime de conexões.

Quando usar o gerenciador de credenciais?

Veja a seguir três cenários para usar o gerenciador de credenciais.

Cenário de configuração

Depois de configurar o provedor de credenciais e uma conexão, o gerenciador de API poderá testar a conexão. O gerenciador de API configura uma API do OAuth de back-end de teste para usar a política get-authorization-context usando a identidade gerenciada da instância. Em seguida, o gerenciador de API poderá testar a conexão chamando a API de teste.

Diagram of initial configuration scenario for credential manager.

Cenário autônomo

Por padrão, quando uma conexão é criada, uma política de acesso e uma conexão são pré-configuradas para a identidade gerenciada da instância de Gerenciamento de API. Para usar essa conexão, usuários diferentes podem entrar em um aplicativo cliente, como um aplicativo Web estático, que chama uma API de back-end exposta por meio do Gerenciamento de API. Para fazer essa chamada, as conexões são aplicadas usando a política get-authorization-context. Como a chamada à API usa uma conexão pré-configurada que não está relacionada ao contexto do usuário, os mesmos dados são retornados a todos os usuários.

Diagram of managed identity scenario for credential manager.

Cenário assistido (delegado pelo usuário)

Para habilitar uma experiência de autenticação simplificada para usuários de aplicativos cliente, como aplicativos Web estáticos, que chamam APIs SaaS de back-end que exigem um contexto de usuário, você pode habilitar o acesso a uma conexão em nome de uma identidade de grupo ou de usuário do Microsoft Entra. Nesse caso, um usuário configurado precisar fazer logon e dar consentimento apenas uma vez, e a instância do Gerenciamento de API criará e gerenciará sua conexão depois disso. Quando o Gerenciamento de API recebe uma chamada de entrada a ser encaminhada a um serviço externo, ele anexa o token de acesso da conexão à solicitação. Isso é ideal para quando as solicitações e respostas da API são voltadas para um indivíduo (por exemplo, recuperando informações de perfil específicas do usuário).

Diagram of user-delegated scenario for credential manager.

Como configurar o gerenciador de credenciais?

Requisitos

  • A identidade atribuída ao sistema gerenciado deve ser habilitada para a instância do Gerenciamento de API.

  • A instância do Gerenciamento de API deve ter conectividade de saída com a Internet na porta 443 (HTTPS).

Disponibilidade

  • Todas as camadas de serviço do Gerenciamento de API

  • Sem suporte no gateway auto-hospedado

  • Sem suporte em nuvens soberanas ou nas seguintes regiões, australiacentral, australiacentral2, indiacentral

Exemplos passo a passo

Considerações sobre segurança

O token de acesso e outros segredos (por exemplo, segredos do cliente) são criptografados com uma criptografia de envelope e armazenados em um armazenamento interno multilocatário. Os dados são criptografados com AES-128 usando uma chave exclusiva por dados. Essas chaves são criptografas de forma assimétrica com um certificado mestre armazenado no Azure Key Vault e alternadas todos os meses.

Limites

Recurso Limite
Número máximo de provedores de credenciais por instância de serviço 1.000
Número máximo de conexões por provedor de credenciais 10.000
Número máximo de políticas de acesso por conexão 100
Número máximo de solicitações de autorização por minuto por conexão 250

Perguntas frequentes (FAQ)

Quando os tokens de acesso são atualizados?

Para uma conexão do tipo código de autorização, os tokens de acesso são atualizados da seguinte maneira: quando a política get-authorization-context é executada em runtime, o Gerenciamento de API verifica se o token de acesso armazenado é válido. Se o token tiver expirado ou estiver quase expirado, o Gerenciamento de API usará o token de atualização para buscar um novo token de acesso e um novo token de atualização do provedor de identidade configurado. Se o token de atualização tiver expirado, um erro será gerado e a conexão precisará ser reautorizada antes de funcionar.

O que acontece se o segredo do cliente expirar no provedor de identidade?

No runtime, o Gerenciamento de API não pode buscar novos tokens e ocorre um erro.

  • Se a conexão for do tipo código de autorização, o segredo do cliente precisará ser atualizado no nível do provedor de credenciais.

  • Se a conexão for do tipo credenciais do cliente, o segredo do cliente precisará ser atualizado no nível de conexão.

Esse recurso tem suporte usando o Gerenciamento de API em execução dentro de uma VNet?

Sim, desde que a conectividade de saída na porta 443 esteja habilitada para a marca de serviço AzureConnectors. Para obter mais informações, consulte Referência de configuração de rede virtual.

O que acontece quando um provedor de credenciais é excluído?

Todas as conexões subjacentes e as políticas de acesso também são excluídas.

Os tokens de acesso são armazenados em cache pelo Gerenciamento de API?

Nas camadas de serviço dedicadas, o token de acesso é armazenado em cache pelo Gerenciamento de API até 3 minutos antes do tempo de expiração do token. Se o token de acesso estiver a menos de 3 minutos da expiração, o tempo em cache será até que o token de acesso expire.

Os tokens de acesso não são armazenados em cache no nível de Consumo.