Mecanismos de autenticação
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-AWS
e 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:
SCRAM-SHA-256
SCRAM-SHA-1
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
na string de conexão 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("<username>"); const password = encodeURIComponent("<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 desafio-resposta (CR) e salgados (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 o authMechanism
para o valor SCRAM-SHA-256
na string 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("<username>"); const password = encodeURIComponent("<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 este mecanismo de autenticação configurando o parâmetro authMechanism
para o valor SCRAM-SHA-1
na string de conexão como mostrado no seguinte código de amostra.
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("<username>"); const password = encodeURIComponent("<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 string 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("<username>"); const password = encodeURIComponent("<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:
Connection string
Variáveis de ambiente
Arquivo de token de identidade da Web
Desfecho AWS ECS especificado em
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
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 string de conexão:
Configure o parâmetro
authMechanism
paraMONGODB-X509
Configure o parâmetro
tls
paratrue
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);
Opções TLS/SSL
A tabela a seguir descreve cada uma das opções de TLS/SSL que pode ser passada como um parâmetro no URI de conexão.
Nome do Parâmetro | Tipo | Valor padrão | Descrição |
---|---|---|---|
tls | booleano | false | Especifica se as conexões TLS/SSL devem ser usadas. |
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 driver permite que um certificado inválido seja usado para se conectar. |
tlsAllowInvalidHostnames | booleano | false | Especifica se o driver deve permitir uma incompatibilidade entre o nome de host do servidor e o nome de host do certificado TLS. |