Powered by Zoomin Software. For more details please contactZoomin

Secure MarkLogic Server

Table of Contents

Through the REST API

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
Print
  • Last Updated: September 10, 2026
  • 3 minute read
    • MarkLogic Server
    • Version 12.0
    • Documentation

To set up OAuth-based authentication and authorization with Amazon Cognito 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:

    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 required only 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)

    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

    {
"external-security-name": "AmazonCognitoExampleOAuth",
"description": "Amazon Cognito external security object for OAuth",
"authentication": "oauth",
"cache-timeout": "300",
"authorization": "oauth",
"oauth-server": {
"oauth-vendor": "Amazon Cognito",
"oauth-flow-type": "Resource server",
"oauth-client-id": "19vomjilg46bbvcpp9qcmeacoc",
"oauth-token-type": "JSON Web Tokens",
"oauth-username-attribute": "username",
"oauth-role-attribute": "cognito:groups",
"oauth-jwt-issuer-uri": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_fMQqTCMd9",
"oauth-jwt-alg": "RS256",
"oauth-jwt-secret": [
    {
        "oauth-jwt-key-id": "fBwvWl/oWKPB9fyhXtZ8EqAhAmljMhk4hW2dd/zpFYs=ID",
        "oauth-jwt-secret-value": "-----BEGIN PUBLIC KEY-----<PEM-converted RS256 JWT Secret Value>-----END PUBLIC KEY-----"
    }
],
"oauth-jwks-uri": ""
}
}

    Authorization code flow example (JavaScript/JSON)

    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

    {
"external-security-name": "AmazonCognitoExampleOAuthClient",
"description": "Amazon Cognito external security object for OAuth Authorization Code flow",
"authentication": "oauth",
"cache-timeout": "300",
"authorization": "oauth",
"oauth-server": {
"oauth-vendor": "Amazon Cognito",
"oauth-flow-type": "Authorization code",
"oauth-client-id": "<application-client-id>",
"oauth-token-type": "JSON Web Tokens",
"oauth-username-attribute": "username",
"oauth-role-attribute": "cognito:groups",
"oauth-jwt-issuer-uri": "<jwt-issuer-uri>",
"oauth-jwt-alg": "RS256",
"oauth-jwt-secret": [
    {
        "oauth-jwt-key-id": "<key-id>",
        "oauth-jwt-secret-value": "-----BEGIN PUBLIC KEY-----<PEM-converted key>-----END PUBLIC KEY-----"
    }
],
"oauth-jwks-uri": "",
"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)

    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

    <external-security-properties xmlns="http://marklogic.com/manage/external-security/properties">
<external-security-name>AmazonCognitoExampleOAuth</external-security-name>
<description>Amazon Cognito external security object for OAuth</description>
<authentication>oauth</authentication>
<cache-timeout>300</cache-timeout>
<authorization>oauth</authorization>
<oauth-server>
    <oauth-vendor>Amazon Cognito</oauth-vendor>
    <oauth-flow-type>Resource server</oauth-flow-type>
    <oauth-client-id>19vomjilg46bbvcpp9qcmeacoc</oauth-client-id>
    <oauth-token-type>JSON Web Tokens</oauth-token-type>
    <oauth-username-attribute>username</oauth-username-attribute>
    <oauth-role-attribute>cognito:groups</oauth-role-attribute>
    <oauth-jwt-issuer-uri>https://cognito-idp.us-east-1.amazonaws.com/us-east-1_fMQqTCMd9</oauth-jwt-issuer-uri>
    <oauth-jwt-alg>RS256</oauth-jwt-alg>
    <oauth-jwt-secrets>
        <oauth-jwt-secret>
            <oauth-jwt-key-id>fBwvWl/oWKPB9fyhXtZ8EqAhAmljMhk4hW2dd/zpFYs=</oauth-jwt-key-id>
            <oauth-jwt-secret-value>-----BEGIN PUBLIC KEY-----<PEM-converted RS256 JWT Secret Value>-----END PUBLIC KEY-----</oauth-jwt-secret-value>
        </oauth-jwt-secret>
    </oauth-jwt-secrets>
    <oauth-jwks-uri></oauth-jwks-uri>
</oauth-server>
</external-security-properties>

    Authorization code flow example (XQuery/XML)

    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

    <external-security-properties xmlns="http://marklogic.com/manage/external-security/properties">
<external-security-name>AmazonCognitoExampleOAuthClient</external-security-name>
<description>Amazon Cognito external security object for OAuth Authorization Code flow</description>
<authentication>oauth</authentication>
<cache-timeout>300</cache-timeout>
<authorization>oauth</authorization>
<oauth-server>
    <oauth-vendor>Amazon Cognito</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>cognito:groups</oauth-role-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>-----BEGIN PUBLIC KEY-----&lt;PEM-converted key&gt;-----END PUBLIC KEY-----</oauth-jwt-secret-value>
        </oauth-jwt-secret>
    </oauth-jwt-secrets>
    <oauth-jwks-uri></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

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

    XML application

    curl -X PUT --anyauth -k -u <username>:<password> -H "Content-type:application/xml" \
-d '<http-server-properties xmlns=”http://marklogic.com/manage”> \
<external-security>AmazonCognitoExampleOAuth</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:

    JSON application

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

    XML application

    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>GroupFoo</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 Amazon Cognito.

Alert