OAuth-Based Authentication and Authorization

OAuth 2.0 is an open standard for providing both authentication and authorization between two parties: the Authorization Server and the Resource Server.

OAuth requires that your MarkLogic app server is configured with SSL. Before configuring OAuth, you must create a certificate template then enable SSL on the app server that will use OAuth authentication.

OAuth Flow Types

MarkLogic Server supports two OAuth flow types:

• Resource server
• [v12.1.0 and up] Authorization code

Resource Server Flow

In the Resource server flow, the OAuth vendor acting as the external agent acts as the Authorization Server, and MarkLogic Server acts as the Resource Server.

Your client application must obtain an Access Token from the OAuth vendor to send to MarkLogic Server in the resource request header.

If MarkLogic Server receives a resource request without a valid Access Token, then it returns an error. It does not redirect the client to the OAuth vendor.

This diagram details the Resource server flow:

1. The client sends a resource request that includes the Access Token to the Resource Server (MarkLogic Server).

2. The Resource Server (MarkLogic Server) validates the Access Token.

3. The Resource Server (MarkLogic Server) sends the requested resources to the client.

Authorization Code Flow

[v12.1.0 and up]

In the Authorization code flow, the OAuth vendor acting as the external agent acts as the Authorization Server, and MarkLogic Server acts as the Resource Server.

Meanwhile, a MarkLogic app server that has a UI (such as the Admin Interface, Query Console, or Monitoring Dashboard) acts as the client.

If the MarkLogic app server acting as the client receives a resource request without a valid session, then it redirects the user to the OAuth vendor to authenticate and obtain an authorization code. The MarkLogic app server then exchanges that code for an Access Token using PKCE for security, obtains the requested resources from MarkLogic Server, and sets up a valid session for the user.

This diagram details the Authorization code flow:

1. The user sends a resource request to the client (a MarkLogic app server like the Admin Interface).

2. The client redirects the user to the authorization endpoint of the Authorization Server (the OAuth vendor acting as the external agent) to authenticate.

3. The user authenticates.

4. The user receives an authorization code from the authorization endpoint.

5. The authorization code is sent to the client (the Admin Interface).

6. The client sends the authorization code to the token server endpoint of the Authorization Server (the OAuth vendor).

7. The token server endpoint sends an Access Token to the client (the Admin Interface).

8. The client sends the user’s resource request that includes the Access Token to the Resource Server (MarkLogic Server).

9. The Resource Server sends the requested resources to the client (the Admin Interface).

10. The client sends the requested resources to the user.

11. The client sets the Access Token as a cookie for the user.

Session Behavior

MarkLogic Server creates a standard MarkLogic session after validating the Access Token. The session lifetime depends on how long the Access Token is configured to be valid on the OAuth vendor side.

Deploying Behind a Load Balancer

Deploying MarkLogic Server behind a load balancer requires session affinity (sticky sessions). Configure your load balancer to use the MarkLogic Server SessionID cookie for session affinity to ensure that requests from a user are routed to the same MarkLogic Server host that initiated the OAuth flow.

Security Recommendations

When using the Authorization code flow, follow these security recommendations:

• PKCE is automatic: MarkLogic Server automatically uses Proof Key for Code Exchange (PKCE) in the Authorization code flow. No additional configuration is needed on the MarkLogic Server side. Your OAuth vendor must be configured with PKCE enabled to complete the flow.

• Register redirect URIs: It is recommended to use an OAuth vendor that supports registering redirect URIs. Registering the exact redirect URI with your OAuth vendor prevents unauthorized redirection of authorization codes.

• Use a supported OAuth vendor: Use one of the supported OAuth vendors for the Authorization code flow. If you use an unsupported OAuth vendor, then ensure that it is secure and up to date with the OAuth 2.0 protocol, including support for PKCE and redirect URI validation.

Authentication and Authorization

Authentication occurs when the OAuth external agent validates the user, responding with an access token or authorization code.

Authorization occurs when MarkLogic Server validates the access token included in the request header and assigns to the temporary user any roles with external names that relate to a field that you configured in the external security object.

OAuth Access Tokens

MarkLogic Server uses JSON Web Tokens (JWT) as access tokens. The resource server validates these tokens locally through the JWT signature. The JWT signature is validated through JWT secrets.

MarkLogic Server supports both types of key encryption:

• Symmetric encryption uses the same key for both encryption and decryption:

  • Symmetric keys can be encoded using either Hex or Base64URL format.

• Asymmetric encryption uses a pair of keys: a public key for encryption and a private key for decryption:

  • Asymmetric keys must be PEM encoded.

Resource Request Header

To request resources from MarkLogic Server, you must include the access token in the request header Authorization tag in one of these formats:

• XML: <Authorization>Bearer {access token goes here}</Authorization>

• JSON: "Authorization": "Bearer {access token goes here}"

OAuth External Agents

MarkLogic Server supports configuring OAuth through the external agents listed in this section.

You can also attempt to configure through unsupported external agents. All fields needed to configure external security are explained in these sections:

• Reference: The External Security Configuration Page

• Reference: The App Server Configuration Page

• Reference: The User Configuration Page

• Reference: The Role Configuration Page