Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas App Services
/
Authenticate & Manage Users
/
Authentication Providers

Okta JWT Authentication (Custom JWT)

On this page

  • Before You Begin
  • Create an Okta App & Authorization Server
  • Configure the Custom JWT authentication provider
  • Log in with an Okta JWT

You can configure the Custom JWT authentication provider to authenticate users that you manage with Okta.

Before You Begin

You will need the following to use Okta:

  • An Okta project. To learn more, refer to the Okta documentation.

  • An App Services App that does not already use Custom JWT authentication. To learn how to create a new App Services App, see Create an App.

  • If you're using the command line interface, you need App Services CLI to be installed and authenticated on your local system.

  • If you're using the Admin API, you need a MongoDB Atlas Admin API public/private key pair. The API key must have Project Owner permissions.

Create an Okta App & Authorization Server

Create an application in Okta that represents your client application. The type of application you create depends on your use case. For example, if you're building a web browser app, you might create a Single-Page Application (SPA) or Web application in Okta.

Once you've configured the application, create an authorization server in Okta that represents your App Services App. You can use any name and description. Set the server Audience to your App Services App's Client App ID. For example, myapp-abcde.

To learn more about how to set up an Okta application and authorization server, refer to Create an authorization server in the Okta documentation.

Configure the Custom JWT authentication provider

You can configure Custom JWT authentication from the UI or by modifying the underlying configuration files directly with the CLI or Admin API. Choose your preferred method below.

In the left navigation menu, click Authentication. Then click the Authentication Providers tab and select the Custom JWT provider.

Now you can configure the Custom JWT authentication provider to work with your Okta project.

  1. Click the toggle to enable the provider.

  2. Set Verification Method to Use a JWK URI. Specify your Okta Authorization Server's JWK URI in the JWK URI field.

    Your Okta JWK URI should resemble the following:

    https://<Your Okta Domain>/oauth2/<Your Authorization Server ID>/v1/keys

    Note

    You can get your exact JWK URI from the Okta UI by following the Metadata URI link for your Authorization server. Use the value listed in the jwks_uri field.

  3. Define Metadata Fields to map data from the Okta JWT to the corresponding App Services user account.

    You do not have to map metadata fields from the Okta JWT. However, you might find them useful for getting user information from Okta into your App. To learn more about metadata fields and how to configure them, see Custom JWT metadata fields .

  4. Leave the value of Audience blank.

  5. Click Save and deploy your changes

Run the following command, replacing the value of --remote with your App's Client App ID. This downloads a local copy of your App's latest configuration files and navigates to the configuration file directory, which uses the same name as your App.

appservices pull --remote "myapp-abcde"
cd myapp

Add a new Custom JWT authentication provider to your App's /auth/providers.json file. Use the following configuration as a template. Make sure to:

  • Replace the jwkURI value with your Okta Authorization Server's JWK URI.

  • Define Custom JWT metadata fields to map data from the Okta JWT. This is optional, however, you might find the field mapping useful for getting user information from Okta into your App.

/auth/providers.json
{
  "custom-token": {
    "name": "custom-token",
    "type": "custom-token",
    "disabled": false,
    "config": {
      "audience": [],
      "jwkURI": "https://<Your Okta Domain>/oauth2/<Your Authorization Server ID>/v1/keys",
      "useJWKURI": true
    },
    "secret_config": {
      "signingKeys": []
    },
    "metadata_fields": []
  }
}

Save your changes to /auth/providers.json. Then, push the updated configuration file to deploy your App:

appservices push

Add a new Custom JWT authentication provider to your App using the Create an authentication provider endpoint.

Use the following configuration as a template. Make sure to:

  • Specify your App's $PROJECT_ID and $APP_ID

  • Include an Admin API access token in the Authorization header.

  • Replace the jwkURI value in the request body with your Okta Authorization Server's JWK URI.

  • Define Custom JWT metadata fields to map data from the Okta JWT. This is optional, however, you might find the field mapping useful for getting user information from Okta into your App.

curl "https://services.cloud.mongodb.com/api/admin/v3.0/groups/$PROJECT_ID/apps/$APP_ID/auth_providers" \
  -X "POST" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom-token",
    "type": "custom-token",
    "disabled": false,
    "config": {
      "audience": [],
      "jwkURI": "https://<Your Okta Domain>/oauth2/<Your Authorization Server ID>/v1/keys",
      "useJWKURI": true
    },
    "secret_config": {
      "signingKeys": []
    },
    "metadata_fields": []
  }'

Log in with an Okta JWT

Once you've configured the Custom JWT authentication provider to use Okta, you can log in to your App Services App with an Okta JWT access token.

  1. Log the user into Okta. To learn how, see the relevant Okta SDK documentation for your platform and programming language.

  2. Get the user's Okta access token from the login response.

  3. Use the Okta access token to authenticate with Atlas App Services. You can start a session over HTTP or log in with an SDK. To learn how, see the docs for your SDK:

Back

Firebase (Custom JWT)

Next

Connect to MongoDB Data Sources