Through the Admin Interface

To set up OAuth-based authentication and authorization with PingIdentity through the Admin Interface, follow these steps:

1. Create your external security object by setting these fields on the External Security configuration page and clicking OK:

   Field	Setting
   External Security Name	Enter a descriptive name for this external security object that identifies the external agent. EXAMPLE: PingIdentityExampleOAuth
   Description	(Optional) Enter a description for this external security object. EXAMPLE: PingIdentity external security object for OAuth
   Authentication	Choose oauth from the dropdown. Setting this field to oauth makes the OAuth Server fields available.
   Cache Timeout	Enter a number in seconds after which you want MarkLogic Server to re-authenticate the user with your OAuth external agent instead of with the credentials stored in the cache.. EXAMPLE: 300 (default kept) Note: Clear the cache by calling either sec.externalSecurityClearCache() or sec:external-security-clear-cache().
   Authorization	Choose oauth from the dropdown.

   OAuth Server fields:

   Note:
   
   The Admin Interface currently displays all OAuth fields regardless of which OAuth Flow Type is selected. The fields that you must complete depend on the OAuth Flow Type that you select.

   Fields for All Flows

   Field	Setting
   OAuth Flow Type	Choose Resource server if MarkLogic Server is validating access tokens sent by external clients. Choose Authorization code if MarkLogic app servers are acting as OAuth clients (for example, to enable single sign-on for the Admin Interface or Query Console). Do not choose Client credentials. That option was deprecated in MarkLogic 12.0 and removed in MarkLogic 12.1.
   OAuth Vendor	Choose Ping Identity from the dropdown.
   OAuth Client ID	Enter the name of the OAuth client that you created. EXAMPLE: PingExampleClientID
   OAuth Token Type	Choose JSON Web Tokens from the dropdown.
   OAuth Username Attribute	username
   OAuth Role Attribute	roles
   OAuth Privilege Attribute	(Optional) privileges
   OAuth JWT Algorithm	Choose RS256 from the dropdown.
   OAuth JWT Secrets	Enter the key ID into the left field as the Secret Key ID and the public key in PEM format into the right field as the Secret Value. To enter more secrets, click Add Secret to expose additional field pairs. EXAMPLE: Secret Key ID = PingExampleKeyID Secret Value = <Hex-encoded JWT Secret> <Hex- or Base64URL-encoded JWT Secret> Note: The JWT Secrets field secures both symmetric and asymmetric signature keys.
   OAuth JWKS URI	(Optional) The JSON Web Key Set endpoint for obtaining JSON Web Keys. This URI must support TLS (HTTPS) or be a loopback URI. EXAMPLE: https://localhost/pf/JWKS 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.

   Additional Fields for Authorization Code Flow

   [v12.1.0 and up]

   The following fields are required only when OAuth Flow Type is set to Authorization code. These fields configure the MarkLogic app server to act as an OAuth client, enabling single sign-on for UI applications such as the Admin Interface and Query Console. See Authorization Code Flow.

   Field	Setting
   OAuth Authorization Server URI	Enter the endpoint on the OAuth server where end users are redirected to initiate the Authorization code flow. EXAMPLE: https://<oauth-server>/authorize
   OAuth Token Server URI	Enter the endpoint on the OAuth server where MarkLogic Server exchanges an authorization code for an access token. EXAMPLE: https://<oauth-server>/token
   OAuth Redirect URI	Enter the URI that the OAuth server redirects the browser back to after authentication. This URI must match a redirect URI registered with your OAuth vendor. This URI cannot include wildcards or URL fragments. EXAMPLE: https://<marklogic-host>:<app-server-port>
   OAuth Scope	(Optional) Enter the scope parameter included in the authorization request to the OAuth server. EXAMPLE: openid profile
   OAuth Client Authentication Method	Choose from the dropdown the method for MarkLogic Server to use to authenticate with the OAuth server when requesting tokens. EXAMPLE: Client secret
   OAuth Client Secret	Enter the client secret used for authentication with the OAuth server. This value is stored securely in the MarkLogic Server internal KMS. Note: This field is used only to import the client secret value. Once this value is stored, it is referenced by an internal ID and cannot be retrieved.

2. Configure your desired app servers to use this external security object by setting these fields on each App Server configuration page and clicking OK:

   Field	Setting
   Authentication	Choose oauth from the dropdown.
   Internal Security	Click the false radio button.
   External Securities dropdown	Choose from the dropdown the External Security Name that you gave to your external security object in the previous step. Choose only one. EXAMPLE: PingIdentityExampleOAuth

3. Assign the external name to your desired roles by setting this field on each Role configuration page and clicking OK:

   Field	Setting
   External Name	Enter the external role name returned in the roles attribute of the JWT token payload that corresponds to this role. EXAMPLE: external-user-role

MarkLogic Server is now set up for OAuth-based authentication and authorization with PingIdentity.