With Amazon Cognito

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

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

1. Register with Amazon Cognito to obtain your tenancy, called a user pool.

   • Note the user pool ID for external security object configuration.

2. Create your Amazon Cognito users and groups.

3. Register your application with Amazon Cognito.

   • Note the app client ID for external security object configuration.

4. Program your application to request this token.

5. Obtain public keys and their corresponding key IDs from Amazon Cognito.

   1. Go to https://cognito-idp.<Region>.amazonaws.com/<userPoolId>/.well-known/jwks.json. On the page that appears, each entry in the keys array is a public key containing kid as the key ID.

   2. Convert each entry in the keys array from JWK to PEM format using any public access tool.

   • Note the key ID for external security object configuration.

   • Note the PEM-converted public key for external security object configuration.

   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.

   Amazon Cognito 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 Amazon Cognito map to fields on the MarkLogic Server External Security configuration page in the Admin Interface and includes the values used in the example setups:

   Amazon Cognito element	External Security configuration page field
   App client ID EXAMPLE: 19vomjilg46bbvcpp9qcmeacoc	OAuth Client ID
   User pool ID EXAMPLE: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_fMQqTCMd9	OAuth JWT Issuer URI
   Name claim EXAMPLE: username	OAuth Username Attribute
   Groups claim EXAMPLE: cognito:groups	OAuth Role Attribute
   JWT Secrets           kid           keys array EXAMPLE (one kid/keys pair): kid:           fBwvWl/oWKPB9fyhXtZ8EqAhAmljMhk4hW2dd/zpFYs= keys:           -----BEGIN PUBLIC KEY-----           <PEM-converted key>           -----END PUBLIC KEY----- Note: The JWT Secrets field secures both symmetric and asymmetric signature keys.	OAuth JWT Secrets            Secret Key ID            Secret Value
   (Optional) JWKS Endpoint Path EXAMPLE: https://cognito-idp.us-east-1.amazonaws.com/fMQqTCMd9/.well-known/jwks.json Note: You can specify a JWKS URI to validate incoming JWT access tokens with JWKS instead of with JWT Secrets signature keys.	OAuth JWKS URI

   You will also assign Amazon Cognito group names to MarkLogic Server roles as external names. Amazon Cognito groups are analogous to MarkLogic Server roles.

   EXAMPLE (of one): GroupFoo

   You can now set up MarkLogic Server integration through one of the methods described in this section.