Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Integre seu aplicativo com as conexões de aplicativos do Atlas

O Atlas App Connections é a plataforma OAuth 2.1 do MongoDB Atlas que permite que seu aplicativo aja em nome dos usuários do Atlas por meio de acesso delegado pelo usuário. Quando um usuário autoriza seu aplicativo, seu aplicativo recebe um conjunto de tokens que pode usar para chamar a Atlas Administration API com as mesmas permissões que o usuário possui em suas organizações no Atlas. Para uma visão geral da plataforma e como as organização gerenciam aplicativos conectados, consulte Visão geral das conexões de aplicativos do Atlas.

Este guia cobre a integração completa:

  • Iniciando o OAuth 2.1 Fluxo de código de autorização com chave de prova para troca de código (PKCE)

  • Troca de códigos de autorização por tokens e atualização de tokens

  • Usando a Atlas Administration API com acesso delegado

  • Compreender o escopo e os limites do acesso delegado

  • Configurando o acesso à rede e gerenciando usuários de banco de dados

  • Lidar com revogação e erros

Acesso delegado
Seu aplicativo age em nome de um Atlas user, não como ele mesmo. As próprias função da organização e permissões de projeto do usuário determinam quais operação são bem-sucedidas. Se o usuário não puder realizar uma ação, seu aplicativo também não poderá realizá-la em seu nome.
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 aplicativo, as operações em uma organização específica só terão êxito se essa organização tiver conexões de aplicativos de terceiros habilitadas. A delegação é 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 das organizações do usuário e falhar para outras, dependendo da configuração de delegação de cada organização.
Proof Key for Code Exchange (PKCE)
Uma extensão de segurança para o fluxo de Authorization Code do OAuth 2.1 Fluxo de Código de autorização 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. O cliente então prova que originou a solicitação enviando o code_verifier original ao trocar o código de autorização por tokens.

Antes de começar, verifique se tem:

  • Status de parceiro de design aprovado.

  • Um aplicativo OAuth registrado. O MongoDB fornece a você um client_id durante a integração. Clientes confidenciais (aplicativos da web do lado do servidor) também recebem um client_secret. Clientes públicos (aplicativos nativos e de página única) autenticam-se apenas com o client_id e não recebem um segredo.

  • Uma URI de redirecionamento registrada com seu aplicativo OAuth. Os URIs de redirecionamento devem usar HTTPS, exceto para endereços de loopback (localhost, 127.0.0.1, ::1), que podem usar HTTP em qualquer porta. URIs de redirecionamento não devem conter fragmentos (#).

  • Familiaridade com o fluxo de 2.1 de código de autorização e Proof Key for Code Exchange (PKCE).

Se você precisar de ativos de marca do MongoDB para sua integração, como o logotipo do MongoDB, consulte a página Recursos de marca do MongoDB.

Desenvolva e lance sua integração em produção. O Atlas não fornece ambientes de parceiro separados.

Todos os pontos de extremidade de OAuth e API usam duas URLs base de produção:

Base
URL

Base de autorização ({OAUTH_BASE})

https://authorize.mongodb.com

Base da nuvem ({CLOUD_BASE})

https://cloud.mongodb.com

Ao longo deste guia, esses nomes representam as URLs acima. Por exemplo, o ponto de extremidade de token é {OAUTH_BASE}/tokens.

O ponto de extremidade de autorização onde os usuários se conectam e concedem acesso é hospedado na base da nuvem ({CLOUD_BASE}/oauth/authorize), enquanto o token e outros pontos de extremidade OAuth são hospedados na base de autorização ({OAUTH_BASE}). Essa divisão é intencional. O Atlas Administration API é hospedado na base da nuvem ({CLOUD_BASE}/api/atlas).

Dica

Descubra pontos de extremidade automaticamente

O Atlas publica metadados do servidor OAuth 2.1 em {OAUTH_BASE}/.well-known/oauth-authorization-server. Muitas bibliotecas e SDKs de cliente OAuth podem ler esse ponto de extremidade para descobrir e configurar automaticamente os pontos de extremidade de autorização, token e relacionados, o que evita o hardcoding de URLs de ponto de extremidade.

As conexões de aplicativo do Atlas usam o OAuth 2.1 Fluxo de código de autorização com Proof Key for Code Exchange (PKCE). Esse fluxo requer interação do usuário: o usuário se conecta ao Atlas e aprova as permissões que seu aplicativo solicita.

O fluxo ocorre em três etapas:

  1. Seu aplicativo gera um verificador e um 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 consentimento.

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

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

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

Parâmetro
Obrigatório
Descrição

response_type

Obrigatório

Deve ser code.

client_id

Obrigatório

O ID do cliente do seu aplicativo, fornecido pelo MongoDB durante a integração.

redirect_uri

Obrigatório

O URI HTTPS para onde o Atlas envia o código de autorização após a aprovação do usuário. Deve corresponder a um URI registrado com seu aplicativo OAuth.

code_challenge

Obrigatório

O desafio de código PKCE derivado do seu code_verifier. Gere uma string aleatória de 43a 128caracteres como code_verifier, depois calcule BASE64URL(SHA256(code_verifier)).

code_challenge_method

Obrigatório

Deve ser S256. O método plain não é suportado e é rejeitado.

state

Obrigatório

Um valor opaco que seu aplicativo usa para manter o estado entre a solicitação de autorização e a chamada de resposta. Use isso para proteger contra ataques de falsificação de solicitação entre sites (CSRF) e para restaurar o estado do aplicativo após o redirecionamento.

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

O exemplo a seguir quebra a URL em várias linhas para facilitar a leitura. 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>

Depois que o usuário se conectar ao Atlas, ele verá uma tela de consentimento que lista as permissões que seu aplicativo está solicitando:

  • Saiba a quais recursos do Atlas você tem acesso

  • Agir em seu nome nas organizações do Atlas

A tela de consentimento também exibe o seguinte aviso ao usuário:

Ao autorizar um aplicativo:

  • Você está permitindo que ele acesse e execute ações em seus recursos do MongoDB Atlas da mesma forma que você pode, usando as permissões da sua conta.

  • Você pode revogar o acesso a qualquer momento.

Se o usuário clicar em Authorize, o Atlas redireciona para o seu redirect_uri com uma code de autorização, o valor state que você forneceu e um parâmetro iss. Se o usuário clicar em Decline, o Atlas redireciona com um parâmetro error.

Seu manipulador de chamada de resposta deve:

  1. Verifique se state corresponde ao valor que você enviou na solicitação de autorização para evitar ataques CSRF.

  2. Verifique se iss corresponde à base de autorização (https://authorize.mongodb.com) para evitar ataques de confusão de servidor de autorização.

  3. Verifique se há um parâmetro error e lide com a negação normalmente antes de tentar usar o code.

Os códigos de autorização são de uso único e expiram em 10 minutos. Troque-os prontamente.

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

POST https://authorize.mongodb.com/tokens
Parâmetro do corpo
Obrigatório
Descrição

grant_type

Obrigatório

Deve ser authorization_code.

code

Obrigatório

O código de autorização recebido do redirecionamento.

redirect_uri

Obrigatório

O mesmo URI de redirecionamento usado na solicitação de autorização.

code_verifier

Obrigatório

A string original do verificador de código PKCE.

client_id

Obrigatório

O ID do cliente do seu aplicativo.

client_secret

Condicional

O segredo do cliente do seu aplicativo. Necessário apenas para clientes confidenciais (aplicativos da web do lado do servidor). Clientes públicos (aplicativos nativos e de página única) autenticam-se apenas com o client_id e omitem este parâmetro.

Exemplo de solicitação:

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:

Campo
Tipo
Descrição

access_token

string

Bearer token para autenticar solicitações da Atlas Administration API. De curta duração. Conte com o valor expires_in para determinar quando atualizar, em vez de codificar um tempo de vida.

refresh_token

string

Token usado para obter um novo token de acesso quando o atual expira. Armazene isso com segurança.

token_type

string

Sempre Bearer.

expires_in

inteiro

Tempo de vida do token de acesso em segundos. Atualmente 600 (10 minutos). Conte com esse valor para determinar quando atualizar em vez de codificar um tempo de vida, pois o padrão pode mudar.

Os tokens de acesso têm vida curta (atualmente 10 minutos). Antes de fazer chamadas para chamar a Atlas Administration API 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 é invalidado imediatamente. Sempre substitua ambos os valores armazenados.

Importante

Tokens de atualização expiram após 7 dias de inatividade (o tempo de vida ocioso). Independentemente da atividade, os usuários devem se reautenticar a cada 30 dias (o tempo de vida máximo). Organization Owner podem configurar limites mais rígidos. Quando um token de atualização expira, o usuário deve reautorizar seu aplicativo. Projete seu aplicativo para lidar com isso de forma elegante, solicitando que o usuário se reconecte.

Após obter um token de acesso, use-o para fazer solicitações da Atlas Administration API incluindo-o no cabeçalho Authorization:

Authorization: Bearer <ACCESS_TOKEN>

Exemplo de solicitação:

curl --request GET \ --url 'https://cloud.mongodb.com/api/atlas/v2/orgs' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --header 'Accept: application/vnd.atlas.2023-01-01+json'

Seu aplicativo atua com as mesmas permissões que o usuário autorizador possui no momento de cada solicitação. Se as funções do usuário mudarem após a autorização, as permissões efetivas do seu aplicativo mudarão de acordo.

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

  • A organização tem conexões de aplicativos de terceiros habilitadas. Organization Owner configuram essa configuração em Organization Settings > App Connections. Para aprender mais sobre essas configurações, consulte Visão geral das conexões de aplicativos do 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 aplicativo, as chamar de API direcionadas a essa organização retornarão uma resposta 403 Forbidden.

Uma autorização concluída não oferece garantias de que as chamadas da Atlas Administration API sejam bem-sucedidas. O Atlas avalia a configuração de delegação da organização e as função do usuário em cada solicitação, não apenas no momento da autorização, portanto, o fluxo OAuth e a tela de consentimento podem ser concluídos normalmente enquanto as solicitações ainda retornam 403 Forbidden.

Chame GET /api/atlas/v2/orgs após a autorização para determinar em quais organizações seu aplicativo 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 os ativou.

Uma lista vazia é uma etapa de configurar, não uma falha. Solicite ao usuário que peça a um Organization Owner para habilitar conexões de aplicativo para a organização e indique a ele a Visão geral das conexões de aplicativo do Atlas. Evite apresentar a lista vazia como um erro de autorização ou autenticação, pois as credenciais e o consentimento do usuário são válidos.

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

Um usuário que possui 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 no seu tratamento de erros para que o usuário possa fazer a solicitação da função correta. Para aprender sobre todas as funções disponíveis, consulte Funções do Atlas User.

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

O acesso delegado alcança a maioria dos pontos de extremidade da Atlas Administration API, mas o Atlas trata alguns pontos de extremidade de forma diferente, independentemente das permissões do usuário que está autorizando.

Pontos de extremidade bloqueados retornam uma resposta 403 Forbidden mesmo quando o usuário autorizador possui uma função que normalmente permitiria a operação. O Atlas bloqueia os pontos de extremidade de configurações de federação, que leem e modificam a configuração de federação e logon único (SSO). A configuração do provedor de identidade é compartilhada entre todas as organizações em uma federação, portanto, o acesso delegado a ela pode expor ou interromper organizações que nunca autorizaram seu aplicativo.

Pontos de extremidade com filtro aceitam chamar, mas restringem o que ela pode ver ou alterar, com base em quais organizações optaram por conexões de aplicativos de terceiros. Seu aplicativo pode acessar apenas essas organizações, e o Atlas bloqueia o acesso aos recursos de uma organização que não optou por participar.

Os pontos de extremidade que abrangem organizações, como aqueles que listam todas as organizações, projetos ou clusters 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 chamar quando essa organização não optou por participar.

Um Organization Owner opta por participar em Organization Settings > App Connections. Para aprender mais, consulte Permissões e configurações de delegação de organização.

O Atlas pode bloquear ou filtrar pontos de extremidade adicionais para acesso delegado ao longo do tempo.

A Atlas Administration API 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 documento em seus bancos de dados).

Para acessar dados em cluster do Atlas, recupere a string de conexão do cluster por meio da Atlas Administration API e conecte-se usando um usuários 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 Bearer token OAuth.

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

O acesso delegado vincula os tokens do seu aplicativo ao usuário que autoriza. Se as função desse usuário mudarem, o usuário for desligado ou o usuário não se autenticar novamente dentro do tempo de vida do token de atualização, seu aplicativo perderá as permissões de que precisa, mesmo que sua integração em si ainda esteja ativa.

Se a sua integração precisar de acesso contínuo à Atlas Administration API que não dependa de um usuário específico permanecer autorizado, por exemplo, redimensionar clusters ou alterar regiões de implantação de forma contínua, crie uma conta de serviço para a organização e o projeto do cliente em vez de depender de acesso delegado para esse fluxo de trabalho.

Uma conta de serviço é autenticada usando o fluxo de 2.0 de credenciais de cliente em vez do fluxo de código de autorização, portanto, não depende da sessão contínua de um usuário. Cada conta de serviço pertence a uma organização e você pode conceder a ela acesso a qualquer número de projetos dentro dessa organização. As funções do Atlas limitam quais operações os tokens de acesso da conta de serviço podem autenticar, da mesma forma que as funções limitam um usuário. Uma conta de serviço não pode entrar na IU do Atlas e, como o acesso delegado, não fornece acesso ao plano de dados.

Para criar uma conta de serviço para a organização de um cliente, consulte Visão geral das contas de serviço e Criar uma conta de serviço para uma organização.

A maioria das integrações de parceiros provisiona recursos do Atlas em nome do usuário autorizador. A sequência a seguir cobre o caminho comum de uma conexão autorizada para uma string de conexão utilizável. Cada solicitação usa o Bearer token de Etapa 2: Troca de token.

1

Chame GET /api/atlas/v2/orgs para listar as organizações que o usuário autorizador pode acessar, depois GET /api/atlas/v2/orgs/{orgId}/groups para listar os projetos dentro de uma organização.

Apenas organizações que permitem conexões de aplicativos de terceiros aparecem como destinos utilizáveis. Para saber mais, consulte Permissões e configurações de delegação de organização.

2

Chame POST /api/atlas/v2/groups com o nome do projeto e o orgId da organização de destino. O Atlas valida as orgId no corpo da solicitação e retorna 403 Forbidden quando essa organização não permite conexões de aplicativos de terceiros.

3

Chamar POST /api/atlas/v2/groups/{groupId}/clusters com o nome do cluster, tipo de cluster e especificação de replicação. A criação de cluster é assíncrona. Faça polling de GET /api/atlas/v2/groups/{groupId}/clusters/{clusterName} até que o stateName do cluster seja IDLE.

4

Chame POST /api/atlas/v2/groups/{groupId}/databaseUsers para criar a identidade que seu aplicativo usa para acesso ao plano de dados. Para obter orientação sobre funções e ciclo de vida, consulte Ciclo de vida de usuários de banco de dados.

5

Adicione os endereços IP de saída do seu aplicativo à lista de acesso do projeto ou configure uma opção de conectividade privada. Para aprender mais, consulte Configuração de rede e lista de permissões de IP.

6

Leia o campo connectionStrings do recurso do cluster e, em seguida, conecte-se com um driver MongoDB usando o usuário de banco de dados que você criou. A string de conexão e as credenciais do banco de dados são separadas do Bearer token do OAuth.

Para os esquemas completos de solicitação e resposta para cada ponto de extremidade, consulte a Atlas Administration API Specification.

A Atlas Administration API está disponível apenas pela internet pública. Não está disponível por meio de emparelhamento de nuvem privada virtual (VPC) ou private endpoints. Seu aplicativo deve ser capaz de acessar cloud.mongodb.com na porta 443.

Observação

O acesso delegado à Atlas Administration API ignora quaisquer restrições da lista de acesso da API do plano de controle (lista de permissões de IP da chave de API) que o cliente tenha configurado. O acesso é regido pelas permissões do usuário autorizador e pelas configurações de delegação da organização, não por restrições de IP do plano de controle. Para aprender mais, consulte Limitações.

Para acesso ao plano de dados, o cluster Atlas ao qual você está se conectando pode ter uma lista de acesso IP configurada. Os endereços IP de saída do seu aplicativo devem ser adicionados à lista de acesso IP do cluster, ou você deve configurar o emparelhamento de rede ou um private endpoints apropriado para sua implantação.

Padrão de conectividade na versão inicial:

  • Seu aplicativo é responsável por configurar a lista de permissões de IP para acesso ao plano de dados. Isso não é feito automaticamente pela plataforma Atlas Aplicativo Connections.

  • Para cada cluster que seu aplicativo provisiona ou acessa, adicione seus IPs de saída ou faixas de Classless Inter-Domain Routing (CIDR) à lista de acesso IP do cluster usando o ponto de extremidade POST /api/atlas/v2/groups/{groupId}/accessList.

  • Nunca exponha o plano de dados à internet pública. Sempre restrinja o acesso ao plano de dados com lista de acesso IP ou conexões privadas, como emparelhamento de rede ou private endpoints.

Seu aplicativo pode precisar criar e gerenciar usuários de banco de dados durante o provisionamento de clusters Atlas em nome dos usuários. Os padrões a seguir são suportados no lançamento inicial.

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

  • Mantenha-se dentro do limite de usuários de banco de dados. O Atlas forçar um limite padrão de 100 usuários de banco de dados por projeto. Reutilize os 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 de que você não precisa mais para evitar atingir o limite.

  • Use funções com escopo definido. Crie usuários de banco de dados com as funções de banco de dados mínimas 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 revoga o acesso ao seu aplicativo, exclua todos os usuários de banco de dados que seu aplicativo criou em nome deles. O Atlas não remove automaticamente usuários de banco de dados quando o acesso é revogado.

  • Gire as credenciais em um agendar definido. Se o seu aplicativo armazena senhas de usuários de banco de dados, gire-as regularmente usando o ponto de extremidade PATCH /api/atlas/v2/groups/{groupId}/databaseUsers/ {databaseName}/{username}.

Importante

O Atlas não exclui automaticamente usuários de banco de dados ou outros recursos que seu aplicativo criou quando um usuário revoga o acesso. Seu aplicativo é responsável por limpar os recursos que criou. A falha em desprovisionar usuários de banco de dados deixa as credenciais ativas na conta do Atlas do usuário depois que eles desconectam seu aplicativo. Para aprender mais, consulte Limitações.

Se o Atlas girar as credenciais para um recurso que seu aplicativo provisionou, como a senha de um usuário de banco de dados, ele poderá notificar seu aplicativo por meio de um webhook opcional, em vez de exigir que você atualize as credenciais por conta própria. Isso não está relacionado a renovar seu OAuth client_secret; para isso, consulte Armazenamento de Token e Segredo. Para implementar o webhook, consulte Implementar o webhook de rotação de credenciais.

Esta seção descreve os requisitos mínimos de segurança para o manuseio de credenciais e informações confidenciais em sua integração. Essas práticas reduzem o raio de explosão de um incidente de segurança e são obrigatórias para parceiros de design.

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

  • String de conexão. As string de conexão do Atlas contêm credenciais incorporadas ou fazem referência a usuários de banco de dados. Criptografado qualquer string de conexão armazenar usando o Advanced Encryption Standard (AES)-256 ou criptografia equivalente. Não armazenar string de conexão em texto simples em arquivo de configuração, armazenamento de variáveis de ambiente ou banco de dados.

  • Tokens OAuth. Tokens de atualização são credenciais de longa duração. Armazene-os em um gerente de segredos criptografado (por exemplo, HashiCorp Vault, Amazon Web Services (Amazon Web Services) 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. Armazenar em um gerente de segredos e gire-o se suspeitar que ele foi exposto.

Dica

Prefira a autenticação sem segredos

O Atlas oferece suporte à autenticação sem segredos usando PKCE, o que remove a necessidade de gerenciar um client_secret. Sempre que o tipo de cliente permitir, use a autenticação sem segredos como a opção mais segura em vez de fazer o provisionamento e armazenar um segredo de cliente.

Quando seu aplicativo recupera strings de conexão da Atlas Administration API em nome de um usuário:

  • Recupere as strings de conexão no momento em que forem necessárias, em vez de armazená-las por um longo período, sempre que possível.

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

  • Não faça log de string de conexão nem as inclua em mensagens de erro ou pilha.

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

  • Não faça log de tokens de acesso, tokens de atualização ou segredos de cliente. Se o seu aplicativo fizer log de solicitações da Atlas Administration API para depuração, oculte o cabeçalho Authorization.

  • Limite o acesso a segredos no seu gerente de segredos apenas aos 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 aplicativo OAuth.

Entender o comportamento de revogação é importante para projetar uma integração resiliente. A revogação pode ser acionada de várias maneiras e afeta o acesso ao plano de controle e ao plano de dados de forma diferente.

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

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

  • Organization Owner 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 ficou ocioso além do limite de tempo de vida ocioso.

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

Importante

Os acionar acima revogam tokens emitidos por meio do fluxo OAuth. Eles não afetam uma conta de serviço que você criou para acesso contínuo (consulte Acesso contínuo com contas de serviço), porque uma conta de serviço não está vinculada à autorização de nenhum usuário individual.

Não revogue ou exclua as credenciais da conta de serviço de um cliente apenas porque um usuário individual revoga o acesso delegado ou é desligado da organização. A conta de serviço representa a autorização contínua da sua integração, não o acesso individual desse usuário.

Revogue as credenciais da conta de serviço quando o cliente excluir ou desconectar sua integração da conta dele, de acordo com o que essa ação significa em seu produto.

Quando um usuário desconecta seu aplicativo da sua própria interface, ou sua integração não precisa mais de acesso, revogue os tokens em vez de deixá-los expirar. Envie uma solicitação POST para o ponto de extremidade 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'
Parâmetro
Obrigatório
Descrição

token

Obrigatório

O token de acesso ou token de atualização a ser revogado.

token_type_hint

Opcional

access_token ou refresh_token. Ajuda o servidor a otimizar a busca de tokens.

A revogação de um token de atualização também invalida todos os tokens de acesso emitidos a partir dele. O ponto de extremidade retorna 200 OK independentemente de o token ser válido ou não, portanto, trate uma resposta de sucesso como confirmação de que o token não é mais utilizável, em vez de prova de que ele existia.

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

  • Um Organization Owner restringe as conexões de aplicativos de terceiros: a Atlas Administration API verifica as configurações de delegação da organização em cada chamar, portanto, as solicitações feitas a essa organização começam 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 têm vida curta, seu aplicativo pode continuar a fazer chamadas bem-sucedidas por até 10 minutos. Depois disso, chamar retornam 401 Unauthorized.

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

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

A revogação do acesso à Atlas Administration API não encerra imediatamente as conexões existentes do plano de dados. Seu aplicativo acessa o plano de dados por meio dos usuários de banco de dados que ele criou, autenticando-se com credenciais que são independentes de seus tokens OAuth. A revogação de um token não invalida essas credenciais. As sessões do driver do MongoDB e as conexões do pool de conexões permanecem ativas até serem fechadas por eventos normais do ciclo de vida da conexão, como um tempo limite, um fechamento por inatividade ou um fechamento explícito pelo seu aplicativo.

Como a revogação não remove os usuários de banco de dados que seu aplicativo criou, remova-os como parte do seu fluxo de desconexão. Para aprender mais, consulte Ciclo de vida do usuário de banco de dados.

Cenário
Status
Ação Recomendada

Token de acesso expirado

401

Use o token de atualização para obter um novo token de acesso.

Token de acesso revogado

401

Solicite que o usuário autorize novamente. O token de atualização também é invalidado.

Token de atualização expirado ou revogado

400

Solicite que o usuário autorize novamente. Reinicie o fluxo de autorização Code.

Credenciais de cliente inválidas

401

Verifique seu client_id e client_secret.

Delegação desativada para organização

403

Informe ao usuário que sua organização do Atlas não permite conexões de aplicativos de terceiros. Direcione-os ao seu Organization Owner.

Ponto de extremidade bloqueado

403

O ponto de extremidade solicitado não está disponível por meio de acesso delegado. Remover chamar da sua integração.

O usuário não tem a função necessária

403

O usuário autorizador não tem a função necessária para esta operação. Informe o usuário e sugira que ele solicite a função necessária do Organization Owner da organização dele.

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

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

A tabela a seguir lista valores comuns de error:

Código de erro
Quando
Ação Recomendada

invalid_request

Um parâmetro obrigatório está ausente ou malformado.

Verifique os parâmetros e a formatação necessários.

invalid_client

Falha na autenticação do cliente.

Verifique seu client_id e client_secret.

invalid_grant

O código de autorização expirou ou já foi usado, ou o token de atualização é inválido.

Reinicie o fluxo de código de autorização.

unauthorized_client

O cliente não está autorizado para este tipo de concessão.

Verifique se o seu registro de cliente inclui authorization_code.

access_denied

O usuário negou o consentimento.

Informe o usuário. Não tente novamente automaticamente.

invalid_target

O parâmetro resource é inválido ou está ausente.

Verifique se o recurso está registrado para seu cliente.

unsupported_token_type

O valor token_type_hint é inválido.

Use access_token ou refresh_token.

Se o mesmo código de autorização for apresentado mais de uma vez, o servidor invalida 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.

O MongoDB pode desativar um cliente registrado, por exemplo, durante a resposta a incidentes ou o desligamento de um parceiro. Enquanto seu cliente estiver desativado, o servidor se recusa 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 ponto de extremidade 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 aplicativo não pode trocar tokens de atualização existentes enquanto estiver desabilitado.

Os tokens de acesso emitidos antes da desativação do cliente permanecem válidos até expirarem. Desativar um cliente bloqueia novos tokens em vez de invalidar os existentes.

Um cliente desativado não consegue se recuperar por conta própria. 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.

Avalie esta página