Mecanismos de autenticação
Nesta página
Visão geral
Neste guia, você aprenderá como autenticar com o MongoDB usando cada mecanismo de autenticação disponível no MongoDB Community Edition. Os mecanismos de autenticação são processos pelos quais o driver e o servidor confirmam a identidade e estabelecem confiança para garantir a segurança.
Os mecanismos que você pode usar com a versão mais recente do MongoDB Community Edition são os seguintes:
Para autenticar usando Kerberos
ou LDAP
, consulte o guia Mecanismos de Autenticação Empresarial.
Para obter mais informações sobre como estabelecer uma conexão com seu cluster MongoDB, leia nosso Guia de Conexão.
Especificar um mecanismo de autenticação
Você pode especificar seu mecanismo de autenticação e credenciais ao se conectar ao MongoDB usando um dos seguintes:
Uma connection string
Um método de fábrica do
MongoCredential
Uma string de conexão (também conhecida como uri de conexão) especifica como se conectar e autenticar ao cluster MongoDB.
Para autenticar usando uma string de conexão, inclua suas configurações na string de conexão e passe-a para o método MongoClient.create()
para instanciar seu MongoClient
. A guia Connection String em cada seção fornece a sintaxe para autenticar utilizando uma cadeia de conexão.
Alternativamente, você pode utilizar a classe MongoCredential
para especificar seus detalhes de autenticação. A classe MongoCredential
contém métodos de fábrica estáticos que constroem instâncias contendo seu mecanismo de autenticação e credenciais. Quando você usa a classe auxiliar MongoCredential
, é necessário usar a classe MongoClientSettings.Builder
para definir as configurações de conexão ao construir o MongoClient
. A guia MongoCredential em cada seção fornece a sintaxe para autenticar utilizando um MongoCredential
.
Para obter mais informações sobre essas classes e métodos, consulte a seguinte documentação da API:
Mecanismos
Default
A configuração do mecanismo de autenticação padrão usa um dos seguintes mecanismos de autenticação, dependendo do que seu servidor MongoDB suporta:
SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR
Versões de servidor 3.6 e anteriores utilizam o MONGODB-CR
como o mecanismo padrão. Versões mais recentes do servidor usam um dos mecanismos para os quais anunciam suporte.
Os seguintes trechos de código mostram como especificar o mecanismo de autenticação, usando os seguintes placeholders:
db_username
- seu nome de usuário do banco de dados de dados MongoDBdb_password
- a senha de usuário do banco de banco de dados MongoDBhostname
- endereço de rede do seu MongoDB Server, acessível pelo seu clienteport
- número da porta do seu servidor MongoDBauthenticationDb
- Banco de dados MongoDB que contém os dados de autenticação do usuário. Se omitir este parâmetro, o driver utiliza o valor padrãoadmin
.
Selecione a aba Connection String ou MongoCredential abaixo para obter instruções e amostras de código para especificar este mecanismo de autenticação:
Para especificar o mecanismo de autenticação padrão usando uma string de conexão, omita o mecanismo. Seu código para instanciar um MongoClient
deve ser semelhante ao seguinte:
val mongoClient = MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>")
Para especificar o mecanismo de autenticação padrão usando a classe MongoCredential
, use o método createCredential()
. Seu código para instanciar um MongoClient
deve ser semelhante ao seguinte:
val credential = MongoCredential.createCredential( "<db_username>", "<authenticationDb>", "<db_password>".toCharArray() ) val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( listOf(ServerAddress("<hostname>", "<port>")) ) } .credential(credential) .build() val mongoClient = MongoClient.create(settings)
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 do Servidor MongoDB.
SCRAM-SHA-256
Observação
SCRAM-SHA-256
é o método de autenticação padrão para o MongoDB começando no MongoDB 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.
Os seguintes trechos de código mostram como especificar o mecanismo de autenticação, usando os seguintes placeholders:
db_username
- seu nome de usuário do banco de dados de dados MongoDB .db_password
- a senha do usuário do banco de banco de dados MongoDB .hostname
- endereço de rede do seu MongoDB Server, acessível pelo seu cliente.port
- número da porta do seu servidor MongoDB.authenticationDb
- Banco de dados MongoDB que contém os dados de autenticação do usuário. Se omitir este parâmetro, o driver utiliza o valor padrãoadmin
.
Selecione a aba Connection String ou MongoCredential abaixo para obter instruções e amostras de código para especificar este mecanismo de autenticação:
Para especificar o mecanismo de autenticação do SCRAM-SHA-256
utilizando uma cadeia de conexão, atribua ao parâmetro authMechanism
o valor SCRAM-SHA-256
em sua cadeia de conexão. Seu código para instanciar um MongoClient
deve se assemelhar ao seguinte:
val mongoClient = MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-256")
Para especificar o mecanismo de autenticação padrão usando a MongoCredential
classe , use o createScramSha256Credential() método. Seu código para instanciar um MongoClient
deve ser semelhante ao seguinte:
val credential = MongoCredential.createScramSha256Credential( "<db_username>", "<authenticationDb>", "<db_password>".toCharArray() ) val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( listOf(ServerAddress("<hostname>", "<port>")) ) } .credential(credential) .build() val mongoClient = MongoClient.create(settings)
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, criptografado com o algoritmo do SHA-1
, para autenticar seu usuário.
Os seguintes trechos de código mostram como especificar o mecanismo de autenticação, usando os seguintes placeholders:
db_username
- seu nome de usuário do banco de dados de dados MongoDB .db_password
- a senha do usuário do banco de banco de dados MongoDB .hostname
- endereço de rede do seu MongoDB Server, acessível pelo seu cliente.port
- número da porta do seu servidor MongoDB.authenticationDb
- Banco de dados MongoDB que contém os dados de autenticação do usuário. Se omitir este parâmetro, o driver utiliza o valor padrãoadmin
.
Selecione a aba Connection String ou MongoCredential abaixo para obter instruções e amostras de código para especificar este mecanismo de autenticação:
Para especificar o mecanismo de autenticação do SCRAM-SHA-1
utilizando uma cadeia de conexão, atribua ao parâmetro authMechanism
o valor SCRAM-SHA-1
em sua cadeia de conexão. Seu código para instanciar um MongoClient
deve se assemelhar ao seguinte:
val mongoClient = MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-1")
Para especificar o mecanismo de autenticação padrão usando a MongoCredential
classe , use o createScramSha1Credential() método. Seu código para instanciar um MongoClient
deve ser semelhante ao seguinte:
val credential = MongoCredential.createScramSha1Credential( "<db_username>", "<authenticationDb>", "<db_password>".toCharArray() ) val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( listOf(ServerAddress("<hostname>", "<port>")) ) } .credential(credential) .build() val mongoClient = MongoClient.create(settings)
MONGODB-CR
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. Esse mecanismo de autenticação começou a ficar obsoleto no MongoDB 3.6 e não é mais compatível no MongoDB 4.0.
Você não pode especificar este método explicitamente; consulte o fallback fornecido pelo mecanismo de autenticação padrão para se conectar utilizando o MONGODB-CR
.
MONGODB-AWS
Observação
O mecanismo de autenticação MONGODB-AWS está disponível para sistemas MongoDB no MongoDB Atlas.
O mecanismo de autenticação do MONGODB-AWS
utiliza suas credenciais do Amazon Web Services Identity e Access Management (AWS IAM) para autenticar o usuário. Para saber mais sobre como configurar o MongoDB Atlas, consulte o guia Configurar autenticação sem senha com funções de IAM do AWS.
Para instruir o driver a usar esse mecanismo de autenticação, você pode especificar MONGODB-AWS
como um parâmetro na cadeia de conexão ou usando o método de fábrica MongoCredential.createAwsCredential()
.
Aprenda a especificar esse mecanismo de autenticação e as várias maneiras de fornecer suas credenciais do AWS IAM nas próximas seções.
Estas seções contêm exemplos de código que usam os seguintes espaços reservados:
awsKeyId
- valor do ID da sua chave de acesso AWSawsSecretKey
- valor de sua chave de acesso secreto AWSatlasUri
- endereço de rede da sua implantação do MongoDB Atlashostname
- nome do host da sua implantação do MongoDB Atlasport
- porta de sua implantação do MongoDB AtlasawsSessionToken
- valor do token de sessão AWS
AWS SDK
Você pode usar um dos AWS SDK para Java v1 ou v2 para especificar suas credenciais. Este método oferece as seguintes funcionalidades:
Várias opções para obter credenciais
Cache de credenciais que ajuda seu aplicativo a evitar limitação de taxa
Gerenciamento de fornecedor de credencial para uso com o Serviço Elastic Kubernetes.
Para usar o AWS SDK para Java para autenticação MONGODB-AWS
, você deve executar o seguinte:
Especifique o mecanismo de autenticação
Adicione o SDK como uma dependência ao seu projeto
Forneça suas credenciais usando um dos métodos na cadeia de fornecedores de credencial
Para especificar o mecanismo de autenticação usando uma MongoCredential
, use o método de fábrica MongoCredential.createAwsCredential()
e adicione a instância MongoCredential
ao seu MongoClient
, conforme mostrado no exemplo a seguir:
val credential = MongoCredential.createAwsCredential(null, null) val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( listOf(ServerAddress("<atlasUri>")) ) } .credential(credential) .build() val mongoClient = MongoClient.create(settings)
Para especificar o mecanismo de autenticação na connection string, adicione-o como um parâmetro, conforme mostrado no exemplo a seguir:
val mongoClient = MongoClient.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS")
Para adicionar a AWS SDK como uma dependência ao seu projeto, consulte a seguinte documentação da AWS para a versão necessária:
Para o AWS SDK for Java v2, consulte a página de Configuração do guia.
Para o AWS SDK for Java v1, consulte o Guia de Primeiros passos.
Observação
Para o AWS SDK para Java v2, o driver Java testa atualmente usando a dependência software.amazon.awssdk:auth:2.18.9
.
Para o AWS SDK para Java v1, o driver Java testa atualmente usando a dependência com.amazonaws:aws-java-sdk-core:1.12.337
.
Para fornecer suas credenciais, consulte a seguinte documentação AWS para a versão que você precisa:
Para saber mais sobre a classe AWS SDK para Java v2 que o driver usa para obter as credenciais, consulte a documentação da API DefaultCredentialsProvider.
Saiba como fornecer suas credenciais a essa classe na seção Usar a cadeia de fornecedores de credenciais padrão.
Para saber mais sobre a classe AWS SDK for Java v1 que o driver usa para obter as credenciais, consulte a documentação da API DefaultAWSCredentialsProviderChain.
Saiba como fornecer suas credenciais a essa classe na seção Usar a cadeia de provedor de credenciais padrão.
Observação
Se você incluir v1 e v2 do AWS SDK para Java em seu projeto, deverá usar os métodos v2 para fornecer suas credenciais.
Especifique suas Credenciais no Ambiente
Você pode fornecer suas credenciais do AWS IAM instruindo o driver a usar o mecanismo de autenticação MONGODB-AWS
e definindo as variáveis de ambiente apropriadas.
Para usar as variáveis de ambiente para fornecer suas credenciais, você deve executar o seguinte:
Especifique o mecanismo de autenticação
Adicione as variáveis de ambiente apropriadas
Você pode especificar o mecanismo de autenticação utilizando um MongoCredential
ou na cadeia de conexão.
Para especificar o mecanismo de autenticação usando uma MongoCredential
, use o método de fábrica MongoCredential.createAwsCredential()
e adicione a instância MongoCredential
ao seu MongoClient
, conforme mostrado no exemplo a seguir:
val credential = MongoCredential.createAwsCredential(null, null) val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( listOf(ServerAddress("<atlasUri>")) ) } .credential(credential) .build() val mongoClient = MongoClient.create(settings)
Para especificar o mecanismo de autenticação na connection string, adicione-o como um parâmetro, conforme mostrado no exemplo a seguir:
val mongoClient = MongoClient.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS")
Os próximos exemplos mostram como fornecer suas credenciais configurando variáveis de ambiente para os seguintes tipos de autenticação:
Chaves de acesso programático
Credenciais do container ECS
Credenciais do container EC2
O exemplo a seguir mostra como você pode definir suas chaves de acesso programático em variáveis de ambiente usando bash
ou um shell similar:
export AWS_ACCESS_KEY_ID=<awsKeyId> export AWS_SECRET_ACCESS_KEY=<awsSecretKey> export AWS_SESSION_TOKEN=<awsSessionToken>
Omita a linha que contém AWS_SESSION_TOKEN
se não precisar de um token de sessão AWS para essa função.
Para autenticar usando credenciais de container do ECS, defina o URI relativo do ponto de extremidade do ECS em uma variável de ambiente usando bash
ou um shell semelhante, conforme mostrado no exemplo a seguir:
export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<your ECS endpoint>
Para autenticar usando credenciais de container do EC2, verifique se nenhuma das variáveis de ambiente mencionadas acima está definida. O driver obtém as credenciais do endpoint de metadados de instância IPv4 EC2 padrão.
Especifique Suas Credenciais em uma MongoCredential
Você pode fornecer suas credenciais do AWS IAM para um MongoClient
utilizando uma instância MongoCredential
. Para criar a instância do MongoCredential
para a autenticação do MONGODB-AWS
, utilize o método de fábrica createAwsCredential().
Você pode fornecer somente chaves de acesso programáticas para o método MongoCredential.createAwsCredential()
. Se você precisar fornecer credenciais de contêiner ECS ou EC2, use as instruções em Specify Your Credentials in the Environment ou Amazon Web Services SDK.
Para usar o MongoCredential
para autenticação do MONGODB-AWS
, você deve executar o seguinte:
Especifique o mecanismo de autenticação
Fornecer as credenciais
Para especificar o mecanismo de autenticação usando uma MongoCredential
, use o método de fábrica MongoCredential.createAwsCredential()
e adicione a instância MongoCredential
ao seu MongoClient
, conforme mostrado no exemplo a seguir:
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray()) val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( listOf(ServerAddress("<atlasUri>")) ) } .credential(credential) .build() val mongoClient = MongoClient.create(settings)
Se você precisar especificar um token de sessão AWS, passe para o método withMechanismProperty() como mostrado no exemplo a seguir:
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray()) .withMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>") val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( listOf(ServerAddress("<atlasUri>")) ) } .credential(credential) .build() val mongoClient = MongoClient.create(settings)
Para atualizar suas credenciais, você pode declarar uma expressão lambda do Supplier
que retorna novas credenciais como mostrado no seguinte exemplo:
val awsFreshCredentialSupplier: Supplier<AwsCredential> = Supplier { // Add your code here to fetch new credentials // Return the new credentials AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>") } val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray()) .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier) val settings = MongoClientSettings.builder() .applyToClusterSettings { builder -> builder.hosts(listOf(ServerAddress("<hostname>", "<port>"))) } .credential(credential) .build() val mongoClient = MongoClient.create(settings)
Se você precisar fornecer credenciais do Amazon Web Services IAM em uma de string conexão, poderá adicioná-la ao seu ligando MongoClientSettings
para o método applyConnectionString() método:
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray()) val connectionString = ConnectionString("mongodb://<atlasUri>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>") val settings = MongoClientSettings.builder() .applyConnectionString(connectionString) .credential(credential) .build() val mongoClient = MongoClient.create(settings)
X.509
O mecanismo de autenticação do X.509
utiliza TLS com certificados X.509 para autenticar seu usuário, identificado pelos nomes diferenciados relativos (RDNs) do seu certificado de cliente. Quando você especifica o mecanismo de autenticação X.509
, o servidor autentica a conexão utilizando o nome do assunto do certificado do cliente.
Os seguintes trechos de código mostram como especificar o mecanismo de autenticação, usando os seguintes placeholders:
hostname
- endereço de rede do seu MongoDB Server, acessível pelo seu cliente.port
- número da porta do seu servidor MongoDB.authenticationDb
- Banco de dados MongoDB que contém os dados de autenticação do usuário. Se omitir este parâmetro, o driver utiliza o valor padrãoadmin
.
Selecione a aba Connection String ou MongoCredential abaixo para obter instruções e amostras de código para especificar este mecanismo de autenticação:
Para especificar o mecanismo de autenticação X.509
utilizando uma string de conexão, atribua ao parâmetro authMechanism
o valor MONGODB-X509
e habilite TLS atribuindo ao parâmetro tls
um valor true
. Seu código para instanciar um MongoClient
deve se assemelhar ao seguinte:
val mongoClient = MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-X509&tls=true")
Para especificar o X.509
mecanismo de autenticação usando a MongoCredential
classe , use o createMongoX509Credential() método. Além disso, habilite o TLS chamando o método applyToSslSettings() método e definindo a enabled
propriedade como true
no SslSettings.Builder bloco. Seu código para instanciar um MongoClient
deve ser semelhante ao seguinte:
val credential = MongoCredential.createMongoX509Credential() val settings = MongoClientSettings.builder() .applyToClusterSettings { builder -> builder.hosts(listOf( ServerAddress("<hostname>", "<port>")) ) } .applyToSslSettings { builder -> builder.enabled(true) } .credential(credential) .build() val mongoClient = MongoClient.create(settings)
Para obter informações adicionais sobre como configurar seu aplicação para usar certificados e opções TLS/SSL, consulte nosso guia TLS/SSL.