> ## 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 Basic Authentication – StackOne Hub

> Link a OpenSearch account in the StackOne Hub using Basic Authentication. End-user guide to authorize the integration and start using OpenSearch actions.

<Warning>OpenSearch clusters run on many platforms — self-hosted, AWS OpenSearch Service (Managed), Aiven, Bonsai, and others. The credential path differs per platform; the sections below cover the most common ones. The cluster must serve a TLS certificate signed by a Certificate Authority (public or internal) that the calling environment trusts — self-signed certificates cause connection failures at account-creation time.</Warning>

<section data-guide-section data-guide-scopes="">
  <h2>Identify your OpenSearch endpoint URL</h2>

  <p>StackOne calls the OpenSearch REST data plane over HTTPS. The endpoint is the fully-qualified URL of your cluster's REST API — the URL format depends on how OpenSearch is hosted.</p>

  <Steps>
    <Step title="Copy the endpoint URL from your platform">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Use the pattern that matches your deployment.</p>

        <ul>
          <li><strong>Self-hosted / on-premise</strong> — an HTTPS URL to your cluster's REST port (default `9200`).</li>
          <li><strong>AWS OpenSearch Service (Managed)</strong> — the domain endpoint shown on the <a href="https://console.aws.amazon.com/aos/home/" target="_blank" rel="noopener noreferrer">Amazon OpenSearch Service console</a>; host ends in `.es.amazonaws.com`.</li>
          <li><strong>Aiven for OpenSearch</strong> — the service URI shown on the service <strong>Overview</strong> page in the <a href="https://console.aiven.io/" target="_blank" rel="noopener noreferrer">Aiven Console</a>; host ends in `.aivencloud.com` on a service-specific port.</li>
          <li><strong>Bonsai</strong> — copy the connection URL from the cluster's <strong>Credentials</strong> tab in the <a href="https://app.bonsai.io/" target="_blank" rel="noopener noreferrer">Bonsai app</a>. Paste only the host+port portion here (host ends in `.bonsaisearch.net`, on port `443`); put the username and password in the credential fields below.</li>
          <li>The URL must use HTTPS — the Security Plugin requires TLS.</li>
          <li>No trailing slash.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Create the integration credentials for your platform</h2>

  <p>Basic authentication uses a username and password issued by the cluster's OpenSearch Security Plugin. Follow the path that matches your hosting platform, and prefer a scoped integration user over a shared admin account.</p>

  <Steps>
    <Step title="Create an internal user in Dashboards (self-hosted)">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sign in to OpenSearch Dashboards as an admin, then:</p>

        <ul>
          <li>Choose <strong>Security</strong>, <strong>Internal Users</strong>, and <strong>Create internal user</strong>.</li>
          <li>Provide a <strong>Username</strong> (e.g. `stackone-integration`) and <strong>Password</strong>. The Security plugin automatically hashes the password and stores it in the `.opendistro_security` index.</li>
          <li>Optionally set <strong>Backend roles</strong> and <strong>Attributes</strong>.</li>
          <li>Choose <strong>Submit</strong>.</li>
          <li>See <a href="https://docs.opensearch.org/latest/security/access-control/users-roles/" target="_blank" rel="noopener noreferrer">Defining users and roles</a> in the OpenSearch documentation.</li>
        </ul>
      </div>
    </Step>

    <Step title="Enable fine-grained access control (AWS OpenSearch Service)">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>On AWS OpenSearch Service, HTTP basic authentication requires <strong>fine-grained access control (FGAC)</strong> with the internal user database enabled. If FGAC is already enabled with the internal user database, sign in to the domain's Dashboards URL (typically the domain endpoint suffixed with `/_dashboards`) as the master user and follow the self-hosted path above. If FGAC is not yet enabled:</p>

        <ul>
          <li>Open the <a href="https://console.aws.amazon.com/aos/home/" target="_blank" rel="noopener noreferrer">Amazon OpenSearch Service console</a>, select your domain, and choose <strong>Actions</strong> > <strong>Edit security configuration</strong>.</li>
          <li>Select <strong>Enable fine-grained access control</strong>.</li>
          <li>Choose <strong>Create master user</strong> and specify a username and password.</li>
          <li>Choose <strong>Save changes</strong>. The change triggers a blue/green deployment.</li>
          <li>Once the domain returns to `Active`, sign in to the Dashboards URL with the master credentials and use the standard <strong>Security</strong> > <strong>Internal Users</strong> flow above to create the scoped integration user.</li>
          <li>Reference: <a href="https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html" target="_blank" rel="noopener noreferrer">Fine-grained access control in Amazon OpenSearch Service</a>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Enable OpenSearch Security and create an admin (Aiven for OpenSearch)">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Aiven services start without OpenSearch Security enabled. To use basic auth against the Security plugin's internal user database, first enable it on the service:</p>

        <ul>
          <li>In the <a href="https://console.aiven.io/" target="_blank" rel="noopener noreferrer">Aiven Console</a>, open your OpenSearch service and click <strong>Users</strong> in the sidebar.</li>
          <li>Click <strong>Enable OpenSearch Security</strong>.</li>
          <li>Review the confirmation window, select the acknowledgement checkbox, and click <strong>Continue</strong>.</li>
          <li>Enter a password for the default admin user, then click <strong>Enable OpenSearch Security</strong> to activate.</li>
          <li>Once enabled, further user management moves into the OpenSearch Dashboards UI — sign in as admin and use <strong>Security</strong> > <strong>Internal Users</strong> > <strong>Create internal user</strong> to add the scoped integration user.</li>
          <li>Note: enabling OpenSearch Security cannot be reversed without Aiven support. Reference: <a href="https://aiven.io/docs/products/opensearch/concepts/os-security" target="_blank" rel="noopener noreferrer">OpenSearch Security in Aiven for OpenSearch</a>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Copy the cluster credentials from the Bonsai app">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Bonsai does not expose the Security plugin UI; each cluster comes with its own credentials pair.</p>

        <ul>
          <li>In the <a href="https://app.bonsai.io/" target="_blank" rel="noopener noreferrer">Bonsai app</a>, open your cluster and go to the <strong>Credentials</strong> tab.</li>
          <li>Copy the <strong>User</strong> and <strong>Password</strong> values.</li>
          <li>Bonsai clusters ship with cluster-scoped credentials — rotate them via the same page if compromised.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Grant least-privilege permissions</h2>

  <p>Basic authentication grants the permissions of the mapped role. Map the integration user to the narrowest role that covers the actions this connector needs.</p>

  <Steps>
    <Step title="Grant the user a role in Dashboards">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In OpenSearch Dashboards:</p>

        <ul>
          <li>Choose <strong>Security</strong>, <strong>Roles</strong>, and select the role you want to assign.</li>
          <li>Choose the <strong>Mapped users</strong> tab and <strong>Manage mapping</strong>.</li>
          <li>Specify the integration username (or a backend role it holds) and choose <strong>Map</strong>.</li>
          <li>Predefined role reference: `readall_and_monitor` grants search on all indexes plus monitoring — a reasonable minimum for read-heavy connector actions. `all_access` grants full cluster access but is not least-privilege.</li>
          <li>Reference: <a href="https://docs.opensearch.org/latest/security/access-control/users-roles/#predefined-roles" target="_blank" rel="noopener noreferrer">Predefined roles</a>.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

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

  <p>The connection test calls `GET /_cluster/health`. Match the error to a fix:</p>

  <Steps>
    <Step title="Verify with a manual health check">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Run the same call StackOne runs, then interpret the response.</p>

        <ul>
          <li><strong>401 Unauthorized</strong> — username or password wrong. Verify with a call to `/_plugins/_security/authinfo` on the same endpoint using the credentials.</li>
          <li><strong>403 Forbidden</strong> — user authenticates but the mapped role is missing a permission. The response body names the missing permission — grant it via a role and re-map.</li>
          <li><strong>Certificate error / unable to verify</strong> — cluster is serving a certificate the caller can't validate. Use a properly-signed certificate or publish the internal CA root to the calling environment.</li>
          <li><strong>Connection refused / timeout</strong> — the cluster URL or port is unreachable. Check firewall rules, security groups, and VPC/VPN reachability from StackOne's egress.</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 platform you configured above.</p>

        <ul>
          <li><strong>OpenSearch Endpoint URL</strong> — the HTTPS endpoint from step 1.</li>
          <li><strong>Username</strong> — the internal / master / cluster user you created.</li>
          <li><strong>Password</strong> — the password you set for that user.</li>
          <li><strong>OpenSearch Dashboards URL</strong> — optional. Only required if you plan to sync dashboards, visualisations, or index patterns via the `dashboards_*` actions. Self-hosted Dashboards runs on port `5601` by default; AWS OpenSearch Service exposes it as the domain endpoint suffixed with `/_dashboards`. Leave blank for core datasync workflows.</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>Username</strong></li>
        <li><strong>Password</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>