chore: Merge SA dev branch to master

.changelog/3700.txt

@@ -0,0 +1,3 @@
+```release-note:enhancement
+provider: Supports Service Account as credentials to authenticate the provider
+```

.changelog/3716.txt

@@ -0,0 +1,3 @@
+```release-note:enhancement
+provider: Supports Service Account JWT Token as credentials to authenticate the provider
+```

.changelog/3738.txt

@@ -0,0 +1,3 @@
+```release-note:bug
+provider: Enforces strict hierarchy when selecting the credential source such as AWS Secrets Manager, provider attributes, or environment variables to prevent combining with values from different sources
+```

.github/workflows/acceptance-tests-runner.yml

@@ -163,6 +163,10 @@ on:
         required: true
       mongodb_atlas_rp_public_key:
         required: true
+      mongodb_atlas_rp_client_id:
+        required: true
+      mongodb_atlas_rp_client_secret:
+        required: true
       mongodb_atlas_client_id:
         required: true
       mongodb_atlas_client_secret:
@@ -206,9 +210,10 @@ env:
   TF_ACC: 1
   TF_LOG: ${{ vars.LOG_LEVEL }}
   ACCTEST_TIMEOUT: ${{ vars.ACCTEST_TIMEOUT }}
-  # Only Migration tests are run when a specific previous provider version is set
-  # If the name (regex) of the test is set, only that test is run
-  ACCTEST_REGEX_RUN: ${{ inputs.test_name || inputs.provider_version == '' && '^Test(Acc|Mig)' || '^TestMig' }}
+  # If the name (regex) of the test is set, only that test is run.
+  # Don't run migration tests if using Service Accounts because previous provider versions don't support SA yet.
+  # Only Migration tests are run when a specific previous provider version is set.
+  ACCTEST_REGEX_RUN: ${{ inputs.test_name || inputs.use_sa && '^TestAcc' || inputs.provider_version == '' && '^Test(Acc|Mig)' || '^TestMig' }}
   MONGODB_ATLAS_BASE_URL: ${{ inputs.mongodb_atlas_base_url }}
   MONGODB_REALM_BASE_URL: ${{ inputs.mongodb_realm_base_url }}
   MONGODB_ATLAS_ORG_ID: ${{ inputs.mongodb_atlas_org_id }}
@@ -554,8 +559,39 @@ jobs:
           MONGODB_ATLAS_CLIENT_ID: ${{ secrets.mongodb_atlas_client_id }}
           MONGODB_ATLAS_CLIENT_SECRET: ${{ secrets.mongodb_atlas_client_secret }}
           MONGODB_ATLAS_LAST_VERSION: ${{ needs.get-provider-version.outputs.provider_version }}
-          ACCTEST_REGEX_RUN: '^TestUnexisting' # TODO: SA not implemented in master yet
-          # ACCTEST_REGEX_RUN: '^TestAccServiceAccount'
+          ACCTEST_REGEX_RUN: '^TestAccServiceAccount'
+          ACCTEST_PACKAGES: ./internal/provider
+        run: make testacc
+      - name: Generate OAuth2 Token
+        id: generate-token
+        shell: bash
+        env:
+          MONGODB_ATLAS_BASE_URL: ${{ inputs.mongodb_atlas_base_url }}
+          MONGODB_ATLAS_CLIENT_ID: ${{ secrets.mongodb_atlas_client_id }}
+          MONGODB_ATLAS_CLIENT_SECRET: ${{ secrets.mongodb_atlas_client_secret }}
+        run: |
+          if ! ACCESS_TOKEN=$(make generate-oauth2-token); then
+            echo "Error: Failed to generate access token"
+            exit 1
+          fi
+          if [ -z "$ACCESS_TOKEN" ]; then
+            echo "Error: Generated access token is empty"
+            exit 1
+          fi
+          {
+            echo "access_token<<EOF"
+            echo "$ACCESS_TOKEN"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+      - name: Acceptance Tests (Access Token)
+        env:
+          MONGODB_ATLAS_PUBLIC_KEY: ""
+          MONGODB_ATLAS_PRIVATE_KEY: ""
+          MONGODB_ATLAS_CLIENT_ID: ""
+          MONGODB_ATLAS_CLIENT_SECRET: ""
+          MONGODB_ATLAS_ACCESS_TOKEN: ${{ steps.generate-token.outputs.access_token }}
+          MONGODB_ATLAS_LAST_VERSION: ${{ needs.get-provider-version.outputs.provider_version }}
+          ACCTEST_REGEX_RUN: '^TestAccAccessToken'
           ACCTEST_PACKAGES: ./internal/provider
         run: make testacc
       - name: Acceptance Tests (Service Account smoke tests) # small selection of fast tests to run with SA
@@ -565,7 +601,7 @@ jobs:
           MONGODB_ATLAS_CLIENT_ID: ${{ secrets.mongodb_atlas_client_id }}
           MONGODB_ATLAS_CLIENT_SECRET: ${{ secrets.mongodb_atlas_client_secret }}
           MONGODB_ATLAS_LAST_VERSION: ${{ needs.get-provider-version.outputs.provider_version }}
-          ACCTEST_REGEX_RUN: '^TestUnexisting' # TODO: SA not implemented in master yet
+          ACCTEST_REGEX_RUN: '^TestAcc' # Don't run migration tests because previous provider versions don't support SA.
           ACCTEST_PACKAGES: |
             ./internal/service/alertconfiguration
             ./internal/service/databaseuser
@@ -1176,12 +1212,13 @@ jobs:
           terraform_wrapper: false  
       - name: Acceptance Tests
         env:
+          MONGODB_ATLAS_PUBLIC_KEY: ${{ inputs.use_sa == false && secrets.mongodb_atlas_rp_public_key || '' }}
+          MONGODB_ATLAS_PRIVATE_KEY: ${{ inputs.use_sa == false && secrets.mongodb_atlas_rp_private_key || '' }}
+          MONGODB_ATLAS_CLIENT_ID: ${{ inputs.use_sa  && secrets.mongodb_atlas_rp_client_id || '' }}
+          MONGODB_ATLAS_CLIENT_SECRET: ${{ inputs.use_sa && secrets.mongodb_atlas_rp_client_secret || '' }}
           MONGODB_ATLAS_ORG_ID: ${{ inputs.mongodb_atlas_rp_org_id }}
-          MONGODB_ATLAS_PUBLIC_KEY: ${{ secrets.mongodb_atlas_rp_public_key }}
-          MONGODB_ATLAS_PRIVATE_KEY:  ${{ secrets.mongodb_atlas_rp_private_key }}
           MONGODB_ATLAS_LAST_VERSION: ${{ needs.get-provider-version.outputs.provider_version }}
-          ACCTEST_PACKAGES: |
-            ./internal/service/resourcepolicy
+          ACCTEST_PACKAGES: ./internal/service/resourcepolicy
         run: make testacc
 
   search_deployment:

.github/workflows/acceptance-tests.yml

@@ -82,6 +82,8 @@ jobs:
       mongodb_atlas_gov_private_key: ${{ inputs.atlas_cloud_env == 'qa' && secrets.MONGODB_ATLAS_GOV_PRIVATE_KEY_QA || secrets.MONGODB_ATLAS_GOV_PRIVATE_KEY_DEV }}
       mongodb_atlas_rp_public_key: ${{ inputs.atlas_cloud_env == 'qa' && secrets.MONGODB_ATLAS_RP_PUBLIC_KEY_QA || secrets.MONGODB_ATLAS_RP_PUBLIC_KEY_DEV }}
       mongodb_atlas_rp_private_key: ${{ inputs.atlas_cloud_env == 'qa' && secrets.MONGODB_ATLAS_RP_PRIVATE_KEY_QA || secrets.MONGODB_ATLAS_RP_PRIVATE_KEY_DEV }}
+      mongodb_atlas_rp_client_id: ${{ inputs.atlas_cloud_env == 'qa' && secrets.MONGODB_ATLAS_RP_CLIENT_ID_QA || secrets.MONGODB_ATLAS_RP_CLIENT_ID_DEV }}
+      mongodb_atlas_rp_client_secret: ${{ inputs.atlas_cloud_env == 'qa' && secrets.MONGODB_ATLAS_RP_CLIENT_SECRET_QA || secrets.MONGODB_ATLAS_RP_CLIENT_SECRET_DEV }}
       mongodb_atlas_client_id: ${{ inputs.atlas_cloud_env == 'qa' && secrets.MONGODB_ATLAS_CLIENT_ID_QA || secrets.MONGODB_ATLAS_CLIENT_ID_DEV }}
       mongodb_atlas_client_secret: ${{ inputs.atlas_cloud_env == 'qa' && secrets.MONGODB_ATLAS_CLIENT_SECRET_QA || secrets.MONGODB_ATLAS_CLIENT_SECRET_DEV }}
       ca_cert: ${{ secrets.CA_CERT }}

Makefile

@@ -43,11 +43,16 @@ test: fmtcheck ## Run unit tests
 	@$(eval export MONGODB_ATLAS_ORG_ID?=111111111111111111111111)
 	@$(eval export MONGODB_ATLAS_PROJECT_ID?=111111111111111111111111)
 	@$(eval export MONGODB_ATLAS_CLUSTER_NAME?=mocked-cluster)
+	@$(eval export MONGODB_ATLAS_PUBLIC_KEY=)
+	@$(eval export MONGODB_ATLAS_PRIVATE_KEY=)
+	@$(eval export MONGODB_ATLAS_CLIENT_ID=)
+	@$(eval export MONGODB_ATLAS_CLIENT_SECRET=)
+	@$(eval export MONGODB_ATLAS_ACCESS_TOKEN=)
 	go test ./... -timeout=120s -parallel=$(PARALLEL_GO_TEST) -race
 
 .PHONY: testmact
 testmact: ## Run MacT tests (mocked acc tests)
-	@$(eval ACCTEST_REGEX_RUN?=^TestAccMockable)
+	@$(eval export ACCTEST_REGEX_RUN?=^TestAccMockable)
 	@$(eval export HTTP_MOCKER_REPLAY?=true)
 	@$(eval export HTTP_MOCKER_CAPTURE?=false)
 	@$(eval export MONGODB_ATLAS_ORG_ID?=111111111111111111111111)
@@ -72,7 +77,7 @@ testmact-capture: ## Capture HTTP traffic for MacT tests
 
 .PHONY: testacc
 testacc: fmtcheck ## Run acc & mig tests (acceptance & migration tests)
-	@$(eval ACCTEST_REGEX_RUN?=^TestAcc)
+	@$(eval export ACCTEST_REGEX_RUN?=^TestAcc)
 	TF_ACC=1 go test $(ACCTEST_PACKAGES) -run '$(ACCTEST_REGEX_RUN)' -v -parallel $(PARALLEL_GO_TEST) $(TESTARGS) -timeout $(ACCTEST_TIMEOUT) -ldflags="$(LINKER_FLAGS)"
 
 .PHONY: testaccgov
@@ -196,6 +201,10 @@ check-changelog-entry-file: ## Check a changelog entry file in a PR
 jira-release-version: ## Update Jira version in a release
 	go run ./tools/jira-release-version/*.go
 
+.PHONY: generate-oauth2-token
+generate-oauth2-token: ## Generate OAuth2 access token from Service Account credentials
+	@go run ./tools/generate-oauth2-token/*.go
+
 .PHONY: enable-autogen
 enable-autogen: ## Enable use of autogen resources in the provider
 	$(eval filename := ./internal/provider/provider.go)

docs/guides/provider-configuration.md

@@ -0,0 +1,176 @@
+---
+page_title: "Guide: Provider Configuration"
+---
+
+# Provider Configuration
+
+This guide covers authentication and configuration options for the MongoDB Atlas Provider.
+
+## Authentication Methods
+
+The MongoDB Atlas provider supports the following authentication methods:
+
+1. [**Service Account (SA)** - Recommended](#service-account-recommended)
+2. [**Programmatic Access Key (PAK)**](#programmatic-access-key)
+
+Credentials can be provided through (in priority order):
+
+- AWS Secrets Manager
+- Provider attributes
+- Environment variables
+
+The provider uses the first available credentials source.
+
+### Service Account (Recommended)
+
+SAs simplify authentication by eliminating the need to create new Atlas-specific user identities and permission credentials. See [Service Accounts Overview](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/) and [MongoDB Atlas Service Account Limits](https://www.mongodb.com/docs/manual/reference/limits/#mongodb-atlas-service-account-limits) for more information.
+
+To use SA authentication, create an SA in your [MongoDB Atlas organization](https://www.mongodb.com/docs/atlas/configure-api-access/#grant-programmatic-access-to-an-organization) and set the credentials, for example:
+
+```terraform
+provider "mongodbatlas" {
+  client_id     = var.mongodbatlas_client_id
+  client_secret = var.mongodbatlas_client_secret
+}
+```
+
+**Note:** SAs can't be used with `mongodbatlas_event_trigger` resources because its API doesn't support it yet.
+
+### Programmatic Access Key
+
+Generate a PAK with the appropriate [role](https://docs.atlas.mongodb.com/reference/user-roles/). See the [MongoDB Atlas documentation](https://www.mongodb.com/docs/atlas/configure-api-access-org/) for detailed instructions.
+
+**Role recommendation:** If unsure which role to grant, use an organization API key with the Organization Owner role to ensure sufficient access as in the following example:
+
+```terraform
+provider "mongodbatlas" {
+  public_key  = var.mongodbatlas_public_key
+  private_key = var.mongodbatlas_private_key
+}
+```
+
+~> **Migrating from PAK to SA:** Update your provider attributes or environment variables to use SA credentials instead of PAK credentials, then run `terraform plan` to verify everything works correctly.
+
+## AWS Secrets Manager
+
+The provider supports retrieving credentials from AWS Secrets Manager. See [AWS Secrets Manager documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) for more details.
+
+### Setup Instructions
+
+1. **Create secrets in AWS Secrets Manager**
+
+   For SA, create a secret with the following key-value pairs:
+   - `client_id`: your-client-id
+   - `client_secret`: your-client-secret
+
+   For PAK, create a secret with the following key-value pairs:
+   - `public_key`: your-public-key
+   - `private_key`: your-private-key
+
+2. **Create an IAM Role** with:
+   - Permission for `sts:AssumeRole`
+   - Attached AWS managed policy `SecretsManagerReadWrite`
+
+3. **Configure AWS credentials** (using AWS CLI or environment variables)
+
+4. **Assume the role** to obtain STS credentials
+
+   ```shell
+   aws sts assume-role --role-arn <ROLE_ARN> --role-session-name newSession
+   ```
+
+5. **Configure provider with AWS Secrets Manager**
+
+   Using provider attributes:
+
+   ```terraform
+   provider "mongodbatlas" {
+      aws_access_key_id     = var.aws_access_key_id
+      aws_secret_access_key = var.aws_secret_access_key
+      aws_session_token     = var.aws_session_token
+      assume_role           = "arn:aws:iam::<AWS_ACCOUNT_ID>:role/mdbsts"
+      secret_name           = "mongodbsecret"
+      region                = "us-east-2"
+   }
+   ```
+
+   Alternatively, you can use environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `ASSUME_ROLE_ARN`, `SECRET_NAME`, `AWS_REGION`).
+
+### Cross-Account and Cross-Region Access
+
+For cross-account secrets, use the fully qualified ARN for `secret_name`. For cross-region or cross-account access, the `sts_endpoint` parameter is required, for example:
+
+```terraform
+provider "mongodbatlas" {
+   aws_access_key_id     = var.aws_access_key_id
+   aws_secret_access_key = var.aws_secret_access_key
+   aws_session_token     = var.aws_session_token
+   assume_role    = "arn:aws:iam::<AWS_ACCOUNT_ID>:role/mdbsts"
+   secret_name    = "arn:aws:secretsmanager:us-east-1:<AWS_ACCOUNT_ID>:secret:test789-TO06Hy"
+   region         = "us-east-2"
+   sts_endpoint   = "https://sts.us-east-2.amazonaws.com/"
+}
+```
+
+## Provider Configuration Reference
+
+### Provider Arguments
+
+* `client_id` - (Optional) SA Client ID (env: `MONGODB_ATLAS_CLIENT_ID`).
+* `client_secret` - (Optional) SA Client Secret (env: `MONGODB_ATLAS_CLIENT_SECRET`).
+* `access_token` - (Optional) SA Access Token (env: `MONGODB_ATLAS_ACCESS_TOKEN`). Instead of using Client ID and Client Secret, you can generate and use an SA token directly. See [Generate Service Account Token](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token/#std-label-generate-oauth2-token-atlas) for details. Note: tokens have expiration times.
+* `public_key` - (Optional) PAK Public Key (env: `MONGODB_ATLAS_PUBLIC_API_KEY`).
+* `private_key` - (Optional) PAK Private Key (env: `MONGODB_ATLAS_PRIVATE_API_KEY`).
+* `base_url` - (Optional) MongoDB Atlas Base URL (env: `MONGODB_ATLAS_BASE_URL`). For advanced use cases, you can configure custom API endpoints.
+* `realm_base_url` - (Optional) MongoDB Realm Base URL (env: `MONGODB_REALM_BASE_URL`).
+* `is_mongodbgov_cloud` - (Optional) Set to `true` to use MongoDB Atlas for Government, a dedicated deployment option for government agencies and contractors requiring FedRAMP compliance. When enabled, the provider uses government-specific API endpoints. Ensure credentials are created in the government environment. See [Atlas for Government Considerations](https://www.mongodb.com/docs/atlas/government/api/#atlas-for-government-considerations) for feature limitations and requirements.
+  ```terraform
+  provider "mongodbatlas" {
+    client_id           = var.mongodbatlas_client_id
+    client_secret       = var.mongodbatlas_client_secret
+    is_mongodbgov_cloud = true
+  }
+  ```
+* `assume_role` - (Optional) AWS IAM role configuration for accessing secrets in AWS Secrets Manager. Role ARN env: `ASSUME_ROLE_ARN`. See [AWS Secrets Manager](#aws-secrets-manager) section for details.
+* `secret_name` - (Optional) Name of the secret in AWS Secrets Manager (env: `SECRET_NAME`).
+* `region` - (Optional) AWS region where the secret is stored (env: `AWS_REGION`).
+* `aws_access_key_id` - (Optional) AWS Access Key ID (env: `AWS_ACCESS_KEY_ID`).
+* `aws_secret_access_key` - (Optional) AWS Secret Access Key (env: `AWS_SECRET_ACCESS_KEY`).
+* `aws_session_token` - (Optional) AWS Session Token (env: `AWS_SESSION_TOKEN`).
+* `sts_endpoint` - (Optional) AWS STS endpoint (env: `STS_ENDPOINT`).
+
+## Credential Priority
+
+When multiple credentials are provided in the same source, the provider uses this priority order:
+
+1. Access Token
+2. Service Account (SA)
+3. Programmatic Access Key (PAK)
+
+The provider displays a warning when multiple credentials are detected.
+
+## Supported OS and Architectures
+
+As per [HashiCorp's recommendations](https://developer.hashicorp.com/terraform/registry/providers/os-arch), the MongoDB Atlas Provider fully supports the following operating system / architecture combinations:
+
+- Darwin / AMD64
+- Darwin / ARMv8
+- Linux / AMD64
+- Linux / ARMv8 (AArch64/ARM64)
+- Linux / ARMv6
+- Windows / AMD64
+
+We ship binaries but do not prioritize fixes for the following operating system / architecture combinations:
+
+- Linux / 386
+- Windows / 386
+- FreeBSD / 386
+- FreeBSD / AMD64
+
+## Additional Resources
+
+- [MongoDB Atlas API Documentation](https://www.mongodb.com/docs/atlas/api/)
+- [Service Accounts Overview](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/)
+- [Configure API Access](https://www.mongodb.com/docs/atlas/configure-api-access/)
+- [Atlas for Government](https://www.mongodb.com/docs/atlas/government/)
+- [Terraform Provider Documentation](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs)