JWT authentication and authorization for Amazon OpenSearch Service

Amazon OpenSearch Service now allows you to use JSON Web Tokens (JWTs) for authentication and authorization. JWTs are JSON-based access tokens used to grant single sign-on (SSO) access. You can use JWTs in OpenSearch Service to create single sign-on tokens to validate requests to your OpenSearch Service domain. To use JWTs, you must have fine-grained access control enabled, and you must provide a valid RSA or ECDSA PEM formatted public key. For more information on fine-grained access control, see Fine-grained access control in Amazon OpenSearch Service.

You can configure JSON Web Tokens by using the OpenSearch Service console, the AWS Command Line Interface (AWS CLI), or the AWS SDKs.

Considerations

Before you use JWTs with Amazon OpenSearch Service you must consider the following:

Modifying the domain access policy

Before you can configure your domain to use JWT authentication and authorization, you must update your domain access policy to allow JWT users to access the domain. Otherwise, all incoming JWT authorized requests are denied. The recommended domain access policy to provide full access to the sub resources (/*) is:

Configuring JWT authentication and authorization

You can enable JWT authentication and authorization during the domain creation process or by updating an existing domain. The set-up steps vary slightly depending on which option you choose.

The following steps explain how to configure an existing domain for JWT authentication and authorization in the OpenSearch Service console:

Using a JWKS endpoint to validate a JWT

Instead of configuring a static public key, you can configure a JSON Web Key Set (JWKS) endpoint URL to dynamically retrieve public keys from your identity provider. When a JWKS endpoint is configured, OpenSearch Service automatically fetches and caches the public keys used to validate JWT signatures, eliminating the need to manually update keys when your identity provider rotates signing keys.

JWKS endpoint configuration requires OpenSearch version 3.3 or later.

Backward compatibility

This feature maintains full backward compatibility:

Configuring a JWKS endpoint

You can configure a JWKS endpoint using the OpenSearch Service console, the AWS CLI, or the configuration API.

aws opensearch update-domain-config \
  --domain-name my-domain \
  --advanced-security-options '{"JWTOptions":{"Enabled":true, "JwksUrl":"https://example.com/.well-known/jwks.json", "SubjectKey":"sub", "RolesKey":"roles"}}'

POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain/my-domain/config
{
  "AdvancedSecurityOptions": {
    "JWTOptions": {
      "Enabled": true,
      "JwksUrl": "https://example.com/.well-known/jwks.json",
      "RolesKey": "optional-roles-key",
      "SubjectKey": "optional-subject-key"
    }
  }
}

JWT header requirements

When using a JWKS endpoint, your JWT header must include a key ID (kid) that identifies the specific key to use for verification:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "V-diposfUJIk5jDBFi_QRouiVinG5PowskcSWy5EuCo"
}

The kid value must match a key identifier in the JWKS endpoint response.

For more information about JWKS configuration options and security settings, see Using a JWKS endpoint to validate a JWT in the OpenSearch documentation.

Using a JWT to send a test request

After creating a new JWT with a specified a subject and role pair, you can send a test request. To do this, use the private key to sign your request through the tool that created the JWT. OpenSearch Service is able to validate the incoming request by verifying this signature.

The following is an example of how to use a JWT token to access OpenSearch Service through your domain's search endpoint:

curl -XGET "$search_endpoint" -H "Authorization: Bearer <JWT>"

aws opensearch update-domain-config --domain-name <your_domain_name> --advanced-security-options '{"JWTOptions":{"Enabled":true, "PublicKey": "<your_public_key>", "SubjectKey": "<your_subject_key>", "RolesKey": "<your_roles_key>"}}'

POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain/my-domain/config
{
  "AdvancedSecurityOptions": {
    "JWTOptions": {
      "Enabled": true,
      "PublicKey": "public-key",
      "RolesKey": "optional-roles-key",
      "SubjectKey": "optional-subject-key"
   }  
  }
}