Authorization and Authentication Examples

The following examples show how to implement our recommendations for authentication and authorization for different access types. The examples show how to implement the recommendations using both the Atlas CLI and Terraform.

To learn about Terraform, see Get Started with Terraform and the MongoDB Atlas Provider and the MongoDB Atlas Provider Terraform docs.

Atlas UI

For access to the Atlas UI:

Implement IP access lists. For example,
```
atlas organizations apiKeys accessLists create --apiKey <API_KEY_ID> --ip <IP_ADDRESS>
```
Implement Federated Authentication or Atlas credentials and Multi-factor Authentication (MFA).
To set up Federated Auth, use the atlas-federatedAuthentication and related commands. You can then use the atlas-users-invite command to invite users to your organization and projects.
To get started, use the following command:
```
atlas federatedAuthentication --help
```
Note
For users that authenticate with SSO, you will also need to configure the SSO Identity Provider.
For more information, see Configure Federated Authentication.

Database Access

Workforce (Human) Access

For workforce database access:

Use Workforce Identity Federation.
Use the atlas-dbusers-certs-create command to create Atlas-managed MFA (Multi-Factor Authentication) X.509 client certificates.
Note
To use self-managed certificates, you must first configure X.509:
atlas dbusers certs create --username <USERNAME> --projectId <PROJECT_ID> [--monthsUntilExpiration <MONTHS>] [--output json]

Workload (Machine) Access

For workload (machine) access, use Workload Identity Federation.

API Access

Use the serviceAccounts and related commands to create and manage Service Accounts. For example,

atlas api serviceAccounts createServiceAccount [options]

For development and test environments, you can also use API keys. For example,

atlas organizations apiKeys create [options]

The following examples demonstrate how to configure authentication and authorization. Before you can create resources with Terraform, you must:

Create your paying organization and create an API key for the paying organization. Store your API key as environment variables by running the following command in the terminal:
```
export MONGODB_ATLAS_PUBLIC_KEY="<insert your public key here>"
export MONGODB_ATLAS_PRIVATE_KEY="<insert your private key here>"
```
Install Terraform

Common Files

You must create the following files for each example. Place the files for each example in their own directory. Change the IDs and names to use your values. Then run the commands to initialize Terraform, view the Terraform plan, and apply the changes.

azure.tf

locals {
  tags = {
       CreatedBy = "Terraform"
       Owner     = var.owner
       Module    = "tf-example-oidc-azure"
       Name      = var.project_name
  }
}
resource "azurerm_resource_group" "this" {
  name     = var.project_name
  location = var.location
  tags     = local.tags
}
resource "azurerm_virtual_network" "this" {
  name                = var.project_name
  address_space       = ["10.0.0.0/16"]
  location            = azurerm_resource_group.this.location
  resource_group_name = azurerm_resource_group.this.name
  tags                = local.tags
}
resource "azurerm_subnet" "internal" {
  name                 = "internal"
  resource_group_name  = azurerm_resource_group.this.name
  virtual_network_name = azurerm_virtual_network.this.name
  address_prefixes     = ["10.0.2.0/24"]
}
resource "azurerm_public_ip" "vm-public-ip" {
  name                = "public-ip-${var.project_name}"
  location            = var.location
  resource_group_name = azurerm_resource_group.this.name
  allocation_method   = "Dynamic"
  domain_name_label   = var.project_name
  tags                = local.tags
}
resource "azurerm_network_interface" "this" {
  name                = "ip-${var.project_name}"
  location            = var.location
  resource_group_name = azurerm_resource_group.this.name
  tags                = local.tags
  ip_configuration {
       subnet_id                     = azurerm_subnet.internal.id
       name                          = "public"
       private_ip_address_allocation = "Dynamic"
       public_ip_address_id          = azurerm_public_ip.vm-public-ip.id
  }
}
resource "azurerm_user_assigned_identity" "this" {
  location            = var.location
  name                = var.project_name
  resource_group_name = azurerm_resource_group.this.name
  tags                = local.tags
}
resource "azurerm_linux_virtual_machine" "this" {
  name                  = var.project_name
  resource_group_name   = azurerm_resource_group.this.name
  location              = var.location
  size                  = "Standard_F2"
  admin_username        = var.vm_admin_username
  custom_data           = data.cloudinit_config.this.rendered
  network_interface_ids = [azurerm_network_interface.this.id]
  tags                  = local.tags
  admin_ssh_key {
       username   = var.vm_admin_username
       public_key = var.ssh_public_key
  }
  source_image_reference {
       publisher = "Canonical"
       offer     = "0001-com-ubuntu-server-jammy"
       sku       = "22_04-lts"
       version   = "latest"
  }
  os_disk {
       storage_account_type = "Standard_LRS"
       caching              = "ReadWrite"
       disk_size_gb         = 30
  }
  identity {
       type = "UserAssigned"
       identity_ids = [azurerm_user_assigned_identity.this.id]
  }
}

variables.tf

# Azure Variables
variable "token_audience" {
  type        = string
  default     = "https://management.azure.com/"
  description = "Used as resource when getting the access token. See more in the [Azure documentation](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-to-use-vm-token#get-a-token-using-http)"
}
# MongoDB Atlas variables
variable "org_id" {
  type        = string
  description = "MongoDB Atlas Organization ID"
}
variable "project_id" {
  type        = string
  description = "MongoDB Atlas Project ID"
}
variable "project_name" {
  type        = string
  description = "MongoDB Atlas Project Name"
}
variable "connection_strings" {
  type        = list(string)
  description = "MongoDB Atlas Cluster Standard Connection Strings"
}

terraform.tfvars

org_id = "32b6e34b3d91647abb20e7b8"
project_id = "67212db237c5766221eb6ad9"
project_name = "My Project"
connection_strings =
token_audience = "https://management.azure.com/"

outputs.tf

output "vm_fqdn" {
  value       = azurerm_public_ip.vm-public-ip.fqdn
  description = "Fully Qualified Domain Name (FQDN) of the Virtual Machine (VM)"
}
output "ssh_connection_string" {
  value       = "ssh ${var.vm_admin_username}@${azurerm_public_ip.vm-public-ip.fqdn}"
  description = "Useful for connecting to the instance"
}
output "user_test_conn_string" {
  value       = "mongodb+srv://${local.test_user_username}:${local.test_user_password}@${replace(mongodbatlas_advanced_cluster.this.connection_strings[0].standard_srv, "mongodb+srv://", "")}/?retryWrites=true"
  sensitive   = true
  description = "Useful for connecting to the database from Compass or other tool to validate data"
}
output "user_oidc_conn_string" {
  value       = local.mongodb_oidc_uri
  sensitive   = true
  description = "Useful to see the format of the OIDC connection string"
}

Configure Federated Settings for Identity Provider

Use the following to set up an OIDC federated identity provider in Atlas, for using it with Azure. It allows access by using OIDC tokens issued by Azure Active Directory.

# Connection string to use in this configuration
locals {
  mongodb_uri = var.connection_strings[0]
}
# Atlas organization details to use in the configuration
data "mongodbatlas_federated_settings" "this" {
  org_id = var.org_id
  name   = var.project_name
  project_id = var.project_id
}
# Configure an identity provider for federated authentication
resource "mongodbatlas_federated_settings_identity_provider" "oidc" {
  federation_settings_id = data.mongodbatlas_federated_settings.this.id
  audience               = var.token_audience
  authorization_type     = "USER"
  description            = "oidc-for-azure"
  # e.g. "https://sts.windows.net/91405384-d71e-47f5-92dd-759e272cdc1c/"
  issuer_uri = "https://sts.windows.net/${azurerm_user_assigned_identity.this.tenant_id}/"
  idp_type   = "WORKLOAD"
  name       = "OIDC-for-azure"
  protocol   = "OIDC"
  # groups_claim = null
  user_claim = "sub"
}
resource "mongodbatlas_federated_settings_org_config" "this" {
  federation_settings_id            = data.mongodbatlas_federated_settings.this.id
  org_id                            = var.org_id
  domain_restriction_enabled        = false
  domain_allow_list                 = []
  data_access_identity_provider_ids = [mongodbatlas_federated_settings_identity_provider.oidc.idp_id]
}

Use the following to create an OIDC federated authentication user.

resource "mongodbatlas_database_user" "oidc" {
  project_id         = var.project_id
  username           = "${mongodbatlas_federated_settings_identity_provider.oidc.idp_id}/${azurerm_user_assigned_identity.this.principal_id}"
  oidc_auth_type     = "USER"
  auth_database_name = "$external" # required when using OIDC USER authentication
  roles {
    role_name     = "atlasAdmin"
    database_name = "admin"
  }
}

Configure Custom Role

Use the following to create a custom role named my_custom_role which allows update, add, and delete operations on any collection in the database named myDb.

resource "mongodbatlas_custom_db_role" "create_role" {
  project_id = var.project_id
  role_name  = "my_custom_role"
  actions {
    action = "UPDATE"
    resources {
      database_name   = "myDb"
    }
  }
  actions {
    action = "INSERT"
    resources {
      database_name   = "myDb"
    }
  }
  actions {
    action = "REMOVE"
    resources {
      database_name   = "myDb"
    }
  }
}

Tip

For Terraform examples that enforce our recommendations across all pillars, see one of the following examples in Github:

For an example of an Atlas project with the Atlas role assigned to a specific group, see Examples.

Back

Authorization

Data Encryption