Through the REST API

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

1. Create the external security object with code like this:

   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.

   Note:
   
   The fields oauth-authorization-server-uri, oauth-token-server-uri, oauth-redirect-uri, oauth-scope, oauth-client-authentication-method, and oauth-client-secret are only required when using the Authorization code flow. These fields configure the MarkLogic app-server to act as an OAuth client. They are not needed for the Resource server flow.

   Resource server flow example (JavaScript/JSON)

   Copy

   curl -X POST --anyauth -k -u <username>:<password> -H "Content-Type:application/json" \
   -d @create_extsec.json http://<machine URI>:8002/manage/v2/external-security
   

   Contents of create_extsec.json

   Copy

   {
     "external-security-name": "PingIdentityExampleOAuth",
     "description": "PingIdentity external security object for OAuth",
     "authentication": "oauth",
     "cache-timeout": "300",
     "authorization": "oauth",
     "oauth-server": {
       "oauth-vendor": "Ping Identity",
       "oauth-flow-type": "Resource server",
       "oauth-client-id": "PingExampleClientID",
       "oauth-token-type": "JSON Web Tokens",
       "oauth-username-attribute": "username",
       "oauth-role-attribute": "roles",
       "oauth-privilege-attribute": "privileges",
       "oauth-jwt-issuer-uri": "",
       "oauth-jwt-alg": "RS256",
       "oauth-jwt-secret": [
           {
               "oauth-jwt-key-id": "PingExampleKeyID",
               "oauth-jwt-secret-value": "<RS256 JWT Secret Value>"
           }
       ],
       "oauth-jwks-uri": "https://localhost/pf/JWKS"
     }
   }
   

   Authorization code flow example (JavaScript/JSON)

   Copy

   curl -X POST --anyauth -k -u <username>:<password> -H "Content-Type:application/json" \
   -d @create_extsec_authcode.json http://<machine URI>:8002/manage/v2/external-security
   

   Contents of create_extsec_authcode.json

   Copy

   {
     "external-security-name": "PingIdentityExampleOAuthClient",
     "description": "PingIdentity external security object for OAuth Authorization Code flow",
     "authentication": "oauth",
     "cache-timeout": "300",
     "authorization": "oauth",
     "oauth-server": {
       "oauth-vendor": "Ping Identity",
       "oauth-flow-type": "Authorization code",
       "oauth-client-id": "<application-client-id>",
       "oauth-token-type": "JSON Web Tokens",
       "oauth-username-attribute": "username",
       "oauth-role-attribute": "roles",
       "oauth-privilege-attribute": "privileges",
       "oauth-jwt-issuer-uri": "<jwt-issuer-uri>",
       "oauth-jwt-alg": "RS256",
       "oauth-jwt-secret": [
           {
               "oauth-jwt-key-id": "<key-id>",
               "oauth-jwt-secret-value": "<RS256 JWT Secret Value>"
           }
       ],
       "oauth-jwks-uri": "https://localhost/pf/JWKS",
       "oauth-authorization-server-uri": "<oauth-server-authorize-endpoint>",
       "oauth-token-server-uri": "<oauth-server-token-endpoint>",
       "oauth-redirect-uri": "https://<marklogic-host>:<app-server-port>",
       "oauth-scope": "openid profile",
       "oauth-client-authentication-method": "Client secret",
       "oauth-client-secret": "<client-secret-value>"
     }
   }
   

   Resource server flow example (XQuery/XML)

   Copy

   curl -X POST --anyauth -k -u <username>:<password> -H "Content-Type:application/xml" \
   -d @create_extsec.xml http://<machine URI>:8002/manage/v2/external-security
   

   Contents of create_extsec.xml

   Copy

   <external-security-properties xmlns="http://marklogic.com/manage/external-security/properties">
       <external-security-name>PingIdentityExampleOAuth</external-security-name>
       <description>PingIdentity external security object for OAuth</description>
       <authentication>oauth</authentication>
       <cache-timeout>300</cache-timeout>
       <authorization>oauth</authorization>
       <oauth-server>
           <oauth-vendor>Ping Identity</oauth-vendor>
           <oauth-flow-type>Resource server</oauth-flow-type>
           <oauth-client-id>PingExampleClientID</oauth-client-id>
           <oauth-token-type>JSON Web Tokens</oauth-token-type>
           <oauth-username-attribute>username</oauth-username-attribute>
           <oauth-role-attribute>roles</oauth-role-attribute>
           <oauth-privilege-attribute>privileges</oauth-privilege-attribute>
           <oauth-jwt-alg>RS256</oauth-jwt-alg>
           <oauth-jwt-secrets>
               <oauth-jwt-secret>
                   <oauth-jwt-key-id>PingExampleKeyID</oauth-jwt-key-id>
                   <oauth-jwt-secret-value>RS256 JWT Secret Value</oauth-jwt-secret-value>
               </oauth-jwt-secret>
           </oauth-jwt-secrets>
           <oauth-jwks-uri>https://localhost/pf/JWKS</oauth-jwks-uri>
       </oauth-server>
   </external-security-properties>
   

   Authorization code flow example (XQuery/XML)

   Copy

   curl -X POST --anyauth -k -u <username>:<password> -H "Content-Type:application/xml" \
   -d @create_extsec_authcode.xml http://<machine URI>:8002/manage/v2/external-security
   

   Contents of create_extsec_authcode.xml

   Copy

   <external-security-properties xmlns="http://marklogic.com/manage/external-security/properties">
       <external-security-name>PingIdentityExampleOAuthClient</external-security-name>
       <description>PingIdentity external security object for OAuth Authorization Code flow</description>
       <authentication>oauth</authentication>
       <cache-timeout>300</cache-timeout>
       <authorization>oauth</authorization>
       <oauth-server>
           <oauth-vendor>Ping Identity</oauth-vendor>
           <oauth-flow-type>Authorization code</oauth-flow-type>
           <oauth-client-id>&lt;application-client-id&gt;</oauth-client-id>
           <oauth-token-type>JSON Web Tokens</oauth-token-type>
           <oauth-username-attribute>username</oauth-username-attribute>
           <oauth-role-attribute>roles</oauth-role-attribute>
           <oauth-privilege-attribute>privileges</oauth-privilege-attribute>
           <oauth-jwt-issuer-uri>&lt;jwt-issuer-uri&gt;</oauth-jwt-issuer-uri>
           <oauth-jwt-alg>RS256</oauth-jwt-alg>
           <oauth-jwt-secrets>
               <oauth-jwt-secret>
                   <oauth-jwt-key-id>&lt;key-id&gt;</oauth-jwt-key-id>
                   <oauth-jwt-secret-value>&lt;RS256 JWT Secret Value&gt;</oauth-jwt-secret-value>
               </oauth-jwt-secret>
           </oauth-jwt-secrets>
           <oauth-jwks-uri>https://localhost/pf/JWKS</oauth-jwks-uri>
           <oauth-authorization-server-uri>&lt;oauth-server-authorize-endpoint&gt;</oauth-authorization-server-uri>
           <oauth-token-server-uri>&lt;oauth-server-token-endpoint&gt;</oauth-token-server-uri>
           <oauth-redirect-uri>https://&lt;marklogic-host&gt;:&lt;app-server-port&gt;</oauth-redirect-uri>
           <oauth-scope>openid profile</oauth-scope>
           <oauth-client-authentication-method>Client secret</oauth-client-authentication-method>
           <oauth-client-secret>&lt;client-secret-value&gt;</oauth-client-secret>
       </oauth-server>
   </external-security-properties>
   

2. Create any HTTP, XDBC, WebDAV, or ODBC app servers that you wish to configure with this external security object.

3. Configure your app servers to use this external security object with code like this:

   JSON application

   Copy

   curl -X PUT --anyauth -k -u <username>:<password> -H "Content-type:application/json" \
   -d '{"external-security": "PingIdentityExampleOAuth", \
   "internal-security": false, \
   "authentication": "oauth"}' \
    http://<machine URI>:8002/manage/v2/servers/<app server name>/properties?group-id=Default
   

   XML application

   Copy

   curl -X PUT --anyauth -k -u <username>:<password> -H "Content-type:application/xml" \
   -d '<http-server-properties xmlns="http://marklogic.com/manage"> \
   <external-security>"PingIdentityExampleOAuth"</external-security> \
   <internal-security>false</internal-security> \
   <authentication>oauth</authentication> \
   </http-server-properties>' \
   http://<machine URI>:8002/manage/v2/servers/<app server name>/properties?group-id=Default
   

4. Assign external names to your desired roles with code like this:

   Note:
   
   The external names are the values returned under the role attribute of the access token payload.

   JSON application

   Copy

   curl -X PUT --anyauth -k -u <username>:<password> -H "Content-type:application/json" \
   -d '{"external-name": "external-user-role"}' \
   http://<machine URI>:8002/manage/v2/roles/<MarkLogic Server role name like manage-user>/properties
   

   XML application

   Copy

   curl -X PUT --anyauth -k -u <username>:<password> -H "Content-type:application/xml" \
   -d '<role-properties xmlns="http://marklogic.com/manage/role/properties"> \
   <external-names> \
   <external-name>"external-user-role"</external-name> \
   </external-names> \
   </role-properties>' http://<machine URI>:8002/manage/v2/roles/<MarkLogic Server role name like manage-user>/properties
   

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