Manage Database Users Using SCRAM Authentication
On this page
The Kubernetes Operator supports managing database users using SCRAM authentication on MongoDB deployments.
Considerations
Supported SCRAM Implementations
When you specify SCRAM
as the authentication mechanism, the
implementation of SCRAM used depends upon:
The version of MongoDB and
If the database is the Application Database or another database.
MongoDB Version | Database | SCRAM Implementation |
---|---|---|
3.6 or earlier | Any except Application Database | SCRAM-SHA-1 |
4.0 or later | Any except Application Database | SCRAM-SHA-256 |
Any | Application Database | SCRAM-SHA-1 |
Supported Authentication Mechanisms
The Kubernetes Operator supports SCRAM, LDAP, and X.509 authentication mechanisms in deployments it creates. In an Kubernetes Operator-created deployment, you cannot use Ops Manager to:
Configure other authentication mechanisms for deployments.
Manage users not using SCRAM, LDAP, or X.509 authentication.
After enabling SCRAM authentication, you can add SCRAM users using the Ops Manager interface or by configuring the users in the CustomResourceDefinition based on the MongoDB User Resource Specification.
Prerequisites
Before managing database users, you must deploy a standalone, replica set, or sharded cluster.
For multi-Kubernetes cluster MongoDB deployments, you must deploy replica sets. See Deploy Multiple Clusters.
Add a Database User
Important
You cannot assign the same database user to more than one MongoDB standalone, replica set, or sharded cluster. This includes database users with admin roles.
Create User Secret
Configure kubectl
to default to your namespace.
If you have not already, run the following command to execute all
kubectl
commands in the namespace you created.
Note
If you are deploying an Ops Manager resource in a multi-Kubernetes cluster MongoDB deployment:
Set the
context
to the name of the central cluster, such as:kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME"
.Set the
--namespace
to the same scope that you used for your multi-Kubernetes cluster MongoDB deployment, such as:kubectl config --namespace "mongodb"
.
kubectl config set-context $(kubectl config current-context) --namespace=<metadata.namespace>
Copy the following example secret.
You can choose to use a cleartext password:
1 2 apiVersion: v1 3 kind: Secret 4 metadata: 5 name: <mms-user-1-password> 6 # corresponds to user.spec.passwordSecretKeyRef.name 7 type: Opaque 8 stringData: 9 password: <my-plain-text-password> 10 # corresponds to user.spec.passwordSecretKeyRef.key 11 data: 12 password: <base-64-encoded-password> 13 # corresponds to user.spec.passwordSecretKeyRef.key 14 ...
or you can choose to use a Base64-encoded password:
1 2 apiVersion: v1 3 kind: Secret 4 metadata: 5 name: <mms-user-1-password> 6 # corresponds to user.spec.passwordSecretKeyRef.name 7 type: Opaque 8 stringData: 9 password: <my-plain-text-password> 10 # corresponds to user.spec.passwordSecretKeyRef.key 11 data: 12 password: <base-64-encoded-password> 13 # corresponds to user.spec.passwordSecretKeyRef.key 14 ...
Note
Make sure to copy the desired password configuration. Plaintext
passwords use stringData.password
and Base64-encoded
passwords use data.password
Create a new User Secret YAML file.
Open your preferred text editor.
Paste this User Secret into a new text file.
If you're using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.
To learn about your options for secret storage, see Configure Secret Storage.
Change the highlighted lines.
Use the following table to guide you through changing the highlighted lines in the Secret:
Key | Type | Description | Example |
---|---|---|---|
metadata.name | string | Name of the database password secret. Resource names must be 44 characters or less. | mms-scram-user-1-password |
stringData.password | string | Plaintext password for the desired user. Use this option and value or | <my-plain-text-password> |
data.password | string | Base64-encoded password for the desired user. Use this option and value or You must encode your password into Base64 yourself then paste the resulting value with this option. There are tools for most every platform and multiple web-based tools as well. | <my-base64-encoded-password> |
Create MongoDBUser
Copy the following example MongoDBUser.
apiVersion: mongodb.com/v1 kind: MongoDBUser metadata: name: <mms-scram-user-1> spec: passwordSecretKeyRef: name: <mms-user-1-password> # Match to metadata.name of the User Secret key: password username: "<mms-scram-user-1>" db: "admin" # mongodbResourceRef: name: "<my-replica-set>" # Match to MongoDB resource using authenticaiton roles: - db: "admin" name: "clusterAdmin" - db: "admin" name: "userAdminAnyDatabase" - db: "admin" name: "readWrite" - db: "admin" name: "userAdminAnyDatabase" ...
Change the highlighted lines.
Use the following table to guide you through changing the highlighted lines in the MongoDB User Resource Specification:
Key | Type | Description | Example |
---|---|---|---|
metadata.name | string | Name of the database user resource. Resource names must be 44 characters or less. | mms-scram-user-1 |
spec.username | string | Name of the database user. | mms-scram-user-1 |
spec.passwordSecretKeyRef.name | string | metadata.name value of the secret that stores the
user's password. | my-resource |
spec.mongodbResourceRef.name | string | Name of the MongoDB resource
this user is associated with. | my-resource |
spec.roles.db | string | Database on which the role can act. | admin |
spec.roles.name | string | Name of the role to grant the database
user. The role name can be any
built-in MongoDB role or
custom role that
exists in Cloud Manager or Ops Manager. | readWriteAnyDatabase |
Create the user.
Invoke the following Kubernetes command to create your database user:
kubectl apply -f <database-user-conf>.yaml
When you create a new MongoDB database user, Kubernetes Operator automatically creates a new Kubernetes secret. The Kubernetes secret contains the following information about the new database user:
username
: Username for the database userpassword
: Password for the database userconnectionString.standard
: Standard connection string that can connect you to the database as this database user.connectionString.standardSrv
: DNS seed list connection string that can connect you to the database as this database user.
Note
Alternatively, you can specify an optional
spec.connectionStringSecretName
field in the
MongoDB User Resource Specification to specify
the name of the connection string secret that the
Kubernetes Operator creates.
You can use these credentials to Connect to a MongoDB Database Resource from Inside Kubernetes.
Delete a Database User
To delete a database user, pass the metadata.name
from the user
MongoDBUser to the following command:
kubectl delete mdbu <metadata.name>
Change Authentication Mechanism
To change your user authenication mechanism to SCRAM:
Disable authentication.
Under
spec.security.authentication
, changeenabled
tofalse
.spec: security: authentication: enabled : false Reapply the user's resource definition.
Wait for the MongoDBResource to reach the
running
state.Enable SCRAM authentication.
Under
spec.security.authentication
, changeenabled
totrue
and setspec.security.authentication.modes
to `` ["SCRAM"]``.spec: security: authentication: enabled : true modes: ["SCRAM"] Reapply the MongoDBUser resource.
Wait for the MongoDBResource to reach the
running
state.