> ## Documentation Index
> Fetch the complete documentation index at: https://docs.resolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenSearch

<Info>
  **Prerequisite**: The [Resolve Satellite](/resolve-satellite) should be installed in your environment.
</Info>

## Configure OpenSearch to allow auth via JWT

To see the official instructions please read  [https://docs.aws.amazon.com/opensearch-service/latest/developerguide/JSON-Web-tokens.html](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/JSON-Web-tokens.html)

<Warning>
  OpenSearch 2.11 is the earliest compatible version that can be used for JWT authentication.
</Warning>

Below is an example of how to setup JWT authentication on OpenSearch and create a token

<Steps>
  <Step title="Modifying your 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
  </Step>

  <Step title="Create your permission keys">
    Use OpenSSL to create the keys

    * **privatekey.pem:** Used to sign JWTs.
    * **publickey.pem:** Uploaded to OpenSearch to verify JWTs

    ```javascript theme={null}
    openssl genrsa -out privatekey.pem 2048
    openssl rsa -in privatekey.pem -pubout -out publickey.pem
    ```
  </Step>

  <Step title="Configure JWT authentication and authorization">
    The following steps explain how to configure an existing domain for JWT authentication and authorization in the OpenSearch Service console:

    1. Under Domain configuration, navigate to JWT authentication and authorization for OpenSearch, select *Enable JWT authentication and authorization*.

    2. Configure the public key to use for your domain. To do this, you can either upload a PEM file, containing a public key, or manually enter it. Use the key that you generated in the previous section.

    3. (Optional) Under Additional settings, you can configure the following optional fields
       * **Subject key** — you can leave this field empty to use the default sub key for your JWTs.
       * **Roles key** — you can leave this field empty to use the default roles key for your JWTs.
  </Step>
</Steps>

## **Create** a JWT for ResolveAI

Use a library (e.g., jsonwebtoken in Node.js or pyjwt in Python) to generate a JWT signed with privatekey.pem. Examples are shown below

<Tabs>
  <Tab title="Create A JWT in NodeJS">
    First install the following dependencies

    ```bash theme={null}
    npm install jsonwebtoken
    ```

    Then create a script to generate your token. You will use

    1. The **privatekey.pem** that was generated in the step above
    2. The **Subject key** and **Roles key** that were generated in the step above

    ```javascript theme={null}
    const fs = require('fs');
    const jwt = require('jsonwebtoken');

    // Load private key (PEM format)
    const privateKey = fs.readFileSync('privatekey.pem', 'utf8');

    // Define JWT payload
    const payload = {
      sub: 'opensearch-user',  // Replace with your OpenSearch username
      roles: ['all_access']    // Replace with OpenSearch role(s) assigned
    };

    // Optional JWT options
    const options = {
      algorithm: 'RS256',
      issuer: '<your-issuer>   // Optional issuer
    };

    // Generate JWT
    const token = jwt.sign(payload, privateKey, options);

    // Output the token
    console.log('Generated JWT:\n');
    console.log(token);
    ```

    Finally run the script

    ```bash theme={null}
    node generate-jwt.js
    ```
  </Tab>

  <Tab title="Create a JWT in Python">
    First install the following dependencies

    ```bash theme={null}
    pip install pyjwt
    ```

    Then create a script to generate your token. You will use

    1. The **privatekey.pem** that was generated in the step above
    2. The **Subject key** and **Roles key** that were generated in the step above

    ```python theme={null}
    import jwt
    from datetime import datetime, timedelta

    # Load private key from PEM file
    with open("privatekey.pem", "r") as f:
        private_key = f.read()

    # Define payload (claims)
    payload = {
        "sub": "opensearch-user",           # Replace with valid OpenSearch username
        "roles": ["all_access"],            # Replace with OpenSearch roles
    }

    # Create JWT
    token = jwt.encode(
        payload,
        private_key,
        algorithm="RS256",                  # OpenSearch supports RS256 or ES256
        headers={"alg": "RS256"}
    )

    print("Generated JWT:\n")
    print(token)
    ```

    Finally run the script

    ```bash theme={null}
    python3 generate_jwt.py
    ```
  </Tab>
</Tabs>

## Configure the integration in Resolve Satellite

Below is an example of how to setup the Opensearch integration in the satellite with the url property as well as using the k8s secret (potentially backed by an AWS secret manager or another mechanism) for authentication.

<Steps>
  <Step title="Create a Kubernetes secret">
    Create a Kubernetes secret of the following form. Note that the structure of the secret is important and for a Opensearch API Key, it must have the top-level key token: ‘token-value’.

    ```yaml opensearch-resolve-access-token.yml theme={null}
    apiVersion: v1
    kind: Secret
    type: Opaque
    metadata:
      name:  opensearch-resolve-access-token
    stringData:
      token: "<your opensearch JWT Token>"
    ```

    <Warning>
      **Security Best Practice:** Never store credentials in plaintext in configuration files or source control.
      Always use Kubernetes secrets and encrypt etcd or use enterprise secret management systems.
      See [Secret Management](/secret-management) for detailed guidance.
    </Warning>

    To apply the secret run

    ```shell apply secret theme={null}
    kubectl apply -f opensearch-resolve-access-token.yml
    ```
  </Step>

  <Step title="Configure your OpenSearch JWT token in the Resolve Satellite">
    Update your helm values override file with the following information (e.g.: *resolve-values.yaml*)

    ```yaml resolve-values.yaml theme={null}
    integrations:
      opensearchIntegration:
        type: opensearch
        create: true
        secretName:  "opensearch-resolve-access-token"
        connection:
          url: "<your opensearch endpoint>"
    ```

    Install the satellite and apply the values from the yaml file that you have just updated. e.g.: *resolve-values.yaml.* To find the latest version, visit ResolveAI's docker hub repository for the [helm chart](https://hub.docker.com/r/resolveaihq/satellite-chart/tags) and [satellite image](https://hub.docker.com/r/resolveaihq/satellite/tags).

    ```shell apply config to satellite and redeploy theme={null}
    helm upgrade --install oci://registry-1.docker.io/resolveaihq/satellite-chart --version <LatestChart> --values resolve-values.yaml --set image.tag=<LatestImage>
    ```

    Once your satellite is deployed, we will automatically create an integration instance for you.
  </Step>

  <Step title="Verify your integration status in ResolveAI">
    Login to [https://app0.resolve.ai/](https://app0.resolve.ai/). Go to the integrations page and and select “Opensearch”

    You should see an automatically created integration based on the provided configuration.
  </Step>
</Steps>