Menu Docs
Página inicial do Docs
/
Línguas
/
Javascript
/
Controlador Node.js
/
Fundamentals
/
Autenticação

Mecanismos de autenticação

Nesta página

  • DEFAULT
  • SCRAM-SHA-256
  • SCRAM-SHA-1
  • MONGODB-CR
  • MONGODB-AWS
  • X.509
  • Opções de TLS

Neste guia, você pode encontrar código de exemplo para conexão com o MongoDB com cada mecanismo de autenticação disponível no MongoDB Community Edition: DEFAULT, SCRAM-SHA-256, SCRAM-SHA-1, MONGODB-CR, MONGODB-AWSe X.509.

DEFAULT

O mecanismo de autenticação do DEFAULT é uma configuração de contingência que instrui o driver a negociar o primeiro mecanismo de autenticação suportado pelo servidor na seguinte ordem de preferência:

  1. SCRAM-SHA-256

  2. SCRAM-SHA-1

  3. MONGODB-CR

Se a opção DEFAULT for especificada, o driver primeiro tentará autenticar usando SCRAM-SHA-256. Se a versão da instância MongoDB não suportar este mecanismo, o driver tentará autenticar utilizando o SCRAM-SHA-1. Se a instância também não oferecer suporte a esse mecanismo, o driver tentará se autenticar usando MONGODB-CR.

Você pode especificar esse mecanismo de autenticação definindo o parâmetro authMechanism como DEFAULT naconnection string ou omitindo o parâmetro, já que é o valor-padrão. Inclua também seu nome de usuário e senha, conforme mostrado no código abaixo.

Importante

Sempre codifique em URI o nome de usuário e a senha usando o encodeURIComponent método para garantir que sejam analisados corretamente.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const username = encodeURIComponent("<db_username>");
const password = encodeURIComponent("<db_password>");
const clusterUrl = "<MongoDB cluster url>";
const authMechanism = "DEFAULT";
// Replace the following with your MongoDB deployment's connection string.
const uri =
  `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}`;
// Create a new MongoClient
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
  try {
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

Para obter mais informações sobre os mecanismos de autenticação de resposta e desafio (CR) e mecanismos de autenticação de resposta e desafio baseada em senha (SCRAM) que o MongoDB suporta, consulte a seção SCRAM do manual.

SCRAM-SHA-256

Observação

SCRAM-SHA-256 é o método de autenticação padrão para MongoDB a partir da versão 4.0

SCRAM-SHA-256 é um mecanismo de autenticação de desafio-resposta (SCRAM) que usa seu nome de usuário e senha, criptografados com o algoritmo SHA-256 para autenticar seu usuário.

Você pode especificar esse mecanismo de autenticação definindo authMechanism como o valor SCRAM-SHA-256 na connection string , conforme mostrado no código de exemplo a seguir.

Importante

Sempre codifique em URI o nome de usuário e a senha usando o encodeURIComponent método para garantir que sejam analisados corretamente.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const username = encodeURIComponent("<db_username>");
const password = encodeURIComponent("<db_password>");
const clusterUrl = "<MongoDB cluster url>";
const authMechanism = "SCRAM-SHA-256";
// Replace the following with your MongoDB deployment's connection string.
const uri =
  `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}`;
// Create a new MongoClient
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
  try {
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

SCRAM-SHA-1

Observação

SCRAM-SHA-1 é o método de autenticação padrão para as versões 3.0, 3.2, 3.4 e 3.6. do MongoDB.

SCRAM-SHA-1 é um mecanismo de desafio-resposta (SCRAM) que utiliza seu nome de usuário e senha, codificado com o algoritmo do SHA-1 para autenticar o usuário.

Você pode especificar esse mecanismo de autenticação definindo o parâmetro authMechanism com o valor SCRAM-SHA-1 na cadeia de conexão, conforme mostrado no código de exemplo a seguir.

Importante

Sempre codifique em URI o nome de usuário e a senha usando o encodeURIComponent método para garantir que sejam analisados corretamente.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const username = encodeURIComponent("<db_username>");
const password = encodeURIComponent("<db_password>");
const clusterUrl = "<MongoDB cluster url>";
const authMechanism = "SCRAM-SHA-1";
// Replace the following with your MongoDB deployment's connection string.
const uri =
  `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}`;
// Create a new MongoClient
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
  try {
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

MONGODB-CR

Aviso

O MONGODB-CR foi preterido a partir do MongoDB 3.6 e não é mais compatível com o MongoDB 4.0

MONGODB-CR é um mecanismo de autenticação de resposta e desafio que usa seu nome de usuário e senha para autenticar seu usuário.

Você pode especificar essa opção definindo o parâmetro authMechanism com o valor MONGODB-CR na connection string , conforme mostrado no código de exemplo a seguir.

Importante

Sempre codifique em URI o nome de usuário e a senha usando o encodeURIComponent método para garantir que sejam analisados corretamente.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const username = encodeURIComponent("<db_username>");
const password = encodeURIComponent("<db_password>");
const clusterUrl = "<MongoDB cluster url>";
// Replace the following with your MongoDB deployment's connection string.
const uri =
  `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}&tls=true&tlsCertificateKeyFile=${clientPEMFile}`;
// Create a new MongoClient
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
  try {
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

Importante

Se você atualizou o esquema de autenticação de MONGODB-CR para SCRAM, quaisquer solicitações de autenticação de usuário do MONGODB-CR falharão.

MONGODB-AWS

Observação

O mecanismo de autenticação MONGODB-AWS está disponível somente nas versões 4.4 e mais recentes do MongoDB.

O mecanismo de autenticação do MONGODB-AWS utiliza suas credenciais do Amazon Web Services Identity and Access Management (AWS IAM) para autenticar o usuário. Se você ainda não tiver a biblioteca de assinaturas da AWS, use o seguinte comando npm para instalá-la:

npm install aws4

Para se conectar a uma instância do MongoDB com a autenticação MONGODB-AWS habilitada, especifique o mecanismo de autenticação MONGODB-AWS.

O driver verifica suas credenciais nas seguintes fontes em ordem:

  1. Connection string

  2. Variáveis de ambiente

  3. Arquivo de token de identidade da Web

  4. Desfecho AWS ECS especificado em AWS_CONTAINER_CREDENTIALS_RELATIVE_URI

  5. Endpoint AWS EC2 . Para obter mais informações, consulte Funções do IAM para tarefas.

Importante

O driver só lê as credenciais do primeiro método que detecta na ordem dada pela lista anterior. Por exemplo, se você especificar suas credenciais da AWS na cadeia de conexão, o driver ignora qualquer credenciais que você especificou em variáveis de ambiente.

Para se conectar à sua instância do MongoDB com uma cadeia de conexão, passe suas credenciais do AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY para o driver quando você tenta se conectar. Se o seu login AWS requer um token de sessão, inclua também seu AWS_SESSION_TOKEN.

O código a seguir mostra um exemplo de especificação do mecanismo de autenticação MONGODB-AWS e das credenciais com uma cadeia de conexão:

Importante

Sempre URI codificar o nome de usuário e o caminho do arquivo de certificado usando o método encodeURIComponent para garantir que eles sejam analisados corretamente.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const accessKeyId = encodeURIComponent("<AWS_ACCESS_KEY_ID>");
const secretAccessKey = encodeURIComponent("<AWS_SECRET_ACCESS_KEY>");
const clusterUrl = "<MongoDB cluster url>";
const authMechanism = "MONGODB-AWS";
let uri =
  `mongodb+srv://${accessKeyId}:${secretAccessKey}@${clusterUrl}/?authSource=%24external&authMechanism=${authMechanism}`;
  
// Uncomment the following lines if your AWS authentication setup requires a session token.
// const sessionToken = encodeURIComponent("<AWS_SESSION_TOKEN>");
// uri = uri.concat(`&authMechanismProperties=AWS_SESSION_TOKEN:${sessionToken}`);
// Create a new MongoClient.
const client = new MongoClient(uri);
async function run() {
  try {
    // Establish and verify connection.
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server.");
  } finally {
    // Ensure that the client closes when it finishes/errors.
    await client.close();
  }
}
run().catch(console.dir);

Para autenticar em sua instância do MongoDB usando as credenciais do Amazon Web Services armazenadas em variáveis de ambiente, defina as seguintes variáveis usando um shell:

export AWS_ACCESS_KEY_ID=<awsKeyId>
export AWS_SECRET_ACCESS_KEY=<awsSecretKey>
export AWS_SESSION_TOKEN=<awsSessionToken>

Observação

Omita a linha que contém AWS_SESSION_TOKEN se não precisar de um token de sessão AWS para essa função.

Depois de definir as variáveis de ambiente anteriores, especifique o mecanismo de autenticação MONGODB-AWS em sua connection string, conforme mostrado no exemplo a seguir:

const { MongoClient } = require("mongodb");
// Remember to specify your AWS credentials in environment variables.
const clusterUrl = "<MongoDB deployment url>";
const authMechanism = "MONGODB-AWS";
let uri =
  `mongodb+srv://${clusterUrl}/?authSource=%24external&authMechanism=${authMechanism}`;
// Create a new MongoClient.
const client = new MongoClient(uri);
async function run() {
  try {
    // Establish and verify connection.
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server.");
  } finally {
    // Ensure that the client closes when it finishes/errors.
    await client.close();
  }
}
run().catch(console.dir);

Você pode usar o token OpenID Connect (OIDC) obtido de um fornecedor de identidade da Web para autenticar no Amazon Elastic Kubernetes Service (EKS) ou em outros serviços.

Para autenticar com seu token OIDC, você deve primeiro instalar @aws-sdk/credential-providers. Você pode instalar esta dependência utilizando o seguinte comando npm :

npm install @aws-sdk/credential-providers

Em seguida, crie um arquivo que contenha seu token OIDC. Em seguida, defina o caminho absoluto para este arquivo em uma variável de ambiente usando uma shell como mostrado no exemplo a seguir:

export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file containing your OIDC token>

Depois de definir a variável de ambiente anterior, especifique o mecanismo de autenticação MONGODB-AWS em sua connection string, conforme mostrado no exemplo a seguir:

const { MongoClient } = require("mongodb");
// Remember to specify your AWS credentials in environment variables.
const clusterUrl = "<MongoDB deployment url>";
const authMechanism = "MONGODB-AWS";
let uri =
  `mongodb+srv://${clusterUrl}/?authSource=%24external&authMechanism=${authMechanism}`;
// Create a new MongoClient.
const client = new MongoClient(uri);
async function run() {
  try {
    // Establish and verify connection.
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server.");
  } finally {
    // Ensure that the client closes when it finishes/errors.
    await client.close();
  }
}
run().catch(console.dir);

Importante

Recuperação de credenciais AWS

A partir da versão 4,11, quando você instala a dependência opcional do aws-sdk/credential-providers, o driver utiliza o AWS SDK para recuperar credenciais do ambiente. Como resultado, se você tiver um arquivo de credenciais AWS compartilhado ou arquivo de configuração, o driver utilizará essas credenciais por padrão.

Você pode substituir esse comportamento executando uma das seguintes ações:

  • Configure a variável AWS_SHARED_CREDENTIALS_FILE em seu shell para apontar para seu arquivo de credenciais.

  • Configure a variável de ambiente equivalente em seu aplicativo para apontar para seu arquivo de credenciais.

  • Crie um perfil AWS para suas credenciais MongoDB e defina a variável de ambiente do AWS_PROFILE para este nome de perfil.

X.509

Observação

O mecanismo de autenticação X.509 só está disponível nas versões 2.6 e posterior do MongoDB.

O mecanismo de autenticação do X.509 utiliza TLS com certificados X.509 para autenticar recuperando o nome diferenciado (DN) do certificado do cliente.

Você pode especificar esse mecanismo de autenticação definindo os seguintes parâmetros da connection string:

  • Configure o parâmetro authMechanism para MONGODB-X509

  • Configure o parâmetro tls para true

Passe o local do seu arquivo de certificado do cliente como o valor de tlsCertificateKeyFile como um parâmetro do URI de conexão.

Importante

Sempre codifique em URI o caminho do arquivo de certificado usando o método encodeURIComponent para garantir que ele seja analisado corretamente.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const clusterUrl = "<MongoDB cluster url>";
const clientPEMFile = encodeURIComponent("<path to the client pem certificate file>");
const authMechanism = "MONGODB-X509";
// Replace the following with your MongoDB deployment's connection string.
const uri =
  `mongodb+srv://${clusterUrl}/?authMechanism=${authMechanism}&tls=true&tlsCertificateKeyFile=${clientPEMFile}`;
// Create a new MongoClient
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
  try {
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

Dica

Para saber mais sobre como habilitar o TLS em uma conexão, consulte Habilitar TLS em uma conexão.

Opções de TLS

A tabela a seguir descreve as opções de TLS que você pode definir em um URI de conexão.

Nome do Parâmetro
Tipo
Valor padrão
Descrição
tls
booleano
false
Especifica se deseja habilitar o TLS na conexão.
tlsInsecure
booleano
false
Especifica se permite certificados inválidos e nomes de host incompatíveis. Quando definido como true, isso equivale a definir tlsAllowInvalidCertificates e tlsAllowInvalidHostnames como true.
tlsCAFile
string
Caminho para o arquivo que contém uma única autoridade de certificação confiável ou um pacote de autoridades de certificação confiáveis usadas em uma conexão TLS.
tlsCertificateKeyFile
string
Caminho para o arquivo de certificado do cliente ou o arquivo de chave privada do cliente. Se ambos forem necessários, os dois devem ser concatenados em um único arquivo.
tlsCertificateKeyFilePassword
buffer ou string
String ou buffer que contém a senha para descriptografar a chave privada do cliente.
tlsAllowInvalidCertificates
booleano
false
Especifica se o motorista permite que um certificado inválido seja usado para se conectar.
tlsAllowInvalidHostnames
booleano
false
Especifica se o driver gera um erro quando há uma incompatibilidade entre o nome de host do servidor e o nome do host do certificado TLS.

Voltar

Autenticação