Skip to main content

Securing MarkLogic Server

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.

The flow is shown in this diagram, where the Authorization Server is the external agent (the OAuth vendor) and the Resource Server is a MarkLogic Server app server:

Flow diagram for OAuth-based authentication and authorization

  1. The user sends their credentials to the client.

  2. The client sends the user credentials to the Authorization Server: the OAuth vendor acting as the external agent.

  3. The Authorization Server validates the user credentials.

  4. The Authorization Server sends an Access Token to the client.

  5. The client sends a resource request that includes the Access Token to the Resource Server: MarkLogic Server.

  6. The Resource Server validates the Access Token.

  7. The Resource Server sends the requested resources to the client.

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

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.

There are two types of access tokens:

  • Internally managed reference tokens: The resource server sends these tokens to the Introspection Endpoint of the authorization server for validation.

    Note

    MarkLogic Server deprecated support for this token type in v11.2.0.

  • JSON Web Tokens (JWT): The resource server validates these tokens locally through the JWT signature. The JWT signature is validated through JWT secrets.

    Note

    MarkLogic Server began supporting this token type in v11.2.0.

    MarkLogic Server supports both types of key encryption:

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

      • [v11.2.0] Symmetric keys must be Hex encoded.

      • [v11.3.0 and up] Symmetric keys can be either Hex encoded or Base64URL encoded.

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

      • Asymmetric keys must be PEM encoded.

    Note

    MarkLogic Server stores the JWT secrets in the internal keystore.

    If you set up a foreign cluster with your Security database replicated to the foreign cluster, then you must sync your local and foreign internal keystores after creating OAuth external security objects on your local cluster. Sync them by using xdmp:keystore-export() to export the internal keystore from your local cluster then using xdmp:keystore-import() to import the internal keystore into your foreign cluster.

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}"

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

Note

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

In this section: