MongoDB

Wojciech Trocki

Senior Software Engineer

[MongoDB's Atlas Administration API](https://www.mongodb.com/docs/atlas/configure-api-access/) provides a powerful way to interact with [MongoDB Atlas](https://www.mongodb.com/products/platform/atlas-database) resources. It enables you to manage your Atlas organizations, projects, deployments, and more, allowing you to seamlessly automate and integrate administrative tasks directly into your applications or CI/CD systems. MongoDB Atlas offers various API clients, including the [Atlas CLI](https://github.com/mongodb/mongodb-atlas-cli) and [Terraform providers](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest). In certain scenarios, you can leverage direct programmatic access from applications and automation systems written in languages like Go, Python, or Node.js.

With the introduction of the [Service Accounts](https://www.mongodb.com/docs/atlas/api/service-accounts-overview) for Atlas Administration API, you now can use OAuth2 token credentials when performing API requests. The OAuth2 standard simplifies authentication with the Atlas API compared to the previously used [digest](https://www.mongodb.com/developer/products/atlas/nodejs-python-ruby-atlas-api) authentication. Service Accounts, currently available as a preview feature, offer a new way to authenticate to Atlas using the industry-standard OAuth 2.0 with the [Client Credentials](https://oauth.net/2/grant-types/client-credentials/) flow. This provides a secure and efficient method to manage access to your Atlas resources.

In this tutorial, we will guide you through the process of setting up a service account using the [Atlas SDK Go](https://github.com/mongodb/atlas-sdk-go), Node.js, and Python. We will provide instructions on obtaining the necessary credentials and making programmatic API requests to MongoDB Atlas directly from your application.

## What are Service Accounts?

Service Accounts provide a new way to authenticate to Atlas using [OAuth 2.0 with the Client Credentials](https://oauth.net/2/grant-types/client-credentials/) flow. A service account provides a client ID and client secret, which are used to generate access tokens for performing API requests. Access tokens are currently valid for one hour. Service accounts are created within an Atlas organization and can be configured to access multiple projects within that organization.

![Infographic describing MongoDB Atlas Programmatic Authentication with Service AccountsProgrammatic Authentication with MongoDB Atlas enables secure service account integration for automation.Features:- Leverage service accounts to handle automated processes effectively. Improve CI/CD workflows and support AI training through robust API interactions.- Automate the creation and management of clusters, ensuring reliable backups, scaling, and monitoring without the need for manual setup. Utilize OAuth in programming languages of your choice- Utilize established OAuth clients like Python, JavaScript, and Golang to securely link with MongoDB Atlas and streamline data operations.- Implement detailed access controls for service accounts. Assign roles for reading, writing, or admin tasks, following the least privilege principle for better security.][1]

## Prerequisites

Before you begin, ensure you have the following:

1. A MongoDB Atlas account. If you don’t have one already, follow the [Get Started With Atlas](https://www.mongodb.com/docs/atlas/getting-started/) guide to create your account and first cluster. 
2. A service account with a client ID and client secret. 
3. To create a service account, follow the instructions provided in the [Service Accounts](https://www.mongodb.com/docs/atlas/api/service-accounts-overview). 
    1. For this tutorial, your service account will require a [*ORG\_READ\_ONLY*](https://www.mongodb.com/docs/atlas/reference/user-roles/#mongodb-authrole-Organization-Member) role. 
    2. Once you have created a service account, you will receive a client ID and client secret, which you will use to generate OAuth access tokens for Atlas API requests.

**NOTE**: *Service account credentials will give anyone access to your MongoDB Atlas resources. It is crucial to securely store your client ID and client secret and never expose them in public source code platforms like GitHub.*

## TL;DR?

All examples are available under the [GitHub repository](https://github.com/mongodb-developer/atlas-admin-api-serviceaccount-auth) for direct consumption.

Before running any examples, please make sure to execute all prerequisites.

## Choosing your language

In this tutorial, we will provide steps to make programmatic API requests in different languages:

* Python  
* Node.js  
* Go (using [Atlas SDK Go](https://github.com/mongodb/atlas-sdk-go)) 
    * Learn more about the [Go SDK](https://www.mongodb.com/blog/post/enhancing-mongodb-atlas-go-sdk-with-automated-code-generation).

Please refer to the [Atlas documentation](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/) for a complete list of Atlas APIs for languages without an Atlas SDK. You can also use our official [Postman](https://www.mongodb.com/developer/products/atlas/admin-api-postman/) integration to explore and interact with the API itself. 

## Authentication process

The Atlas API authentication process will consist of the following steps, independent of the language and framework:

- Loading credentials using environment variables 
    - For the purpose of examples, we will use environment variables to store the client ID and client secret.
    - For production usage, please follow [OWASP recommendation ](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) for secrets.
- Generating access token
    - Depending on your language, some libraries will perform a [POST request to the OAuth token endpoint](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token/) out of the box. In other cases, you will need to make a request yourself.  The response from the call will contain the access token that will be used for authentication.
- Using access token
    - The access token will be included in the *Authorization* header of subsequent API requests to authenticate them.
    - An access token needs to be regenerated when it expires, and the API returns an *HTTP 401* status code.
- Optionally, we can revoke [the created OAuth token](https://www.mongodb.com/docs/atlas/api/service-accounts/revoke-oauth2-token/) when it is no longer needed.

### Service accounts with Python

We will use Python to start with the simplest and most self-contained service account integration example. Python provides many libraries for performing HTTP requests. For instance, we will use the [Requests](https://pypi.org/project/requests/) library to handle OAuth 2.0 authentication. 

#### Prerequisites

1. Ensure you have [installed Python 3.8](https://python.org) or later on your machine. 
2. Install the required packages:

```
pip install requests 
pip install oauthlib 
```

#### Creating our example

**Step #1:** Open your favorite code editor and create a file named *atlas\_request.py*. 

**Step #2:** Copy the content into the new file. Here's what the complete script will look like:

```python
import os
from requests_oauthlib import OAuth2Session
from oauthlib.oauth2 import BackendApplicationClient
from requests.auth import HTTPBasicAuth
import requests

# Constants
token_path = "/api/oauth/token"
api_url = "/api/atlas/v2/"
client_id = os.environ["MONGODB_ATLAS_CLIENT_ID"]
client_secret = os.environ["MONGODB_ATLAS_CLIENT_SECRET"]
base_url = "https://cloud.mongodb.com"

def get_access_token():
    # Use BackendApplicationClient for the client credentials grant
    client = BackendApplicationClient(client_id=client_id)
    oauth = OAuth2Session(client=client)

    # Prepare Basic Auth credentials
    auth = HTTPBasicAuth(client_id, client_secret)
    token_url = f"{base_url}{token_path}"

    # Fetch the token using the proper authentication
    token = oauth.fetch_token(token_url=token_url, auth=auth)
    return token['access_token']

def fetch_data():
    access_token = get_access_token()
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Accept": "application/vnd.atlas.2023-01-01+json"
    }

    response = requests.get(f"{base_url}{api_url}", headers=headers)
    response.raise_for_status()

    return response.json()

if __name__ == "__main__":
    try:
        data = fetch_data()
        print(data)
    except Exception as e:
        print(f"Error: {e}")
```

**Step #3:** Set the environment variables in your terminal:

```
set +o history # disable history as we're going to paste credentials
export SA_CLIENT_ID=your_client_id
export SA_CLIENT_SECRET=your_client_secret
```

**Step #4:** Run the example:

```
python atlas_request.py
```

As a result, you should see *Response Status: 200* in the console.

#### Understanding the script

Let’s unpack what’s happening in the Python script step by step. 

The Python script performs several steps to authenticate with MongoDB Atlas using OAuth2 and query its API.

- We start by loading our credentials from environment variables. 
    - Environment variables allow us to manage sensitive information, like your MongoDB Atlas client ID and secret, without hard-coding them into your script. 
    - We retrieve the following variables: 
        - `MONGODB_ATLAS_CLIENT_ID` and `MONGODB_ATLAS_CLIENT_SECRET` for OAuth2 authentication.  
- With our credentials in place, we obtain an access token, essential for making authenticated API requests.  
    - The get\_access\_token function: 
        - We're leveraging the client credentials grant type through the *BackendApplicationClient* from *oauthlib*. 
            - Token management operations are handled entirely by the library. 
            - Please make sure to always use the latest version of the *oauthlib* library to avoid potential security issues. 
        - Using *HTTPBasicAuth*, we generate the credentials needed to request a token. 
        - Please note that the access token needs to be periodically updated upon expiry. 
- Using the obtained access token: 
    - First, we grab our access token returned from the get\_access\_token method. 
    - Next, we set up our request with proper headers: 
        - Authorization is set to Bearer {access\_token}. 
        - Accept specifies the MongoDB Atlas API version required to perform requests against Atlas API (application/vnd.atlas.2023-01-01+json). 
    - The function calls the Atlas API endpoint and awaits the response\! 
        - `GET` request to the specified Atlas API endpoint (`{base_url}/api/atlas/v2/`).

### Service accounts with Node.js

Node.js provides a rich number of libraries for performing HTTP requests. Our example will follow a [Node.JS Reference Architecture](https://github.com/nodeshift/nodejs-reference-architecture) recommendation by using the [Axios](https://www.npmjs.com/package/axios) npm library. 

Axios is a popular promise-based HTTP client for the browser and Node.js. For brevity, the example is written in JavaScript, but it can be adapted to TypeScript by using [Axios Typings.](https://github.com/axios/axios/blob/v1.x/index.d.ts) 

#### Prerequisites

1. Ensure you have [Node.js](http://nodejs.org) and npm installed on your machine.  
2. For existing projects, install the required *axios* and *simple-oauth2* package:

```
 npm install —-save axios simple-oauth2
```

If you are recreating a new project, you need to initialize the *package.json* file by running:

```
npm init
```

#### Procedure

**Step #1:** Open your favorite code editor and create a file named *atlas\_request.js*. 

**Step #2:** Copy the content into the new file. Here's what the complete script will look like:

```javascript
const axios = require('axios');
const { ClientCredentials } = require('simple-oauth2');

// Can be any API url from https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/
const apiURL = '/api/atlas/v2/';

const { MONGODB_ATLAS_CLIENT_ID, MONGODB_ATLAS_CLIENT_SECRET } = process.env;

var baseUrl = "https://cloud.mongodb.com";

// OAuth2 Client Configuration
const oauth2Config = {
  client: {
    id: MONGODB_ATLAS_CLIENT_ID,
    secret: MONGODB_ATLAS_CLIENT_SECRET,
  },
  auth: {
    tokenHost: baseUrl,
    tokenPath: '/api/oauth/token',
  },
};

// Create OAuth2 Client
const oauth2Client = new ClientCredentials(oauth2Config);

async function fetchWithOAuth2() {
  try {
    // Retrieve access token
    const tokenParams = {
    };
    const tokenResponse = await oauth2Client.getToken(tokenParams);
    const accessToken = tokenResponse.token.access_token;
    const headers = {
      Authorization: `Bearer ${accessToken}`,
      Accept: 'application/vnd.atlas.2023-01-01+json'
    }
    // Make API Request
    const response = await axios.get(baseUrl + apiURL, {
      headers: headers
    });

    console.log('Response data:', response.data);
  } catch (error) {
    console.error('Error during request:', error.message);
  }
}

fetchWithOAuth2();
```

**Step #3:** Set the environment variables in your terminal: 

```
set +o history # to disable history for credentials
export MONGODB_ATLAS_CLIENT_ID=your_client_id
export MONGODB_ATLAS_CLIENT_SECRET=your_client_secret
```

**Step #4:** Run example: 

```
node atlas-request.js
```

As a result, I should see the response from the API in the console.

#### Understanding the script

Similar to the Python example, the code will perform several steps that are common for OAuth. 

- Loading the environment variables: We retrieve the MONGODB\_ATLAS\_CLIENT\_ID and MONGODB\_ATLAS\_CLIENT\_SECRET variables from the environment.
- For the example, we have chosen to use the *simple-oauth2* library. The library allows us to automatically obtain and refresh OAuth2 tokens. To do that, we need to provide a client configuration:
    - `client_id` and `client_secret` from environment variables.
    - `auth.tokenHost` references OAuth Token API provided by Atlas *(/api/oauth/token)* We use that URL for token retrieval.
- Calling *simple-oauth2.getToken()* to fetch a new access token: On success, this retrieves the *access_token* from the token response.
- Making an API request: 
    - We need to set the `Authorization` header containing our freshly generated token. 
    - The endpoint can be changed to query different MongoDB Atlas API resources. 
    - During multiple requests, the access token might expire and result in a 401 HTTP status code.
        - You can configure your application to issue another access token upon expiry.

### Service accounts with Go applications

The [Atlas SDK Go](https://github.com/mongodb/atlas-sdk-go) provides OAuth authentication using Service Accounts, which is currently available as a preview feature. 

Additionally, developers can use the Service Account Management API to create, update, and delete service accounts directly from the SDK.

### Prerequisites

1. Ensure you have [Go 1.22](https://golang.org) or later installed on your machine. 
2. Create a *go.mod* file and install the required package.

```
go mod init example.com/service-accounts
go get go.mongodb.org/atlas-sdk/v20241023001/admin
```

To ensure you are using the latest version of SDK Go, please replace the v20241023001 version string with the latest version from the [SDK Go releases](https://github.com/mongodb/atlas-sdk-go/releases).

#### Creating Go example


**Step #1:** Create a new file named *atlas\_request.go* in the editor of your choice. 

**Step #2:** Paste the following content into the new file:

```golang
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"go.mongodb.org/atlas-sdk/v20241113001/admin"
)

// Example for Using Service Account for listing Atlas Projects.
func main() {
	// Fetch clientID and clientSecret from environment variables
	clientID := os.Getenv("MONGODB_ATLAS_CLIENT_ID")
	clientSecret := os.Getenv("MONGODB_ATLAS_CLIENT_SECRET")

	if clientID == "" || clientSecret == "" {
		log.Fatal("Missing required environment variables")
	}

	ctx := context.Background()
	sdk, err := admin.NewClient(
		admin.UseBaseURL(host),
            //Out-of-the-box support for OAuth in the SDK
		admin.UseOAuthAuth(ctx, clientID, clientSecret),
	)
	if err != nil {
		log.Fatalf("Error: %v", err)
	}
 
      orgs, _, err := sdk.OrganizationsApi.ListOrganizations(ctx).Execute()
	if err != nil {
           log.Fatalf("Error: %v", err)
	}
	if orgs.GetTotalCount() == 0 {
		log.Fatalf("no orgs")
	}
      fmt.Println("Successfully used Service Account")
}
```

**Step #3:** Set the environment variables in your terminal:

```
export MONGODB_ATLAS_CLIENT_ID=your_client_id
export MONGODB_ATLAS_CLIENT_SECRET=your_client_secret
export MONGODB_ATLAS_ORG=your_org_id
```

**Step #4:** Run the example:

```
go run atlas_request.go
```

As a result, you should see the *Successfully used Service Account* in your terminal.

The code is using the *admin.UseOAuthAuth(ctx, clientID, clientSecret)* method provided by the SDK to automatically authenticate using Service Accounts. No more actions are required.

Additionally, to authenticate, SDK Go provides an example of [Service Account Management API](https://github.com/mongodb/atlas-sdk-go/tree/main/examples/service_account_management) , which will enable you to manage Service Accounts. 

## Closing remarks

This tutorial demonstrated how to set up Service Accounts and interact with the Atlas API using SDK Go, Node.js, and Python. With these examples, you can integrate Atlas API operations into your applications written in those languages.

Service Accounts and the Atlas Administration API provide a new set of possibilities for managing your MongoDB Atlas resources. By leveraging OAuth2 with the Client Credentials flow, developers can integrate programmatic access into their applications and automation workflows while adhering to industry-standard security practices.

Whether you’re automating deployments, managing databases, or building operational tools, the Atlas Administration API, combined with Service Accounts, provides a robust foundation for seamless MongoDB Atlas integration.

**Warning:**

* Always safeguard your credentials using environment variables or secure storage. 
* Regularly rotate and revoke Service Account secrets to maintain security. 
* Explore the[ Atlas Go SDK](https://github.com/mongodb/atlas-sdk-go/), [Postman Collection](https://www.mongodb.com/developer/products/atlas/admin-api-postman/),  and [API documentation](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/) for more capabilities tailored to your use case.

Questions? Comments? Join us in the [MongoDB Developer Community](https://www.mongodb.com/community/forums/).


[1]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/bltda42878627b06672/679177974a780334086c1c81/image1.png

Wojciech Trocki

Content by Wojciech Trocki

MongoDB Atlas Authentication Using Service Accounts (OAuth)