Configuration

This guide covers the key configuration areas for OpenSearch UI applications: IAM permissions, authentication options, administrator management, and application settings via the CLI.

Required IAM permissions

Before creating or managing an OpenSearch UI application, your IAM user or role needs the right permissions. The permissions fall into two categories depending on your authentication method.

Base permissions (all applications)

Attach this policy to your IAM user or role to create and manage applications:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ApplicationManagement",
      "Effect": "Allow",
      "Action": [
        "es:CreateApplication",
        "es:DeleteApplication",
        "es:GetApplication",
        "es:ListApplications",
        "es:UpdateApplication",
        "es:AddTags",
        "es:ListTags",
        "es:RemoveTags"
      ],
      "Resource": "arn:aws:opensearch:<REGION>:<ACCOUNT_ID>:application/*"
    },
    {
      "Sid": "DataSourceAssociation",
      "Effect": "Allow",
      "Action": [
        "aoss:BatchGetCollection",
        "aoss:ListCollections",
        "es:DescribeDomain",
        "es:DescribeDomains",
        "es:ListDomainNames",
        "es:GetDirectQueryDataSource",
        "es:ListDirectQueryDataSources"
      ],
      "Resource": "*"
    },
    {
      "Sid": "DataSourceAccess",
      "Effect": "Allow",
      "Action": [
        "aoss:APIAccessAll",
        "es:ESHttp*",
        "opensearch:StartDirectQuery",
        "opensearch:GetDirectQuery",
        "opensearch:CancelDirectQuery",
        "opensearch:GetDirectQueryResult"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ServiceLinkedRole",
      "Effect": "Allow",
      "Action": "iam:CreateServiceLinkedRole",
      "Resource": "arn:aws:iam::*:role/aws-service-role/opensearchservice.amazonaws.com/AWSServiceRoleForAmazonOpenSearchService"
    }
  ]
}

Permission group	Purpose
`es:Application`	Create, read, update, delete applications
`es:*Tags`	Manage resource tags on applications
`aoss:BatchGetCollection`, `es:DescribeDomain`	Associate data sources during app creation
`aoss:APIAccessAll`, `es:ESHttp*`	Access data through the application UI
`iam:CreateServiceLinkedRole`	Allows OpenSearch Service to publish CloudWatch metrics

Additional permissions for IAM Identity Center (SSO)

If you plan to enable SSO via IAM Identity Center, add these permissions on top of the base set:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "IDCAppManagement",
      "Effect": "Allow",
      "Action": [
        "sso:CreateApplication",
        "sso:DeleteApplication",
        "sso:PutApplicationGrant",
        "sso:PutApplicationAccessScope",
        "sso:PutApplicationAuthenticationMethod",
        "sso:PutApplicationAssignmentConfiguration",
        "sso:ListInstances",
        "sso:DescribeApplication",
        "sso:CreateApplicationAssignment"
      ],
      "Resource": "*"
    },
    {
      "Sid": "IDCUserLookup",
      "Effect": "Allow",
      "Action": [
        "sso-directory:SearchGroups",
        "sso-directory:SearchUsers",
        "identitystore:DescribeUser",
        "identitystore:DescribeGroup"
      ],
      "Resource": "*"
    },
    {
      "Sid": "PassRoleForIDC",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::<ACCOUNT_ID>:role/<IDC_ROLE_NAME>"
    }
  ]
}

For the full permissions reference, see IAM Policies Reference.

Authentication options

OpenSearch UI supports two authentication methods. You choose during application creation — it can't be changed afterward.

Method	How users log in	Best for
IAM authentication (default)	SigV4 presigned URLs or federated console	Programmatic access, small teams, CLI workflows
IAM Identity Center (SSO)	Browser-based SSO with corporate credentials	Teams using Okta, Azure AD, or other IdPs

IAM authentication

This is the default — no extra setup beyond the base IAM permissions. Users access the application via SigV4 presigned URLs or the AWS Console.

IAM Identity Center

Enables SSO so users can log in with their corporate identity provider credentials. When creating the application, you provide:

An IAM Identity Center instance ARN
An IAM role ARN that IDC will assume (with a trust policy for sso.amazonaws.com)

aws opensearch create-application \
  --name my-sso-app \
  --region us-east-1 \
  --iam-identity-center-options '{
    "enabled": true,
    "iamIdentityCenterInstanceArn": "arn:aws:sso:::instance/ssoins-<INSTANCE_ID>",
    "iamRoleForIdentityCenterApplicationArn": "arn:aws:iam::<ACCOUNT_ID>:role/<IDC_ROLE_NAME>"
  }'

For step-by-step IDC setup, see IDC Auth Setup. To compare all auth methods, see Choose Your Auth Method.

Managing application administrators

Application administrators can edit and delete the application, and create, edit, and delete workspaces. The user who creates the application is automatically the first admin.

Admin types

Admin type	Identifier format	When to use
IAM user or role	IAM ARN (e.g., `arn:aws:iam::123456789012:user/admin`)	IAM-authenticated applications
IDC user	IDC user ID (UUID format, e.g., `a1b2c3d4-e5f6-7890-abcd-ef1234567890`)	IDC-authenticated applications
All users	`*`	Grant admin to everyone with application access

Add an IAM principal as admin

aws opensearch update-application \
  --id <APP_ID> \
  --app-configs '[{
    "key": "opensearchDashboards.dashboardAdmin.users",
    "value": "arn:aws:iam::<ACCOUNT_ID>:user/<USERNAME>"
  }]'

Add an IDC user as admin

aws opensearch update-application \
  --id <APP_ID> \
  --app-configs '[{
    "key": "opensearchDashboards.dashboardAdmin.users",
    "value": "<IDC_USER_UUID>"
  }]'

Grant admin to all users

aws opensearch update-application \
  --id <APP_ID> \
  --app-configs '[{
    "key": "opensearchDashboards.dashboardAdmin.users",
    "value": "*"
  }]'

Every application must have at least one administrator. You can't remove the last admin.

Managing admins via the console

Open the OpenSearch Service console
Choose OpenSearch UI (Dashboards) in the left navigation
Select your application, then choose Edit
In the OpenSearch application admins section, choose either:
- Grant administrator's permission to specific user(s) — select IAM users or IDC users individually
- Grant administrator permission to all users — everyone with access becomes an admin
Choose Update

Application configuration keys

The app-configs parameter on create-application and update-application accepts key-value pairs for application-level settings:

Key	Value	Purpose
`opensearchDashboards.dashboardAdmin.users`	IAM ARN, IDC user UUID, or `*`	Set dashboard admin users
`opensearchDashboards.dashboardAdmin.groups`	IDC group UUID	Set dashboard admin groups

CLI quick reference

Task	Command
Create an application	`aws opensearch create-application --name <NAME> --region <REGION>`
Create with IDC	`aws opensearch create-application --name <NAME> --iam-identity-center-options '{...}'`
List applications	`aws opensearch list-applications --region <REGION>`
Get application details	`aws opensearch get-application --id <APP_ID>`
Update application	`aws opensearch update-application --id <APP_ID> --app-configs '[...]'`
Delete application	`aws opensearch delete-application --id <APP_ID>`
Add data source	`aws opensearch update-application --id <APP_ID> --data-sources '[{"dataSourceArn":"<ARN>"}]'`

Common configuration mistakes

Mistake	Impact	Fix
Missing `iam:PassRole` when enabling IDC	Application creation fails	Add `iam:PassRole` scoped to the IDC role ARN
Using `es:` prefix for application access	403 errors when accessing the UI	Use `opensearch:ApplicationAccessAll` instead
Forgetting `iam:CreateServiceLinkedRole`	CloudWatch metrics not published	Add the SLR permission to your policy
Setting admin to `*` in production	All users get admin privileges	Scope admin to specific IAM ARNs or IDC user IDs
Not scoping resources in production	Overly broad permissions	Replace `*` with specific application ARNs

Troubleshooting

Symptom	Likely cause	Resolution
"Not authorized to perform es:CreateApplication"	Missing base permissions	Attach the base permission policy from above
"Unable to create application" with IDC enabled	Missing SSO permissions	Add the IDC-specific permissions (sso:, identitystore:, iam:PassRole)
Application created but can't access UI	Missing `opensearch:ApplicationAccessAll`	This is a separate permission from `es:Application` — add it to the accessing role
Can't see application in console	Missing `es:GetApplication` or `es:ListApplications`	Add these permissions to the console user's policy
Admin features not available after login	Dashboard admin not configured	Run `update-application` with the `opensearchDashboards.dashboardAdmin.users` config

IAM Policies Reference — Complete permissions reference
Choose Your Auth Method — Compare IAM vs IDC vs SAML
Create Your First App — Step-by-step app creation guide
AWS docs: Getting started with OpenSearch UI