Powered by Zoomin Software. For more details please contactZoomin

Secure MarkLogic Server

Table of Contents

With Amazon Cognito

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
Print
  • Last Updated: September 10, 2026
  • 3 minute read
    • MarkLogic Server
    • Version 12.0
    • Documentation

You can set up MarkLogic Server to use the vendor Amazon Cognito as your OAuth external agent.

Steps for All Flows

To set up Amazon Cognito to properly interface with MarkLogic Server, follow these steps for all OAuth flow types while noting the information that you will need later as you go along:

  1. Register with Amazon Cognito to obtain your tenancy, called a user pool.

    • Note the user pool ID for external security object configuration.

  2. Create your Amazon Cognito users and groups.

  3. Register your application with Amazon Cognito.

    • Note the app client ID for external security object configuration.

  4. Program your application to request this token.

  5. Obtain public keys and their corresponding key IDs from Amazon Cognito.

    1. Go to https://cognito-idp.<Region>.amazonaws.com/<userPoolId>/.well-known/jwks.json. On the page that appears, each entry in the keys array is a public key containing kid as the key ID.

    2. Convert each entry in the keys array from JWK to PEM format using any public access tool.

    • Note the key ID for external security object configuration.

    • Note the PEM-converted public key for external security object configuration.

Note:

The JWT Secrets field secures both symmetric and asymmetric signature keys.

Note:

You can specify a JWKS URI to validate incoming JWT access tokens with JWKS instead of with JWT Secrets signature keys.

Additional Steps for Authorization Code Flow

[v12.1.0 and up]

If you are configuring the Authorization code flow (for browser-based UI app servers), then complete these additional steps:

  1. Configure a callback URL (redirect URI) for your app client under App integration > App client settings:

    • The callback URL should point to your MarkLogic app server (for example, https://marklogic.example.com:8003).

    • Note the callback URL for external security object configuration.

  2. Note your user pool's OAuth 2.0 endpoints for external security object configuration (derived from your user pool domain):

    • Authorization endpoint: https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/authorize

    • Token endpoint: https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token

  3. Generate a client secret for your app client (select "Generate a client secret" during app client creation or update):

    • Note the client secret value for external security object configuration.

  4. Configure the allowed OAuth scopes for your app client (for example, openid profile).

    • Note the scope string for external security object configuration.

Amazon Cognito is now set up to integrate with MarkLogic Server, and you have the information that you need to configure MarkLogic Server external security.

The following tables show how the elements that you noted from Amazon Cognito map to fields on the MarkLogic Server External Security configuration page in the Admin Interface and include the values used in the example setups.

Fields for All Flows

This table applies to all OAuth flow types:

Amazon Cognito element

External Security configuration page field

App client ID

EXAMPLE: 19vomjilg46bbvcpp9qcmeacoc

OAuth Client ID

User pool ID

EXAMPLE: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_fMQqTCMd9

OAuth JWT Issuer URI

Name claim

EXAMPLE: username

OAuth Username Attribute

Groups claim

EXAMPLE: cognito:groups

OAuth Role Attribute

JWT Secrets

          kid

          keys array

EXAMPLE (one kid/keys pair):

kid:

          fBwvWl/oWKPB9fyhXtZ8EqAhAmljMhk4hW2dd/zpFYs=

keys:

          -----BEGIN PUBLIC KEY-----

          <PEM-converted key>

          -----END PUBLIC KEY-----

Note:

The JWT Secrets field secures both symmetric and asymmetric signature keys.

OAuth JWT Secrets

           Secret Key ID

           Secret Value

(Optional)
JWKS Endpoint Path

EXAMPLE: https://cognito-idp.us-east-1.amazonaws.com/fMQqTCMd9/.well-known/jwks.json

Note:

You can specify a JWKS URI to validate incoming JWT access tokens with JWKS instead of with JWT Secrets signature keys.

OAuth JWKS URI

You will also assign Amazon Cognito group names to MarkLogic Server roles as external names. Amazon Cognito groups are analogous to MarkLogic Server roles.

EXAMPLE (of one): GroupFoo

Additional Fields for Authorization Code Flow

[v12.1.0 and up]

Note:

To securely set up the Authorization code flow with an OAuth vendor, see Security Recommendations.

If you are using the Authorization code flow, then these additional fields are required:

Amazon Cognito element

External Security configuration page field

Authorization endpoint

EXAMPLE: https://mypool.auth.us-east-1.amazoncognito.com/oauth2/authorize

OAuth Authorization Server URI

Token endpoint

EXAMPLE: https://mypool.auth.us-east-1.amazoncognito.com/oauth2/token

OAuth Token Server URI

Callback URL (Redirect URI)

EXAMPLE: https://marklogic.example.com:8003

OAuth Redirect URI

Allowed OAuth scopes

EXAMPLE: openid profile

OAuth Scope

Client secret

EXAMPLE: <your-client-secret-value>

OAuth Client Secret

Client authentication method

EXAMPLE: Client secret

OAuth Client Authentication Method

You can now set up MarkLogic Server integration through one of the methods described in this section.

Alert