Mecanismos de autenticação

Nesta página

Visão geral

Especificar um mecanismo de autenticação
Mecanismos
Default
SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR
MONGODB-AWS
X.509

Esta versão da documentação foi arquivada e não é mais suportada. Consulte a documentação atual do para saber como atualizar sua versão do driver Java.

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 a implantação do MongoDB 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:

Default
SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR
MONGODB-AWS
X.509

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 connection string (também conhecida como uri de conexão) especifica como se conectar e autenticar ao cluster MongoDB.

Para autenticar usando uma cadeia de conexão, inclua suas configurações na cadeia de conexão e passe-a para o método MongoClients.create() para instanciar seu MongoClient. Selecione a aba Connection String para visualizar 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. Selecione a aba MongoCredential para visualizar 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 sua versão do 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 MongoDB 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:

username - seu nome de usuário MongoDB
password - a senha de usuário do MongoDB
hostname - endereço de rede da sua MongoDB deployment, acessível pelo seu cliente
port - número da porta da sua implantação do 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ão admin.

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 cadeia de conexão, omita o mecanismo. Seu código para instanciar um MongoClient deve ser semelhante a este:

MongoClient mongoClient = MongoClients.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 ter a seguinte aparência:

MongoCredential credential = MongoCredential.createCredential("<db_username>", "<authenticationDb>", "<db_password>");
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

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

`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:

username - seu nome de usuário MongoDB.
password - a senha do usuário MongoDB.
hostname - endereço de rede da sua implantação do MongoDB, acessível pelo seu cliente.
port - número da porta da sua implantação do 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ão admin.

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 ser semelhante a este:

MongoClient mongoClient = MongoClients.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 a este:

MongoCredential credential = MongoCredential.createScramSha256Credential("<db_username>", "<authenticationDb>", "<db_password>");
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

`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:

username - seu nome de usuário MongoDB.
password - a senha do usuário MongoDB.
hostname - endereço de rede da sua implantação do MongoDB, acessível pelo seu cliente.
port - número da porta da sua implantação do 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ão admin.

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 ser semelhante a este:

MongoClient mongoClient = MongoClients.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 a este:

MongoCredential credential = MongoCredential.createScramSha1Credential("<db_username>", "<authenticationDb>", "<db_password>");
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

`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 AWS
awsSecretKey - valor de sua chave de acesso secreto AWS
atlasUri - endereço de rede da sua implantação do MongoDB Atlas
hostname - nome do host da sua implantação do MongoDB Atlas
port - porta de sua implantação do MongoDB Atlas
awsSessionToken - valor do token de sessão AWS

AWS SDK para Java

Novidades na versão v4.8.

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

Importante

Este método de fornecer credenciais do MONGODB-AWS está disponível somente no MongoDB Java Driver v4.8 e posterior.

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:

MongoCredential credential = MongoCredential.createAwsCredential(null, null);
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

Para especificar o mecanismo de autenticação na connection string, adicione-o como um parâmetro, conforme mostrado no exemplo a seguir:

MongoClient mongoClient = MongoClients.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.

MongoCredential credential = MongoCredential.createAwsCredential(null, null);
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

Para especificar o mecanismo de autenticação na connection string, adicione-o como um parâmetro, conforme mostrado no exemplo a seguir:

MongoClient mongoClient = MongoClients.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
Fornecedor de identidade web
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.

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

Importante

Seu projeto deve incluir v1 ou v2 do AWS SDK como uma dependência para autenticar usando um fornecedor de identidade da Web.

Para usar um fornecedor de identidade web, crie um arquivo que contenha seu token OIDC. Em seguida, use bash ou um shell semelhante para definir uma variável de ambiente para o caminho absoluto para esse arquivo, conforme mostrado no exemplo a seguir:

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

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 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 Java.

Para usar o MongoCredential para autenticação do MONGODB-AWS, você deve executar o seguinte:

Especifique o mecanismo de autenticação
Fornecer as credenciais

MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray());
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

Se você precisar especificar um token de sessão AWS, passe para o método withMechanismProperty() como mostrado no exemplo a seguir:

MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray()).withMechanismProperty("AWS_SESSION_TOKEN",  "<awsSessionToken>");
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

Para atualizar suas credenciais, você pode declarar uma expressão lambda do Supplier que retorna novas credenciais como mostrado no seguinte exemplo:

Supplier<AwsCredential> awsFreshCredentialSupplier = () -> {
    // Add your code here to fetch new credentials here
    // Return the new credentials
    return new AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>");
};
MongoCredential credential = MongoCredential.createAwsCredential(null, null)
        .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier);
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
            builder.hosts(Collections.singletonList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

Observação

Se você precisar fornecer credenciais do AWS IAM em uma string de conexão, consulte uma versão anterior da documentação do driver MONGODB-AWS.

`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 da sua implantação do MongoDB, acessível pelo seu cliente.
port - número da porta da sua implantação do 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ão admin.

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 cadeia 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 ter a seguinte aparência:

MongoClient mongoClient = MongoClients.create("mongodb://<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 a este:

MongoCredential credential = MongoCredential.createMongoX509Credential();
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
            builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .applyToSslSettings(builder ->
            builder.enabled(true);
            )
        .credential(credential)
        .build());

Para obter informações adicionais sobre como configurar seu aplicativo para usar certificados, bem como opções TLS/SSL, consulte nosso guia TLS/SSL.

Voltar

Conecte-se ao MongoDB usando uma fonte de dados JNDI

Mecanismos de autenticação empresarial

Mecanismos de autenticação.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Visão geral

Especificar um mecanismo de autenticação

Mecanismos

Default

SCRAM-SHA-256

Observação

SCRAM-SHA-1

Observação

MONGODB-CR

MONGODB-AWS

Observação

AWS SDK para Java

Importante

Observação

Observação

Especifique suas Credenciais no Ambiente

Importante

Especifique Suas Credenciais em uma MongoCredential

Observação

X.509

Mecanismos de autenticação

`SCRAM-SHA-256`

`SCRAM-SHA-1`

`MONGODB-CR`

`MONGODB-AWS`

`X.509`