OIDC Authentication Mechanism

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:

• Create a Credential struct and pass it to the SetAuth() method when you create a client

• Set 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:

• Create a Credential struct and pass it to the SetAuth() method when you create a client

• Set 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)
}

Kubernetes

If your application runs on a Kubernetes cluster with a configured service account, you can authenticate to MongoDB by using the Go driver's built-in Kubernetes support. To learn more about how to configure a service account, see the Managing Service Accounts guide in the Kubernetes documentation.

You can configure OIDC for Kubernetes in the following ways:

• Create a Credential struct and pass it to the SetAuth() method when you create a client

• Set parameters in your connection string

props := map[string]string{
       "ENVIRONMENT":    "k8s",
}

uri := "mongodb://<hostname>:<port>"
props := map[string]string{
	"ENVIRONMENT": "k8s",
}
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:k8s"
client, err := mongo.Connect(options.Client().ApplyURI(uri))
if err != nil {
       panic(err)
}

API Documentation

• Credential type

• SetAuth() method

• OIDCCredential type

• OIDCCallback function