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 no MongoDB Atlas.

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.

Você pode armazenar suas credenciais do Amazon Web Services como variáveis de ambiente ou inseri-las embutidas, como nos exemplos abaixo. O driver verifica suas credenciais na seguinte ordem:

Valores fornecidos em um objeto MongoCredential ou na connection string fornecida.
Suas variáveis de ambiente. (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e opcionalmente AWS_SESSION_TOKEN)
O endpoint Amazon Web Services EC2 especificado na variável de ambiente do AWS_CONTAINER_CREDENTIALS_RELATIVE_URI.
O endpoint padrão Amazon Web Services EC2. Para obter mais informações, consulte Funções de IAM para tarefas

Os seguintes trechos de código mostram como especificar o mecanismo de autenticação, usando os seguintes placeholders:

awsKeyId - valor do seu AWS_ACCESS_KEY_ID.
awsSecretKey - valor do seu AWS_SECRET_ACCESS_KEY.
atlasUri - endereço de rede da sua instância do MongoDB Atlas .
awsSessionToken - valor do seu AWS_SESSION_TOKEN. (opcional)

Importante

URL-codifique suas credenciais

Certifique-se de codificar suas credenciais para evitar que a barra invertida ou outros caracteres causem erros de análise. O seguinte exemplo de código mostra como codificar para URL uma string de exemplo, representada pelo espaço reservado fieldValue:

String encodedField = java.net.URLEncoder.encode("<fieldValue>".toString(), "ISO-8859-1");

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 MONGODB-AWS utilizando uma cadeia de conexão, atribua ao parâmetro authMechanism o valor "MONGODB-AWS" em sua cadeia de conexão. Seu código para instanciar um MongoClient deve ser semelhante a este:

MongoClient mongoClient = MongoClients.create("mongodb://<awsKeyId>:<awsSecretKey>@<atlasUri>?authMechanism=MONGODB-AWS");

Se você precisar especificar um token de sessão Amazon Web Services , inclua-o no parâmetro authMechanismProperties da seguinte forma, usando o formato AWS_SESSION_TOKEN:<awsSessionToken>. Seu código para instanciar um MongoClient com um token de sessão deve ter a seguinte aparência:

MongoClient mongoClient = MongoClients.create("mongodb://<awsKeyId>:<awsSecretKey>@<atlasUri>?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>");

Para especificar o MONGODB-AWS mecanismo de autenticação utilizando a MongoCredential classe , utilize o createAwsCredential() método. Seu código para instanciar um MongoClient deve ser semelhante a este:

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 do Amazon Web Services, poderá adicioná-lo usando uma das seguintes opções:

Especifique seu token de sessão do Amazon Web Services em uma connection string.

Se você preferir passar o token de sessão do Amazon Web Services na connection string ao lado do seu MongoCredential, especifique seu mecanismo de autenticação no parâmetro authMechanism e seu token de sessão no parâmetro authMechanismProperties. Em seguida, adicione-o ao seu MongoClientSettings chamando o método applyConnectionString() da seguinte forma:

MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray());
ConnectionString connectionString = new ConnectionString("mongodb://<atlasUri>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>");
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(connectionString)
        .credential(credential)
        .build());

Especifique seu token de sessão do Amazon Web Services em uma MongoCredential.

Você pode incluir seu token de sessão do Amazon Web Services em sua MongoCredential instância especificando-o em uma chamada para o método withMechanismProperty() método como mostrado abaixo:

MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray()).withMechanismProperty("AWS_SESSION_TOKEN",  "<awsSessionToken>");
ConnectionString connectionString = new ConnectionString("mongodb://<atlasUri>/?authMechanism=MONGODB-AWS");
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(connectionString)
        .credential(credential)
        .build());

Especifique seu token de sessão do Amazon Web Services em uma variável de ambiente.
No ambiente de execução do cliente, defina uma variável de ambiente chamada AWS_SESSION_TOKEN e atribua seu token a ela. O valor é automaticamente coletado pelo seu MongoClient quando você especifica o mecanismo de autenticação do MONGODB-AWS .

Atualizar credenciais

O driver suporta a atualização de credenciais para casos como assumir funções ou usar o Elastic Kubernetes Service.

Supplier<AwsCredential> awsFreshCredentialSupplier = () -> {
    // Add your code to fetch new credentials, such as assuming a role using the AWS SDK.
    
    // Ensure you return the temporary 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>", 27017))))
        .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