With PingIdentity

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

To set up the PingFederate server to properly interface with MarkLogic Server, noting, as you go along, the information that you will need later, follow these steps:

Register with PingIdentity to obtain a tenancy.
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.
Make sure that the proper IdP Adapter Mapping is properly configured with your system.
If you are using an asymmetric algorithm to sign JWT access tokens, then create or import the key certificate into the PingFederate Server.
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) Note the value of JWKS Endpoint Path under Advanced fields JWKS for external security object configuration.
3. Create the JWT access token's payload structure to include claims containing username, roles, and (Optional) privilege information:
```
{
  "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.
Create an OAuth 2.0 client by setting the Access Token Manager for the OAuth client to the Access Token Manager created in Step 5.1.
- Note the OAuth client name that you chose 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.

This table shows how the elements that you noted from the PingFederate server map to fields on the MarkLogic Server External Security configuration page and to XQuery and REST API code schema elements. This table also includes the values used in the example setups:

PingIdentity element	External Security configuration page field	Schema element
OAuth Client Name EXAMPLE: `PingExampleClientID`	OAuth Client ID	`sec:oauth-client-id`
Token Type EXAMPLE: `JSON Web Tokens`	OAuth Token Type	`sec:oauth-token-type`
`username`	OAuth Username Attribute	`sec:oauth-username-attribute`
`roles`	OAuth Role Attribute	`sec:ouath-role-attribute`
(Optional) `privileges`	OAuth Privilege Attribute	`sec:oauth-privilege-attribute`
JWS Algorithm EXAMPLE: `HS256` (Symmetric)	OAuth JWT Algorithm	`sec:oauth-jwt-alg`
JWT Secret Active Summary Key ID JWT Secret EXAMPLE: Active Summary Key ID: `PingExampleKeyID` JWT Secret (for Symmetric JWS Algorithm): [v11.2.0] <Hex-encoded JWT Secret> [v11.3.0 and up] <Hex- or Base64URL-encoded JWT Secret>	OAuth JWT Secrets Secret Key ID Secret Value	`sec:oauth-jwt-secrets` `sec:oauth-jwt-key-id` `sec:oauth-jwt-secret-value`
(Optional) JWKS Endpoint Path EXAMPLE: `https://localhost/pf/JWKS`	OAuth JWKS URI	`sec:oauth-jwks-uri`

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

Set up MarkLogic Server integration through one of the methods described in this section.

In this section:

Securing MarkLogic Server

With PingIdentity

Search results