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

# Connect OpenSearch with AWS IAM (SigV4) – StackOne Hub

> Link a OpenSearch account in the StackOne Hub using AWS IAM (SigV4). End-user guide to authorize the integration and start using OpenSearch actions.

<Warning>AWS SigV4 is the only accepted auth mode for AWS OpenSearch Serverless collections (service `aoss`) and for AWS OpenSearch Service domains whose access policy references IAM principals. Every request is signed with the caller's AWS credentials and region — the SigV4 service value differs between the two products, so pick the right one below.</Warning>

<section data-guide-section data-guide-scopes="">
  <h2>Identify your AWS OpenSearch endpoint and product</h2>

  <p>There are two AWS-managed products with different endpoint URL shapes, IAM permissions, and SigV4 service values.</p>

  <Steps>
    <Step title="Copy the endpoint from the AWS console">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Check the endpoint hostname:</p>

        <ul>
          <li><strong>AWS OpenSearch Service (Managed domain)</strong> — host ends in `.es.amazonaws.com`, e.g. `search-mydomain-abc123.us-east-1.es.amazonaws.com`. Signing service: `es`.</li>
          <li><strong>AWS OpenSearch Serverless (Collection)</strong> — host ends in `.aoss.amazonaws.com`, e.g. `abcd1234.us-east-1.aoss.amazonaws.com`. Signing service: `aoss`.</li>
          <li>Reference: <a href="https://docs.aws.amazon.com/opensearch-service/latest/developerguide/managedomains-signing-service-requests.html" target="_blank" rel="noopener noreferrer">Making and signing OpenSearch Service requests</a>.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Create an IAM user for the integration</h2>

  <p>SigV4 signing requires a long-term IAM user (or STS-issued temporary credentials via role assumption). Create a dedicated IAM user rather than reusing an admin's keys.</p>

  <Steps>
    <Step title="Create the IAM user in the AWS Console">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sign in to the <a href="https://console.aws.amazon.com/iam/" target="_blank" rel="noopener noreferrer">AWS IAM Console</a> as an administrator, then:</p>

        <ul>
          <li>Go to <strong>Users</strong> > <strong>Create user</strong>.</li>
          <li>Enter a <strong>User name</strong> (e.g. `stackone-opensearch`) and click <strong>Next</strong>.</li>
          <li>On <strong>Set permissions</strong>, attach the policy that matches your product (next step below), then click <strong>Next</strong>, review, and click <strong>Create user</strong>.</li>
          <li>Reference: <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html" target="_blank" rel="noopener noreferrer">Create an IAM user in your AWS account</a>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Grant the access policy for your product">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Which IAM policy the user needs depends on whether you're connecting to a Managed domain or a Serverless collection.</p>

        <ul>
          <li><strong>OpenSearch Service (Managed)</strong> — attach `AmazonOpenSearchServiceFullAccess` (broad) or a scoped policy allowing `es:ESHttp*` on your domain ARN. Also ensure the <strong>domain access policy</strong> references the IAM user's ARN — under <strong>Amazon OpenSearch Service</strong> > select domain > <strong>Actions</strong> > <strong>Edit security configuration</strong>, edit the resource-based access policy to allow the principal. Reference: <a href="https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html" target="_blank" rel="noopener noreferrer">Fine-grained access control</a>.</li>
          <li><strong>OpenSearch Serverless</strong> — the user needs BOTH IAM permissions (`aoss:APIAccessAll` and `aoss:DashboardsAccessAll` on the collection ARN) AND a <strong>data-access policy</strong> granting collection/index permissions. Without both, requests return `403`. Reference: <a href="https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html" target="_blank" rel="noopener noreferrer">Data access control for Amazon OpenSearch Serverless</a>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Add the user to a Serverless data-access policy">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Data access policies are separate from IAM permissions and required for every Serverless collection.</p>

        <ul>
          <li>Open the <a href="https://console.aws.amazon.com/aos/home" target="_blank" rel="noopener noreferrer">Amazon OpenSearch Service console</a>. In the left nav pane, expand <strong>Serverless</strong> and under <strong>Security</strong> choose <strong>Data access policies</strong>.</li>
          <li>Choose <strong>Create access policy</strong>. Provide a name and description, then a rule name (e.g. `stackone-integration`).</li>
          <li>Choose <strong>Add principals</strong> and select the IAM user's ARN.</li>
          <li>Choose <strong>Grant</strong> and select the collection and index permissions the connector needs (for read-only datasync: `aoss:DescribeCollectionItems`, `aoss:ReadDocument`, `aoss:DescribeIndex`).</li>
          <li>Choose <strong>Create</strong>. Enforcement may lag up to a minute.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Generate an access key pair</h2>

  <p>SigV4 signing needs an Access Key ID + Secret Access Key. Generate the pair from the user's Security credentials tab.</p>

  <Steps>
    <Step title="Create the access key">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the IAM Console:</p>

        <ul>
          <li>Open the user you just created, go to the <strong>Security credentials</strong> tab, and in the <strong>Access keys</strong> panel choose <strong>Create access key</strong>.</li>
          <li>On the <strong>Access key best practices & alternatives</strong> screen, pick a use-case (<strong>Third-party service</strong> is appropriate for StackOne), acknowledge the recommendation checkbox, and click <strong>Next</strong>.</li>
          <li>Add an optional description tag (e.g. `stackone-integration`) and click <strong>Create access key</strong>.</li>
          <li>Copy the <strong>Access key</strong> (Access Key ID, format `AKIAIOSFODNN7EXAMPLE`) and the <strong>Secret access key</strong> (format `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`) immediately — <strong>the secret can only be retrieved at creation time</strong>. If you lose it, delete the key and create a new one.</li>
          <li>Reference: <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html" target="_blank" rel="noopener noreferrer">Manage access keys for IAM users</a>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Configure temporary STS credentials as an alternative">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>For higher-security setups, use short-lived STS credentials from an assume-role or federated session.</p>

        <ul>
          <li>Call `sts:AssumeRole` (or your identity federation flow) to obtain a temporary access key pair plus a <strong>Session Token</strong>.</li>
          <li>Paste all three values into the corresponding StackOne fields (Access Key ID, Secret Access Key, AWS Session Token) — StackOne signs each request with all three.</li>
          <li>Refresh the credentials before the STS expiry and update the connection — StackOne does not renew STS credentials automatically.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Test the credentials</h2>

  <p>A signed test call catches missing permissions or wrong signing service before configuring the connector.</p>

  <Steps>
    <Step title="Verify with a signed manual health check">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Two convenient options:</p>

        <ul>
          <li><strong>curl</strong> (7.75+): `curl --aws-sigv4 'aws:amz:{region}:{service}' -u '{accessKeyId}:{secretAccessKey}' https://{coreBaseUrl}/_cluster/health` — set `{service}` to `es` or `aoss` to match your product.</li>
          <li><strong>awscurl</strong>: `awscurl --service {service} --region {region} https://{coreBaseUrl}/_cluster/health`.</li>
          <li><strong>403 Forbidden</strong> on Serverless — you likely have IAM permissions but not a matching data-access policy. Re-check the data-access policy principals.</li>
          <li><strong>403 Forbidden</strong> on Managed — the domain access policy does not reference this IAM principal. Edit the domain's access policy to grant `es:ESHttp*` for this user.</li>
          <li><strong>Signature does not match</strong> — usually a wrong `region` or `awsService` value in the connection fields.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Enter credentials in StackOne Hub</h2>

  <p>Paste the values below into StackOne Hub to connect the account.</p>

  <Steps>
    <Step title="Fill in the connection fields">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Copy each value from the IAM Console and the AWS OpenSearch console.</p>

        <ul>
          <li><strong>OpenSearch Endpoint URL</strong> — the HTTPS endpoint from step 1.</li>
          <li><strong>AWS Access Key ID</strong> — the Access Key ID from step 3.</li>
          <li><strong>AWS Secret Access Key</strong> — the Secret Access Key from step 3.</li>
          <li><strong>AWS Session Token</strong> — only for temporary STS credentials; leave blank for long-term IAM user access keys.</li>
          <li><strong>AWS Region</strong> — the region hosting the endpoint (e.g. `us-east-1`, `eu-west-2`).</li>
          <li><strong>AWS Service</strong> — `es` for AWS OpenSearch Service (Managed domain), `aoss` for AWS OpenSearch Serverless. This value is used as the SigV4 signing service and must match your endpoint host suffix.</li>
          <li><strong>OpenSearch Dashboards URL</strong> — optional. For <strong>Managed</strong> domains, the Dashboards URL is `{coreBaseUrl}/_dashboards`. For <strong>Serverless</strong>, the Dashboards URL is `https://dashboards.{region}.aoss.amazonaws.com/_login/?collectionId={collection-id}` (found on the collection's detail page). Required only for `dashboards_*` actions.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<div data-whitelabel-hide>
  <h2>Linking the Account from the Hub</h2>

  <Steps>
    <Step title="Navigate to the Hub">
      Use one of the three <a href="/connect/managing-connectors/linking-accounts">Linking Account Methods</a> to access the Hub.
    </Step>

    <Step title="Fill out the fields">
      Fill out the following fields using details from your provider:

      <ul>
        <li><strong>OpenSearch Endpoint URL</strong></li>
        <li><strong>AWS Access Key ID</strong></li>
        <li><strong>AWS Secret Access Key</strong></li>
        <li><strong>AWS Session Token</strong> (Optional)</li>
        <li><strong>AWS Region</strong></li>
        <li><strong>AWS Service</strong></li>
        <li><strong>OpenSearch Dashboards URL</strong> (Optional)</li>
      </ul>
    </Step>

    <Step title="Connect">
      <ul>
        <li>Click <strong>Connect</strong></li>
        <li>If applicable, the provider will redirect you to a sign-in or authorization page. Complete the provider's authorization flow.</li>
        <li>Once authorization is successful, you will see a confirmation popup</li>
      </ul>
    </Step>
  </Steps>

  <p>If the account linking is successful, you will see the newly linked account in your <a href="/gateway/concepts/linked-accounts">Accounts</a> page.</p>
</div>