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

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 da Amazon Web Services como variáveis de ambiente ou inseri-las em linha, 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 AWS EC2 especificado na variável de ambiente AWS_CONTAINER_CREDENTIALS_RELATIVE_URI .
O endpoint padrão do AWS 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

Codifique suas credenciais em URL

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 da 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 cadeia 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

Importante

Codifique suas credenciais em URL

Atualizar credenciais

Observação

X.509

Mecanismos de autenticação

`SCRAM-SHA-256`

`SCRAM-SHA-1`

`MONGODB-CR`

`MONGODB-AWS`

`X.509`