With PingIdentity

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

Steps for All Flows

To set up the PingFederate server 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 PingIdentity to obtain a tenancy.

2. Configure a database to store user information.

   1. Set up users.

   2. Set up roles.

      • Note the roles names to configure as external names during role configuration.

3. Make sure that the proper IdP Adapter Mapping is properly configured with your system.

4. If you are using an asymmetric algorithm to sign JWT access tokens, then create or import the key certificate into the PingFederate Server.

5. Make sure that access tokens are properly configured to use JSON Web Tokens.

   1. Create an Access Token Manager that uses JSON Web Tokens as the Token Type.

      • Note the Token Type for external security object configuration.

   2. Ensure that a proper JWT Secret is configured for the token manager.

      To use a symmetric algorithm like HS256 to sign, enter the symmetric key under the symmetric keys section.

      To use an asymmetric algorithm like RS256 to sign, you need to have already inserted the key certificate into PingFederate (Step 3).

      • Note the value of JWS Algorithm for external security object configuration.

      • Note the value of Active Symmetry Key ID for external security object configuration.

      • Note the value of JWT Secret for external security object configuration.

      • (Optional) (Asymmetric algorithm) Note the value of JWKS Endpoint Path under Advanced fields JWKS for external security object configuration.

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

      Note:
      
      If you are using an asymmetric algorithm, then you can specify a JWKS URI to validate incoming JWT access tokens with JWKS instead of with JWT Secrets signature keys.

   3. Create the JWT access token's payload structure to include claims containing username, roles, and (Optional) privilege information:

      Copy

        {
          "payload": {
            "username": <Username info>,
            "roles": <Roles info>,
            "privileges": <Privileges info>
          }
        }

      • Note the names of the elements from this payload for external security object configuration: username, roles, and (Optional) privileges.

6. Create an OAuth 2.0 client by setting the Access Token Manager for the OAuth client to the Access Token Manager created in Step 5a.

   • Note the OAuth client name that you chose for external security object configuration.

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:

7. Configure a redirect URI for your OAuth client in PingFederate under OAuth Settings > Client Management > Redirect URIs:

   • 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.

8. Note your PingFederate server's OAuth 2.0 endpoints for external security object configuration:

   • Authorization endpoint: https://<your-pingfederate-host>/as/authorization.oauth2

   • Token endpoint: https://<your-pingfederate-host>/as/token.oauth2

9. Generate or note the client secret for your OAuth client:

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

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

    • Note the scope string for external security object configuration.

Your PingFederate Server 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 the PingFederate server map to fields on the MarkLogic Server External Security configuration page 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 each role name returned in the JWT access token payload under the roles claim to a corresponding MarkLogic Server role as its external name.

EXAMPLE: external-user-role

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.