Configure MongoDB with Workload Identity Federation to authenticate services across different platforms. This enhances security and simplifies service identity management.
Important
OpenID Connect (OIDC) is only supported on Linux.
Before you Begin
Ensure that you are on MongoDB Enterprise.
To verify that you are using MongoDB Enterprise, pass the
--versioncommand line option to themongodormongos:mongod --version In the output from this command, look for the string
modules: subscriptionormodules: enterpriseto confirm you are using the MongoDB Enterprise binaries.Configure your external identity provider. For more details, see Configure Workload Identity Federation.
Steps
Configure the MongoDB server with OpenID Connect (OIDC)
To configure the MongoDB server, enable the MONGODB-OIDC authentication mechanism and use the
oidcIdentityProviders to specify identity provider
(IDP) configurations.
Note
When configuring MongoDB for Workload Identity Federation, set
the supportsHumanFlows field in
oidcIdentityProviders to false.
You can configure the MongoDB server using your configuration file or command line.
To use your configuration file, specify these parameters in the file:
setParameter: authenticationMechanisms: MONGODB-OIDC oidcIdentityProviders: '[ { "issuer": "https://okta-test.okta.com", "audience": "example@kernel.mongodb.com", "authNamePrefix": "okta-issuer", "authorizationClaim": "groups", "supportsHumanFlows": false, } ]'
To specify multiple identity providers, add additional
objects to the oidcIdentityProviders array. For example:
setParameter: authenticationMechanisms: MONGODB-OIDC oidcIdentityProviders: '[ { "issuer": "https://okta-test.okta.com", "audience": "example@kernel.mongodb.com", "authNamePrefix": "okta-issuer", "authorizationClaim": "groups", "supportsHumanFlows": false, }, { "issuer": "https://azure-test.azure.com", "audience": "example2@kernel.mongodb.com", "authNamePrefix": "azure-issuer", "authorizationClaim": "groups", "supportsHumanFlows": false, } ]'
To use the command line, specify the following startup options:
mongod --auth --setParameter authenticationMechanisms=MONGODB-OIDC --setParameter \ 'oidcIdentityProviders=[ { "issuer": "https://okta-test.okta.com", "audience": "example@kernel.mongodb.com", "authNamePrefix": "okta-issuer", "authorizationClaim": "groups", "supportsHumanFlows": false, } ]'
To specify multiple identity providers, add additional
objects to the oidcIdentityProviders array. For example:
mongod --auth --setParameter authenticationMechanisms=MONGODB-OIDC --setParameter \ 'oidcIdentityProviders=[ { "issuer": "https://okta-test.okta.com", "audience": "example@kernel.mongodb.com", "authNamePrefix": "okta-issuer", "authorizationClaim": "groups", "supportsHumanFlows": false }, { "issuer": "https://azure-test.azure.com", "audience": "example2@kernel.mongodb.com", "authNamePrefix": "azure-issuer", "authorizationClaim": "groups", "supportsHumanFlows": false } ]'
(Optional) Enable internal authorization
To enable internal authorization, set the
useAuthorizationClaim field of the oidcIdentityProviders
parameter to false. This setting enables more flexible user
management by relying on user documents rather than authorization
claims from the identity provider.
Important
If useAuthorizationClaim is set to false, do not
include the authorizationClaim field.
setParameter: authenticationMechanisms: MONGODB-OIDC oidcIdentityProviders: '[ { "issuer": "https://okta-test.okta.com", "audience": "example@kernel.mongodb.com", "authNamePrefix": "okta-issuer", "useAuthorizationClaim": false, "supportsHumanFlows": false, } ]'
To specify multiple identity providers, add additional
objects to the oidcIdentityProviders array. For example:
setParameter: authenticationMechanisms: MONGODB-OIDC oidcIdentityProviders: '[ { "issuer": "https://okta-test.okta.com", "audience": "example@kernel.mongodb.com", "authNamePrefix": "okta-issuer", "useAuthorizationClaim": false, "supportsHumanFlows": false, }, { "issuer": "https://azure-test.azure.com", "audience": "example2@kernel.mongodb.com", "authNamePrefix": "azure-issuer", "useAuthorizationClaim": false, "supportsHumanFlows": false, } ]'
mongod --auth --setParameter authenticationMechanisms=MONGODB-OIDC --setParameter \ 'oidcIdentityProviders=[ { "issuer": "https://okta-test.okta.com", "audience": "example@kernel.mongodb.com", "authNamePrefix": "okta-issuer", "useAuthorizationClaim": false, "supportsHumanFlows": false, } ]'
To specify multiple identity providers, add additional
objects to the oidcIdentityProviders array. For example:
mongod --auth --setParameter authenticationMechanisms=MONGODB-OIDC --setParameter \ 'oidcIdentityProviders=[ { "issuer": "https://okta-test.okta.com", "audience": "example@kernel.mongodb.com", "authNamePrefix": "okta-issuer", "useAuthorizationClaim": false, "supportsHumanFlows": false, }, { "issuer": "https://azure-test.azure.com", "audience": "example2@kernel.mongodb.com", "authNamePrefix": "azure-issuer", "useAuthorizationClaim": false, "supportsHumanFlows": false, } ]'
When you set useAuthorizationClaim to false, users who
authenticate with the MONGODB-OIDC mechanism obtain their
authorization rights from a user document in $external. The
server searches for a user document with an _id matching the
value of the authNamePrefix/principalName claim for every OIDC
based authentication attempt for a user of your identity provider.
(Conditional) CA Certificates for Internal X509 TLS
For environments using X509 TLS certificates signed by an internal
Certificate Authority (CA), you must add the CA certificate to the
system CA certificate bundle so that mongod can
communicate with the identity provider. This applies to user
authentication and to workload authentication when using the callback
method. Omitting this step might result in OIDC SSL Certificate or JWT
Key Verification errors.