Enterprise Authentication Mechanisms

Example

This example specifies the authentication mechanism using the following placeholders:

• Kerberos principal: Your Kerberos principal. A sample username is myuser@KERBEROS.EXAMPLE.COM.

• password: Your Kerberos user's password. You can also store your password in a keytab file to avoid exposing your password in your code.

• connection uri: Your connection string URI.

The following code shows how you can define a Credential struct to authenticate to Kerberos and create a client with your authentication preferences:

credential := options.Credential{
        AuthMechanism: "GSSAPI",
        Username:      "<Kerberos principal>",
        Password:      "<password>",
        PasswordSet:   true,
}
uri := "<connection uri>"
clientOpts := options.Client().ApplyURI(uri).SetAuth(credential)
client, err := mongo.Connect(clientOpts)

You don't need to define a password or the PasswordSet field in your Credential struct if you store authentication keys in keytab files. You can initialize a credential cache for authenticating the Kerberos principal using the kinit binary. To learn more about the kinit binary, see the Oracle documentation.

The following command shows how you can invoke a credential cache for a sample username:

kinit myuser@KERBEROS.EXAMPLE.COM

You can alternatively authenticate using a connection string URI, specifying your URL-encoded Kerberos principal, password, and hostname, the network address of your MongoDB server:

uri := "mongodb://<Kerberos principal>:<password>@<hostname>/?authMechanism=GSSAPI"

Set Custom SERVICE_NAME and SERVICE_REALM Fields

You can specify additional properties with your authentication mechanism using the AuthMechanismProperties field in the Credential struct. The default service name for Kerberos is "mongodb". The following code shows how you can set custom values for the SERVICE_NAME and SERVICE_REALM fields when defining a Credential struct:

credential := options.Credential{
        AuthMechanism: "GSSAPI",
        Username:      "<Kerberos principal>",
        Password:      "<password>",
        AuthMechanismProperties: map[string]string{
                "SERVICE_REALM": "<Kerberos service realm>",
                "SERVICE_NAME":  "<service name>",
        },
}

For additional properties, see the Server manual entry on authentication properties.

Example

This example specifies the authentication mechanism using the following placeholders:

• LDAP username: Your LDAP username

• password: Your LDAP password

• connection uri: Your connection string URI

The following code shows how you can define a Credential struct to authenticate to LDAP and create a client with your authentication preferences:

credential := options.Credential{
        AuthMechanism: "PLAIN",
        Username:      "<LDAP username>",
        Password:      "<password>",
     }
uri := "<connection uri>"
clientOpts := options.Client().ApplyURI(uri).SetAuth(credential)
client, err := mongo.Connect(clientOpts)

You can alternatively authenticate using a connection string URI, specifying your LDAP username, password, and hostname, the network address of your MongoDB server:

uri := "mongodb://<LDAP username>:<password>@<hostname>/?authMechanism=PLAIN"

Azure IMDS

If your application runs on an Azure VM, or otherwise uses the Azure Instance Metadata Service (IMDS), you can authenticate to MongoDB by using the Go driver's built-in Azure support.

You can configure OIDC for Azure IMDS in the following ways:

• By creating a Credential struct and passing it to the SetAuth() method when creating a client

• By setting parameters in your connection string

props := map[string]string{
       "ENVIRONMENT":    "azure",
       "TOKEN_RESOURCE": "<audience>",
}

uri := "mongodb://<hostname>:<port>"
props := map[string]string{
	"ENVIRONMENT":    "azure",
	"TOKEN_RESOURCE": "<audience>",
}
opts := options.Client().ApplyURI(uri)
opts.SetAuth(
	options.Credential{
		Username:                "<Azure client ID or application ID>",
		AuthMechanism:           "MONGODB-OIDC",
		AuthMechanismProperties: props,
	},
)
client, err := mongo.Connect(opts)
if err != nil {
	panic(err)
}

uri := "mongodb://<hostname>:<port>/?" +
     "username=<Azure client ID or application ID>" +
     "&authMechanism=MONGODB-OIDC" +
     "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>"
client, err := mongo.Connect(options.Client().ApplyURI(uri))
if err != nil {
  panic(err)
}

GCP IMDS

If your application runs on a Google Compute Engine VM, or otherwise uses the GCP Instance Metadata Service, you can authenticate to MongoDB by using the Go driver's built-in GCP support.

You can configure OIDC for GCP IMDS in the following ways:

• By creating a Credential struct and passing it to the SetAuth() method when creating a client

• By setting parameters in your connection string

props := map[string]string{
       "ENVIRONMENT":    "gcp",
       "TOKEN_RESOURCE": "<audience>",
}

uri := "mongodb://<hostname>:<port>"
props := map[string]string{
	"ENVIRONMENT":    "gcp",
	"TOKEN_RESOURCE": "<audience>",
}
opts := options.Client().ApplyURI(uri)
opts.SetAuth(
	options.Credential{
		AuthMechanism:           "MONGODB-OIDC",
		AuthMechanismProperties: props,
	},
)
client, err := mongo.Connect(opts)
if err != nil {
	panic(err)
}

uri := "mongodb://<hostname>:<port>/?" +
     "&authMechanism=MONGODB-OIDC" +
     "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>"
client, err := mongo.Connect(options.Client().ApplyURI(uri))
if err != nil {
  panic(err)
}

Custom Callback

The Go driver doesn't offer built-in support for all platforms, including the AWS Elastic Kubernetes Service (EKS). To authenticate against unsupported platforms, you must define a custom callback function to use OIDC to authenticate. In the driver, you can define an options.OIDCCallback function and set it as the value of the OIDCMachineCallback struct field in your Credential struct.

The following example defines a custom callback for an EKS cluster with a configured IAM OIDC provider. The access token is read from a path set in the AWS_WEB_IDENTITY_TOKEN_FILE environment variable:

eksCallback := func(_ context.Context,
	_ *options.OIDCArgs) (*options.OIDCCredential, error) {
	accessToken, err := os.ReadFile(
		os.Getenv("AWS_WEB_IDENTITY_TOKEN_FILE"))
	if err != nil {
		return nil, err
	}
	return &options.OIDCCredential{
		AccessToken: string(accessToken),
	}, nil
}

Then, you can create a Credential struct that uses the EKS callback function that you defined:

uri := "mongodb://<hostname>:<port>"
opts := options.Client().ApplyURI(uri)
opts.SetAuth(
	options.Credential{
		AuthMechanism:       "MONGODB-OIDC",
		OIDCMachineCallback: eksCallback,
	},
)
client, err := mongo.Connect(opts)
if err != nil {
	panic(err)
}

Other Azure Environments

If your application runs on Azure Functions, App Service Environment (ASE), or Azure Kubernetes Service (AKS), you can use the azidentity module to fetch authentication credentials.

First, install the azidentity module by running the following command:

go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity

Your OIDCCallback function must return an OIDCCredential instance that uses the AccessToken generated from the azidentity package. See the preceding Custom Callback section for an example that implements a custom callback to retrieve an access token and then creates a Credential.

GCP GKE

If your application runs on a GCP Google Kubernetes Engine (GKE) cluster with a configured service account, you can read the OIDC token from the standard service-account token-file location.

First, define the OIDCCallback function. This function reads the OIDC token and returns an OIDCCredential instance.

The following example defines a callback function named gkeCallback. The function retrieves an OIDC token from a file in the standard service-account token-file location:

gkeCallback := func(_ context.Context,
	_ *options.OIDCArgs) (*options.OIDCCredential, error) {
	accessToken, err := os.ReadFile(
		"/var/run/secrets/kubernetes.io/serviceaccount/token")
	if err != nil {
		return nil, err
	}
	return &options.OIDCCredential{
		AccessToken: string(accessToken),
	}, nil
}

Then, you can create a Credential struct that uses the the GKE callback function that you defined:

uri := "mongodb://<hostname>:<port>"
opts := options.Client().ApplyURI(uri)
opts.SetAuth(
	options.Credential{
		AuthMechanism:       "MONGODB-OIDC",
		OIDCMachineCallback: gkeCallback,
	},
)
client, err := mongo.Connect(opts)
if err != nil {
	panic(err)
}

API Documentation

• Credential type

• SetAuth() method

• OIDCCredential type

• OIDCCallback function