Visão geral
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
Conceitos chave
- 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_verifieraleatório, derive umcode_challengedele e envie o desafio com a solicitação de autorização. O cliente então prova que originou a solicitação enviando ocode_verifieroriginal ao trocar o código de autorização por tokens.
Pré-requisitos
Antes de começar, verifique se tem:
Status de parceiro de design aprovado.
Um aplicativo OAuth registrado. O MongoDB fornece a você um
client_iddurante a integração. Clientes confidenciais (aplicativos da web do lado do servidor) também recebem umclient_secret. Clientes públicos (aplicativos nativos e de página única) autenticam-se apenas com oclient_ide 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).
Diretrizes de marca
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.
URLs base
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 ( |
|
Base da nuvem ( |
|
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.
OAuth 2.1 Fluxo de código de autorização com PKCE
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.
Visão geral do fluxo

O fluxo ocorre em três etapas:
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.
Seu aplicativo troca o código de autorização por um token de acesso e um token de atualização.
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.
Etapa 1: Solicitação de autorização
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 |
|---|---|---|
| Obrigatório | Deve ser |
| Obrigatório | O ID do cliente do seu aplicativo, fornecido pelo MongoDB durante a integração. |
| 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. |
| Obrigatório | O desafio de código PKCE derivado do seu |
| Obrigatório | Deve ser |
| 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>Tela de Consentimento
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:
Verifique se
statecorresponde ao valor que você enviou na solicitação de autorização para evitar ataques CSRF.Verifique se
isscorresponde à base de autorização (https://authorize.mongodb.com) para evitar ataques de confusão de servidor de autorização.Verifique se há um parâmetro
errore lide com a negação normalmente antes de tentar usar ocode.
Os códigos de autorização são de uso único e expiram em 10 minutos. Troque-os prontamente.
Passo 2: Troca de token
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/tokensParâmetro do corpo | Obrigatório | Descrição |
|---|---|---|
| Obrigatório | Deve ser |
| Obrigatório | O código de autorização recebido do redirecionamento. |
| Obrigatório | O mesmo URI de redirecionamento usado na solicitação de autorização. |
| Obrigatório | A string original do verificador de código PKCE. |
| Obrigatório | O ID do cliente do seu aplicativo. |
| 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 |
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 |
|---|---|---|
| string | Bearer token para autenticar solicitações da Atlas Administration API. De curta duração. Conte com o valor |
| string | Token usado para obter um novo token de acesso quando o atual expira. Armazene isso com segurança. |
| string | Sempre |
| inteiro | Tempo de vida do token de acesso em segundos. Atualmente |
Etapa 3: Atualizando tokens de acesso
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.
Usando a Atlas Admin API com acesso delegado
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.
Permissões e Configurações de Delegação da Organização
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.
Verificando o acesso à organização
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:
Para criar um projeto, o usuário precisa da função
Organization OwnerouOrganization Project Creator.Para criar um cluster, o usuário precisa da função
Project OwnerouProject Cluster Creatorno projeto de destino.
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.
Pontos de extremidade bloqueados e com filtro
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.
Plano de controle versus Plano de dados
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.
Acesso contínuo com contas de serviço
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.
Provisionamento de recursos para um usuário
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.
Identifique a organização e o projeto de destino.
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.
Criar um utilizador de banco de dados.
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.
Configure o acesso à rede.
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.
Para os esquemas completos de solicitação e resposta para cada ponto de extremidade, consulte a Atlas Administration API Specification.
Configuração de rede e lista de permissões de IP
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.
Ciclo de vida do usuário de banco de dados
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.
Criando usuários de banco de dados
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.
Práticas recomendadas
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.
Melhores práticas de segurança
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.
Credenciais criptografadas em repouso
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.
Tratamento de string de conexão
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.
Armazenamento de Token e Segredo
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_secretperiodicamente e imediatamente se ocorrer uma suspeita de comprometimento. Entre em contato com o MongoDB para girar o segredo associado ao seu aplicativo OAuth.
Revogação e Tratamento de erros
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.
Acionar de Revogação
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.
Revogação de tokens do seu aplicativo
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 |
|---|---|---|
| Obrigatório | O token de acesso ou token de atualização a ser revogado. |
| Opcional |
|
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.
Efeitos do Plano de Controle
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 Forbiddenimediatamente.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.
Efeitos do Plano de Dados
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.
Error Scenarios
Cenário | Status | Ação Recomendada |
|---|---|---|
Token de acesso expirado |
| Use o token de atualização para obter um novo token de acesso. |
Token de acesso revogado |
| Solicite que o usuário autorize novamente. O token de atualização também é invalidado. |
Token de atualização expirado ou revogado |
| Solicite que o usuário autorize novamente. Reinicie o fluxo de autorização Code. |
Credenciais de cliente inválidas |
| Verifique seu |
Delegação desativada para organização |
| 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 |
| 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 |
| 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. |
Respostas de erro de OAuth
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 |
|---|---|---|
| Um parâmetro obrigatório está ausente ou malformado. | Verifique os parâmetros e a formatação necessários. |
| Falha na autenticação do cliente. | Verifique seu |
| 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. |
| O cliente não está autorizado para este tipo de concessão. | Verifique se o seu registro de cliente inclui |
| O usuário negou o consentimento. | Informe o usuário. Não tente novamente automaticamente. |
| O parâmetro | Verifique se o recurso está registrado para seu cliente. |
| O valor | Use |
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.
Cliente desabilitado
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_uricomerror=access_deniede umerror_descriptiondeclient is disabled.O ponto de extremidade do token retorna
401cominvalid_cliente a mesma descrição. Isso se aplica a todos os tipos de concessão, incluindorefresh_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.