Integre seu aplicativo com o Atlas App Connections

Conceitos chave

Acesso delegado

Seu aplicação age em nome de um usuário do Atlas , não como si mesmo. As funções da organização e as permissões de projeto do usuário determinam quais operações são bem-sucedidas. Se o usuário não puder executar uma ação, seu aplicação também não poderá executá-la em nome dele.

Configurações de delegação da organização

Cada organização do Atlas controla se as conexões de aplicativos de terceiros são permitidas. Mesmo quando um usuário autoriza seu aplicação, as operações em uma organização específica são bem-sucedidas somente se essa organização tiver conexões de aplicativos de terceiros ativadas. A delegação está desabilitada por padrão para organizações existentes. Como um usuário pode pertencer a várias organizações, uma única autorização pode ser bem-sucedida para algumas organizações do usuário e falhar para outras, dependendo da configuração de delegação de cada organização.

Chave de Prova para Troca de Código (PKCE)

Uma extensão de segurança para o fluxo de código de autorização OAuth 2.1 que protege contra ataques de interceptação de código de autorização . O PKCE exige que o cliente gere um code_verifier aleatório, derive um code_challenge dele e envie o desafio com a solicitação de autorização . Em seguida, o cliente comprova que originou a solicitação enviando o code_verifier original ao trocar o código de autorização por tokens.

Visão geral do fluxo

clique para ampliar

O fluxo prossegue em três etapas:

1. Seu aplicação gera um verificador e desafio de código PKCE, redireciona o usuário para o ponto de extremidade de autorização do Atlas e o usuário aprova o acesso na tela de consenso.

2. Seu aplicação troca o código de autorização por um token de acesso e um token de atualização.

3. Seu aplicação usa o token de acesso para chamar a API de administração do Atlas e usa o token de atualização para obter novos tokens de acesso antes que eles expirem.

Etapa 1: solicitação de autorização

Direcione o usuário para o endpoint de autorização do Atlas (https://cloud.mongodb.com/oauth/authorize) com os seguintes parâmetros. Você controla como seu aplicação apresenta esse endpoint: um redirecionamento dentro da janela existente, uma nova janela do navegador ou um pop-up.

Envie apenas os parâmetros na tabela anterior. O ponto de extremidade de autorização não exige um parâmetro resource, portanto, omita-o da solicitação de autorização , mesmo que a especificação OAuth 2.1 defina um.

O exemplo a seguir divide a URL em linhas para legibilidade. Envie como uma única linha:

https://cloud.mongodb.com/oauth/authorize
  ?response_type=code
  &client_id=<YOUR_CLIENT_ID>
  &redirect_uri=https://yourapp.example.com/callback
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256
  &state=<RANDOM_STATE_VALUE>

Etapa 2: troca de tokens

Troque o código de autorização por tokens fazendo uma solicitação POST para o endpoint do Atlas token:

POST https://authorize.mongodb.com/tokens

Solicitação de exemplo:

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'code=<AUTHORIZATION_CODE>' \
  --data 'code_verifier=<CODE_VERIFIER>' \
  --data 'redirect_uri=https://yourapp.example.com/callback' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

A resposta inclui:

Etapa 3: atualizar tokens de acesso

Os tokens de acesso são de curta duração (atualmente 10 minutos). Antes de fazer chamadas de API de administração do Atlas após a expiração, troque seu token de atualização por um novo token de acesso:

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'refresh_token=<YOUR_REFRESH_TOKEN>' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

A resposta sempre retorna um novo access_token e um novo refresh_token. O token de atualização anterior é imediatamente invalidado. Sempre substitua ambos os valores armazenados.

Permissões e configurações de delegação da organização

As operações contra uma organização específica do Atlas são bem-sucedidas somente quando ambos os itens a seguir são verdadeiros:

• A organização tem conexões de aplicativos de terceiros habilitadas. Os proprietários da organização definem esta configuração em Organization Settings > App Connections. Para saber mais sobre essas configurações, consulte Visão geral das conexões do aplicativo Atlas .

• O usuário autorizador tem a função necessária para a operação dentro dessa organização ou projeto.

Se a delegação estiver desativada para uma organização depois que um usuário já tiver autorizado seu aplicação, as chamadas da API destinadas a essa organização retornarão uma resposta 403 Forbidden.

Uma autorização concluída não garante que as chamadas da API de administração do Atlas sejam bem-sucedidas. O Atlas avalia a configuração de delegação da organização e as funções do usuário em cada solicitação, não uma vez no momento da autorização , para que o fluxo OAuth e a tela de consenso possam ser concluídos de forma limpa enquanto as solicitações ainda retornam 403 Forbidden.

Verificando o acesso da organização

Ligue para GET /api/atlas/v2/orgs após a autorização para determinar em quais organizações seu aplicação pode atuar. O Atlas retorna apenas as organizações que permitem conexões de aplicativos de terceiros, portanto, uma lista vazia significa que nenhuma organização à qual o usuário pertence as habilitou.

Uma lista vazia é uma etapa de configuração, não uma falha. Instrua o usuário a solicitar a um proprietário da organização que habilite conexões de aplicativos para a organização e ponto para a visão geral de conexões de aplicativos do Atlas . Evite apresentar a lista vazia como um erro de autorização ou autenticação, pois as credenciais e o consenso do usuário são válidos.

Como o acesso delegado carrega as próprias permissões do usuário que o autoriza, as operações de gravação também dependem das roles desse usuário. As operações comuns de provisionamento exigem os seguintes roles:

• Para criar um projeto, o usuário precisa ter a função Organization Owner ou Organization Project Creator.

• Para criar um cluster, o usuário precisa ter a função Project Owner ou Project Cluster Creator no projeto de destino.

Um usuário que detém apenas a função Organization Member pode ler os recursos aos quais tem acesso, mas as operações de gravação retornam 403 Forbidden. Nomeie a função necessária em seu tratamento de erros para que o usuário possa solicitar a função correta. Para saber mais sobre todos os papéis disponíveis, consulte Funções de Usuário do Atlas .

Quando seu aplicação cria uma organização em nome de um usuário, a nova organização ainda não permite conexões de aplicativos de terceiros. Habilitá-los é uma etapa manual: entre em contato com o MongoDB para incluir a organização na lista de permissões. Até lá, seu aplicação não pode agir na organização, mesmo que o usuário tenha autorizado seu aplicação.

Endpoints bloqueados e filtrados

O acesso delegado atinge a maioria dos endpoints da API de administração do Atlas , mas o Atlas trata alguns endpoints de forma diferente, independentemente das permissões do usuário autorizante.

Os endpoints bloqueados retornam uma resposta 403 Forbidden mesmo quando o usuário que autoriza detém uma função que normalmente permitiria a operação. O Atlas bloqueia os endpoints de configurações de federação, que leem e modificam a configuração de federação e logon único (SSO). A configuração do fornecedor de identidade é compartilhada por todas as organização de uma federação, portanto, o acesso delegado a ela pode expor ou interromper organizações que nunca autorizaram seu aplicação.

Os endpoints filtrados aceitam a chamada, mas restringem o que ela pode ver ou alterar, com base nas organizações que optaram por conexões de aplicativos de terceiros. Seu aplicação pode alcançar somente essas organizações, e o Atlas bloqueia o acesso aos recursos de uma organização que não optou por participar.

Os endpoints que abrangem organizações, como aquelas que listam todos os organização, projeto ou cluster que o usuário pode acessar, retornam apenas organizações que permitem conexões de aplicativos de terceiros. Para solicitações que criam recursos, o Atlas valida a organização de destino e rejeita a chamada quando essa organização não optou por participar.

O proprietário de uma organização ativa a partir de Organization Settings > App Connections. Para saber mais,consulte Permissões e Configurações de delegação da organização.

O Atlas pode bloquear ou filtrar endpoints adicionais para acesso delegado ao longo do tempo.

Plano de controle versus plano de dados

A API de administração do Atlas fornece acesso ao plano de controle: você pode criar, configurar e gerenciar recursos do Atlas como organizações, projetos, clusters e usuários. Ele não fornece acesso direto ao plano de dados (leitura ou gravação de documentos em seus bancos de dados).

Para acessar dados nos Atlas clusters, recupere a string de conexão do cluster por meio da API de administração do Atlas e conecte-se usando um usuário de banco de dados e o driver ou shell do MongoDB . A string de conexão e as credenciais do banco de dados são separadas do token de portador OAuth.

A revogação afeta o acesso ao plano de controle e ao plano de dados de maneira diferente. Consulte Efeitos do plano de dados.

Criando usuários do banco de dados

Crie usuários de banco de dados por meio do endpoint POST /api/atlas/v2/groups/{groupId}/databaseUsers da API de administração do Atlas usando o token de portador do usuário que autoriza. O usuário deve ter uma função de projeto que permita o gerenciamento de usuário de banco de dados .

Práticas recomendadas

• Fique dentro do limite de usuário de banco de dados . O Atlas impõe um limite padrão de 100 usuários de banco de dados por projeto. Reutilize usuários de banco de dados existentes sempre que possível, em vez de criar um novo usuário para cada operação, e desprovisione os usuários que você não precisa mais para evitar que o limite seja atingido.

• Use funções com escopo. Crie usuários de banco de dados com as funções mínimas de banco de dados necessárias para seu caso de uso, em vez de atlasAdmin.

• Desprovisione os usuários quando não forem mais necessários. Quando um usuário revogar o acesso ao seu aplicação, exclua todos os usuários do banco de dados que seu aplicação criou em seu nome. O Atlas não remove automaticamente os usuários do banco de dados quando o acesso é revogado.

• Gire as credenciais em um cronograma definido. Se o seu aplicação armazenar senhas de usuário de banco de dados , alterne-as regularmente usando o endpoint PATCH /api/atlas/v2/groups/{groupId}/databaseUsers/ {databaseName}/{username}.

Se o Atlas girar as credenciais de um recurso provisionado pelo aplicação , como a senha de um usuário do banco de dados , ele poderá notificar seu aplicação por meio de um webhook opcional em vez de exigir que você mesmo atualize as credenciais. Isso não está relacionado à rotação do OAuth client_secret; para isso, consulte Token e armazenamento secreto. Para implementar o webhook,consulte Implementar o webhook de rotação de credenciais.

Criptografando credenciais em repouso

Seu aplicação lida com várias categorias de informações confidenciais que devem ser criptografadas em repouso:

• Connection strings. As connection strings do Atlas contêm credenciais incorporadas ou usuários do banco de dados de referência. Criptografe todas as connection strings armazenadas usando o Advanced Encryption Standard (AES)-256 ou criptografia equivalente. Não armazene connection strings em texto simples em arquivos de configuração, armazenamentos de variáveis de ambiente ou bancos de dados.

• Tokens OAuth. Os tokens de atualização são credenciais de longa duração. Armazene-os em um gerenciador de segredos criptografado (por exemplo, HashiCorp Vault, Amazon Web Services (AWS) Secrets Manager ou Azure Key Vault). Não armazene tokens de atualização em seu banco de dados de aplicativo sem criptografia.

• Segredos do cliente. Seu client_secret é equivalente a uma senha. Armazene-o em um gerenciador de segredos e gire-o se suspeitar que ele foi exposto.

Tratamento de connection strings

Quando seu aplicação recupera connection strings da API de administração do Atlas em nome de um usuário:

• Recupere connection strings no momento em que forem necessárias, em vez de armazená-las por longo prazo, sempre que possível.

• Se seu aplicação precisar manter uma string de conexão, armazene somente o que é necessário (por exemplo, o nome do host e a porta) separadamente das credenciais.

• Não registre connection strings nem as inclua em mensagens de erro ou rastreamento de pilha.

Armazenamento secreto e de token

• Não confirme tokens ou segredos para o controle de origem.

• Não registre tokens de acesso, tokens de atualização ou segredos de cliente . Se o seu aplicação registrar solicitações de API de Administração do Atlas para depuração, edite o cabeçalho Authorization.

• Defina o acesso aos segredos em seu gerenciador de segredos apenas para os serviços que os exigem.

• Gire seu client_secret periodicamente e imediatamente se ocorrer uma suspeita de comprometimento. Entre em contato com o MongoDB para girar o segredo associado ao seu aplicação OAuth.

Gatilhos de revogação

A revogação pode ocorrer por meio de qualquer uma das seguintes ações:

• O usuário revoga o acesso da UI do Atlas (User Settings > Connected Apps).

• O proprietário da organização restringe conexões de aplicativos de terceiros para toda a organização a partir de Organization Settings.

• O token de atualização expira porque o tempo de vida máximo do token de atualização da organização foi atingido ou o token estava ocioso além do limite de tempo de vida ocioso.

• Seu aplicação revoga seus próprios tokens quando não precisa mais de acesso.

Revogando tokens do seu aplicativo

Quando um usuário desconectar seu aplicação da sua própria interface ou sua integração não precisar mais de acesso, revogue os tokens em vez de deixá-los expirar. Envie uma solicitação POST para o endpoint de revogação:

curl --request POST \
  --url https://authorize.mongodb.com/tokens/revoke \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user '<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>' \
  --data 'token=<REFRESH_OR_ACCESS_TOKEN>' \
  --data 'token_type_hint=refresh_token'

Revogar um token de atualização também invalida todos os tokens de acesso emitidos a partir dele. O endpoint retorna 200 OK se o token era válido ou não, portanto, trate uma resposta de sucesso como uma confirmação de que o token não pode mais ser usado e não como uma prova de que ele existiu.

Efeitos do plano de controle

A rapidez com que a revogação entra em vigor depende de quem revoga o acesso:

• O proprietário de uma organização restringe as conexões de aplicativos de terceiros: a API de administração do Atlas verifica as configurações de delegação da organização em cada chamada, para que as solicitações contra essa organização comecem a retornar 403 Forbidden imediatamente.

• Um usuário revoga o acesso do seu aplicativo: o token de atualização é invalidado imediatamente, mas qualquer token de acesso já emitido permanece válido até expirar. Como os tokens de acesso são de curta duração, seu aplicação pode continuar a fazer chamadas bem-sucedidas por até 10 minutos. Depois disso, as chamadas retornam 401 Unauthorized.

• O MongoDB exclui seu cliente OAuth : a revogação atinge todas as organização às quais seu aplicação está conectado, o que leva até 15 minutos para ser concluído.

Projete seu aplicação para lidar com respostas 401 e 403 de forma proativa, em vez de depender da propagação imediata.

Efeitos do plano de dados

Revogar o acesso à API de administração do Atlas não encerra imediatamente as conexões do plano de dados existentes. Seu aplicação chega ao plano de dados por meio dos usuários do banco de dados criados, autenticando-se com credenciais independentes dos tokens OAuth. Revogar um token não invalida essas credenciais. As sessões abertas do driver do MongoDB e as conexões do pool de conexões permanecem ativas até que sejam fechadas por eventos normais do ciclo de vida da conexão, como um tempo limite, um fechamento ocioso ou um fechamento explícito pelo seu aplicação.

Como a revogação não remove os usuários do banco de dados criados pelo seu aplicação , limpe-os como parte do fluxo de desconexão. Para saber mais, consulte Ciclo de vida do usuário do banco de dados.

Error Scenarios

Respostas de erro OAuth

Os erros dos endpoints de autorização e token seguem a estrutura OAuth padrão:

{
  "error": "error_code",
  "error_description": "Human-readable explanation"
}

A tabela a seguir lista valores error comuns:

Se o mesmo código de autorização for apresentado mais de uma vez, o servidor invalidará todos os tokens associados a essa concessão como uma medida de segurança contra a interceptação de código. Quando isso ocorre, o usuário deve autorizar novamente desde o início.

Clientes desativados

O MongoDB pode desabilitar um cliente registrado , por exemplo, durante a resposta a incidentes ou a desativação de um parceiro. Enquanto seu cliente estiver desabilitado, o servidor se recusará a iniciar novos fluxos de autorização ou emitir novos tokens:

• O ponto de extremidade de autorização redireciona o usuário para seu redirect_uri com error=access_denied e um error_description de client is disabled.

• O endpoint do token retorna 401 com invalid_client e a mesma descrição. Isso se aplica a todos os tipos de concessão, incluindo refresh_token, portanto, seu aplicação não pode trocar tokens de atualização existentes enquanto ele estiver desativado.

Os tokens de acesso emitidos antes de o cliente ser desabilitado permanecem válidos até expirarem. Desabilitar um cliente bloqueia novos tokens em vez de invalidar os existentes.

Um cliente desativado não pode se recuperar sozinho. Trate client is disabled como uma condição terminal: pare de tentar novamente, mostre a falha e entre em contato com a equipe de parceiros do MongoDB para que o cliente seja reativado.