Secure Client Authentication with OIDC

Considerations

When you enable OIDC authentication, consider the following:

• Identity Providers: You must have a pre-existing, configured OIDC Identity Provider (IdP). The Kubernetes Operator does not manage the IdP itself.

• Authorization: The Kubernetes Operator configures authentication (verifying identity) via OIDC. Authorization (granting permissions) is handled by mapping OIDC claims to MongoDB roles within the MongoDB custom resource.

• Federation: MongoDB supports both Workload Identity Federation (for machine-to-machine authentication) and Workforce Identity Federation (for human user authentication).

• TLS Encryption: To improve security, it is highly recommended to deploy a TLS-encrypted replica set or a TLS-encrypted sharded cluster. While OIDC communication with your identity provider is secured by HTTPS, enabling TLS on your MongoDB resource encrypts the connection between your client application and the database. This protects the OIDC token and all other database traffic from network threats.

General Prerequisites

Before you configure OIDC authentication for your MongoDB deployments, complete the following tasks:

• Ensure that you deploy the MongoDB Enterprise database resource. MongoDB Community databases don't support OIDC authentication.

• Deploy the replica set or deploy the sharded cluster whose client authentication you want to secure with OpenID Connect.

OIDC Configuration Details

Understanding OIDC Authorization Models

OIDC configuration in MongoDB combines two key concepts: the Federation Method and the Authorization Type.

Managing OIDC Roles and Permissions

After configuring an OIDC provider, you must grant permissions. The method you use to do this depends on the authorizationType you selected.

roles:
 - role: "idp-human-users/app-devs" # Maps the "app-devs" group from the IdP
   db: "admin"
   roles:
     - role: "readWrite"
       db: "app-data"

Configure OIDC Client Authentication for a Replica Set

Follow these steps to configure OIDC for a replica set.

apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: my-oidc-replicaset
spec:
  type: ReplicaSet
  members: 3
  version: 7.0.11-ent
  opsManager:
    configMapRef:
      name: <my-project-configmap>
  credentials: <my-credentials-secret>
  security:
    authentication:
      modes: ["SCRAM", "OIDC"]
      oidcProviderConfigs:
        - configurationName: "idp-human-users"
          issuerURI: "https://<your-idp-domain>"
          clientId: "<your-client-id>"
          audience: "api://default"
          groupsClaim: "groups"
          authorizationMethod: "WorkforceIdentityFederation"
          authorizationType: "GroupMembership"
    roles:
      - role: "idp-human-users/app-devs"
        db: "admin"
        roles:
          - role: "readWrite"
            db: "app-data"

apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: my-oidc-replicaset
spec:
  type: ReplicaSet
  members: 3
  version: 7.0.11-ent
  opsManager:
    configMapRef:
      name: <my-project-configmap>
  credentials: <my-credentials-secret>
  security:
    authentication:
      modes: ["SCRAM", "OIDC"]
      oidcProviderConfigs:
        - configurationName: "billing-service-auth"
          issuerURI: "https://<your-idp-uri>"
          clientId: "<billing-service-client-id>"
          audience: "mongodb-api"
          userClaim: "sub"
          authorizationMethod: "WorkloadIdentityFederation"
          authorizationType: "UserID"

apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: my-oidc-replicaset
spec:
  type: ReplicaSet
  members: 3
  version: 7.0.11-ent
  opsManager:
    configMapRef:
      name: <my-project-configmap>
  credentials: <my-credentials-secret>
  security:
    authentication:
      modes: ["SCRAM", "OIDC"]
      oidcProviderConfigs:
        - configurationName: "idp-special-user"
          issuerURI: "https://<your-idp-domain>"
          clientId: "<your-client-id>"
          audience: "api://default"
          userClaim: "sub"
          authorizationMethod: "WorkforceIdentityFederation"
          authorizationType: "UserID"

apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: my-oidc-replicaset
spec:
  type: ReplicaSet
  members: 3
  version: 7.0.11-ent
  opsManager:
    configMapRef:
      name: <my-project-configmap>
  credentials: <my-credentials-secret>
  security:
    authentication:
      modes: ["SCRAM", "OIDC"]
      oidcProviderConfigs:
        - configurationName: "reporting-services"
          issuerURI: "https://<your-idp-uri>"
          clientId: "<reporting-services-client-id>"
          audience: "mongodb-api"
          groupsClaim: "service-roles"
          authorizationMethod: "WorkloadIdentityFederation"
          authorizationType: "GroupMembership"
    roles:
      - role: "reporting-services/report-generators"
        db: "admin"
        roles:
          - role: "read"
            db: "sales-data"

kubectl apply -f <your-replica-set-file>.yaml

kubectl get mdb <resource-name> -o yaml -w

Configure OIDC Client Authentication for a Sharded Cluster

Use the following example to configure OIDC for a sharded cluster. The principles and configuration options are identical to a replica set.

apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: my-oidc-shardedcluster
spec:
  type: ShardedCluster
  shardCount: 2
  mongodsPerShardCount: 3
  mongosCount: 2
  configServerCount: 3
  version: 7.0.11-ent
  opsManager:
    configMapRef:
      name: <my-project-configmap>
  credentials: <my-credentials-secret>
  security:
    authentication:
      modes: ["SCRAM", "OIDC"]
      oidcProviderConfigs:
        # Provider 1: For human users (Workforce/Group)
        - configurationName: "idp0-human-users"
          issuerURI: "https://<your-idp0-domain>"
          clientId: "<human-users-client-id>"
          audience: "api://default"
          groupsClaim: "groups"
          authorizationMethod: "WorkforceIdentityFederation"
          authorizationType: "GroupMembership"
        # Provider 2: For service accounts (Workload/UserID)
        - configurationName: "service-accounts"
          issuerURI: "https://<your-idp-uri>"
          clientId: "<services-client-id>"
          audience: "mongodb-api"
          userClaim: "sub"
          authorizationMethod: "WorkloadIdentityFederation"
          authorizationType: "UserID"
    roles:
      # Role mapping for the human user group
      - role: "idp0-human-users/db-admins"
        db: "admin"
        roles:
          - role: "readWriteAnyDatabase"
            db: "admin"

OIDC Troubleshooting

• Manually Validate JWT Token: Use a tool to decode the OIDC token.

  • Core Claims: Ensure the iss (issuer) and aud (audience) claims in the token exactly match your OIDC provider configuration. Check that the token is not expired (exp claim).

  • Expected User/Group Claims: Verify that the expected claims for user identity (userClaim) and groups (groupsClaim) are present in the token and contain the correct values.

• Verify Username Format for UserID Auth: The MongoDBUser username must be in the exact format <configurationName>/<userClaimValue>. The <configurationName> must match the name of the OIDC provider in your MongoDB resource.

• Confirm $external Database is Used: For UserID authorization, the MongoDBUser resource must specify db: "$external". Users authenticated by an external source are always resolved through this virtual database.

• Check Group Role Mapping for GroupMembership Auth: Ensure the role defined in the MongoDB resource's spec.security.roles section is formatted correctly as <configurationName>/<groupName>, where <groupName> exactly matches a group in the JWT's groupsClaim.

• Validate Assigned Role Permissions: Check that the MongoDB role(s) assigned to the OIDC user or group actually grant the necessary permissions (e.g., readWrite on the correct database).

• Verify MongoDBUser Resource Reference: For UserID authorization, make sure the spec.mongodbResourceRef.name in the MongoDBUser resource correctly points to the name of your MongoDB deployment.