With Microsoft Entra

You can set up MarkLogic Server to use the vendor Microsoft Entra (formerly Azure Active Directory) as your OAuth external agent.

Steps for All Flows

To set up Microsoft Entra 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 Microsoft Entra to obtain a tenancy.

2. Create groups and users:

   1. Create users through the Users page.

   2. Create groups through the Groups page.

      • Note the group UUIDs. You will use these as external names during role configuration.

   3. Add the created users to the proper groups.

3. Register your application with Microsoft Entra:

   • Note the Application ID URI for external security object configuration.

   • Note the Tenant ID for external security object configuration.

4. Create a scope for your application.

5. Customize the payload of the JWT Token to include groups by changing your application’s Manifest section optionalClaims field to this:

   Copy

   "optionalClaims": {
           "idToken": [
               {
                   "name": "groups",
                   "source": null,
                   "essential": false,
                   "additionalProperties": []
               }
           ],
           "accessToken": [
               {
                   "name": "groups",
                   "source": null,
                   "essential": false,
                   "additionalProperties": []
               }
           ],
           "saml2Token": [
               {
                   "name": "groups",
                   "source": null,
                   "essential": false,
                   "additionalProperties": []
               }
           ]
       }
   

6. Program your application to request this token.

7. Obtain public keys and their corresponding key IDs from Microsoft Entra:

   1. Go to https://login.microsoftonline.com/<your-tenant-UUID>/discovery/v2.0/keys. 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:

8. Register a redirect URI for your application in Microsoft Entra under Authentication > Platform configurations > Web:

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

   • Note the redirect URI for external security object configuration.

9. Note your application's OAuth 2.0 endpoints for external security object configuration (found under Endpoints in the App registration overview):

   • Authorization endpoint: https://login.microsoftonline.com/<your-tenant-UUID>/oauth2/v2.0/authorize

   • Token endpoint: https://login.microsoftonline.com/<your-tenant-UUID>/oauth2/v2.0/token

10. Generate a client secret under Certificates & secrets > Client secrets > New client secret:

    • Note the client secret value for external security object configuration. You will not be able to retrieve it later.

11. Define the scopes your application needs under API permissions (for example, openid profile).

    • Note the scope string for external security object configuration.

Microsoft Entra 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 Microsoft Entra 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:

You will also assign Microsoft Entra group UUIDs to MarkLogic Server roles as external names. Microsoft Entra groups are analogous to MarkLogic Server roles.

EXAMPLE (of one): 7228762e-cb30-428a-ae1a-3a8cf9e2f728

Additional Fields for Authorization Code Flow

[v12.1.0 and up]

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

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