# Using OpenSearch UI in Amazon OpenSearch Service
OpenSearch UI (user interface) is a modernized operational analytics experience for Amazon OpenSearch Service that provides a unified view for you to interact with data across multiple sources. Unlike OpenSearch Dashboards, which works with only the one domain or collection that hosts it, OpenSearch UI is hosted in the AWS Cloud. This makes it possible for OpenSearch UI to achieve high availability and stay functional during cluster upgrades, and to natively connect with multiple data sources. For information about OpenSearch Dashboards, see [Using OpenSearch Dashboards with Amazon OpenSearch Service](dashboards.md).
The following are key features of OpenSearch UI:
+ **Multiple data source support** – OpenSearch UI can connect with multiple data sources to create a comprehensive view. This includes OpenSearch domains and serverless collections, as well as integrated AWS data sources such as Amazon CloudWatch, Amazon Security Lake, and Amazon Simple Storage Service (Amazon S3).
+ **Zero downtime during upgrades** – OpenSearch UI is hosted in the AWS Cloud. This means that OpenSearch remains operational and can retrieve data from clusters during upgrade processes.
+ **Workspaces** – Curated spaces for team collaborations for various workflows, such as Observability, Security Analytics and Search. You can define the privacy settings and manage permissions for collaborators in your workspace.
+ **Single sign-on** – OpenSearch UI works with AWS IAM Identity Center and SAML through AWS Identity and Access Management (IAM) federatation to integrate with your identity providers to create a single sign-on experience for your end users.
+ **GenAI-powered analytics** – OpenSearch UI supports natural language query generation to help generate the right queries for your analysis. OpenSearch UI also works with Amazon Q Developer to provide the Amazon Q chat and help generate visualizations, alert summary, insights, and recommended anomaly detectors.
+ **Multiple query language support** – OpenSearch UI supports Piped Processing Language (PPL), SQL, Lucene, and Dashboards Query Language (DQL).
+ **Cross-Region and cross-account support** – OpenSearch UI can utilize the cross-cluster search feature to connect with OpenSearch domains in different accounts and different Regions for aggregated analysis and visualizations.
To get started and create your first OpenSearch UI, follow the instructions in [Getting started with the OpenSearch user interface in Amazon OpenSearch Service](application-getting-started.md).
For information about the latest features released for OpenSearch UI, see [Amazon OpenSearch Service user interface release history](application-release-history.md).
**Topics**
+ [
# Amazon OpenSearch Service user interface release history
](application-release-history.md)
+ [
# Getting started with the OpenSearch user interface in Amazon OpenSearch Service
](application-getting-started.md)
+ [
# Agentic AI in Amazon OpenSearch Service
](application-ai-assistant.md)
+ [
# Encrypting OpenSearch UI application metadata with customer managed keys
](application-encryption-cmk.md)
+ [
# Enabling SAML federation with AWS Identity and Access Management
](application-enable-SAML-identity-federation.md)
+ [
# Managing data source associations and Virtual Private Cloud access permissions
](application-data-sources-and-vpc.md)
+ [
# Using Amazon OpenSearch Service workspaces
](application-workspaces.md)
+ [
# Cross-Region and cross-account data access
](application-cross-region-cross-account.md)
+ [
# Managing access to the OpenSearch UI from a VPC endpoint
](application-access-ui-from-vpc-endpoint.md)
+ [
# Migrating saved objects from OpenSearch Dashboards to OpenSearch UI
](application-migration.md)
+ [
# OpenSearch UI endpoints and quotas
](opensearch-ui-endpoints-quotas.md)
# Amazon OpenSearch Service user interface release history
The following table lists all releases of the Amazon OpenSearch Service support for OpenSearch UI and the features and enhancements included with each release.
| Change | Release date | Description |
| --- | --- | --- |
| New feature | 2025-03-10 | OpenSearch UI now supports cross-account data access to OpenSearch domains. You can configure applications in one account to access domains in different accounts using IAM or AWS IAM Identity Center authentication, for both public and VPC domains. For more information, see [Cross-account data access to OpenSearch domains](application-cross-account-data-access-domains.md). |
| New feature | 2025-12-29 | OpenSearch UI now supports customer managed keys (CMK) for encrypting application metadata. This feature helps you meet regulatory and compliance requirements by giving you full control over encryption keys. This launch also increases the metadata size limit for saved objects in OpenSearch UI, enabling you to create and store complex queries, extensive visualizations, and large-scale workspaces. For more information, see [Encrypting OpenSearch UI application metadata with customer managed keys](application-encryption-cmk.md). |
| New feature | 2025-04-16 | OpenSearch UI now works with [cross-cluster search](cross-cluster-search.md). This makes it possible for you to use OpenSearch UI in one AWS Region to access clusters in a different Region. This is done by configuring it as a remote cluster connected with a cluster in the same Region. For more information, see [Cross-cluster search](application-cross-cluster-search.md). |
| New feature | 2025-03-31 | Amazon Q Developer is now generally available in Amazon OpenSearch Service. For information, see [AI Assistant for Amazon OpenSearch Service](AI-assistant-support.md). |
| New feature | 2025-02-05 | Security Assertion Markup Language 2.0) (SAML) through AWS Identity and Access Management (IAM) federation now works with OpenSearch UI. This makes it possible to create an identity provider-initiated Single Sign-On (SSO) experience for your end users. For more information, see [Enabling SAML federation with AWS Identity and Access Management](application-enable-SAML-identity-federation.md). |
| New integration | 2024-12-01 | Zero-ETL integration with Amazon CloudWatch simplifies log data analysis and visualization, reducing technical overhead and operational costs. For more information, see [New Amazon CloudWatch and Amazon OpenSearch Service launch an integrated analytics experience](https://aws.amazon.com/blogs/aws/new-amazon-cloudwatch-and-amazon-opensearch-service-launch-an-integrated-analytics-experience/) on the *AWS News Blog*. |
| New integration | 2024-12-01 | Zero-ETL integration with Amazon Security Lake makes it possible for organizations to efficiently search, analyze, and gain actionable insights from their security data. For more information, see [Introducing Amazon OpenSearch Service and Amazon Security Lake integration to simplify security analytics](https://aws.amazon.com/blogs/aws/introducing-amazon-opensearch-service-zero-etl-integration-for-amazon-security-lake/) on the *AWS News Blog*. |
| Initial release | 2024-11-07 | The initial public release of OpenSearch UI. For more information, see [Amazon OpenSearch Service launches the next-generation OpenSearch UI](https://aws.amazon.com/blogs/big-data/amazon-opensearch-service-launches-the-next-generation-opensearch-ui/) on the *AWS Big Data Blog*. |
# Getting started with the OpenSearch user interface in Amazon OpenSearch Service
In Amazon OpenSearch Service, an *application* is an instance of the OpenSearch user interface (OpenSearch UI). Each application can be associated with multiple data sources, and a single source can be associated with multiple applications. You can create multiple applications for different administrators using different supported authentication options.
Use the information in this topic to guide you through the process of creating an OpenSearch UI application using the AWS Management Console or the AWS CLI.
**Topics**
+ [
## Required permissions for creating Amazon OpenSearch Service applications
](#application-prerequisite-permissions)
+ [
## Creating an OpenSearch UI application
](#create-application)
+ [
## Managing application administrators
](#managing-application-administrators)
## Required permissions for creating Amazon OpenSearch Service applications
Before you create an application, verify that you have been granted the necessary permissions for the task. Contact an account administrator for assistance if required.
### General permissions
To work with applications in OpenSearch Service, you need the permissions shown in the following policy. The permissions serve the following purposes:
+ The five `es:*Application` permissions are required to create and manage an application.
+ The three `es:*Tags` permissions are required to add, list and remove tags from the application.
+ The `aoss:BatchGetCollection`, `es:DescribeDomain` and `es:GetDirectQueryDataSource` permissions are required to associate data sources.
+ The `aoss:APIAccessAll`, `es:ESHttp*`, and 4 `opensearch:*DirectQuery*` permissions are required to access data sources.
+ The `iam:CreateServiceLinkedRole` provides permission to Amazon OpenSearch Service for creating a service-linked role (SLR) in your account. This role is used and makes it possible for the OpenSearch UI application to publish Amazon CloudWatch metrics in your account. For more information, see [Permissions](slr-aos.md#slr-permissions) in the topic [Using service-linked roles to create VPC domains and direct query data sources](slr-aos.md).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"es:CreateApplication",
"es:DeleteApplication",
"es:GetApplication",
"es:ListApplications",
"es:UpdateApplication",
"es:AddTags",
"es:ListTags",
"es:RemoveTags",
"aoss:APIAccessAll",
"es:ESHttp*",
"opensearch:StartDirectQuery",
"opensearch:GetDirectQuery",
"opensearch:CancelDirectQuery",
"opensearch:GetDirectQueryResult",
"aoss:BatchGetCollection",
"aoss:ListCollections",
"es:DescribeDomain",
"es:DescribeDomains",
"es:ListDomainNames",
"es:GetDirectQueryDataSource",
"es:ListDirectQueryDataSources"
],
"Resource": "*"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/opensearchservice.amazonaws.com/AWSServiceRoleForAmazonOpenSearchService"
}
]
}
```
------
### Permissions to create an application that uses IAM Identity Center authentication (optional)
By default, dashboard applications are authenticated using AWS Identity and Access Management (IAM) to manage permissions for AWS resource users. However, you can choose to provide a single sign-on experience by using IAM Identity Center, which lets you use your existing identity providers for logging into OpenSearch UI applications. In this case, you'll select the **Authentication with IAM Identity Center** option in the procedure later in this topic, and then grant IAM Identity Center users the permissions required to access the OpenSearch UI application.)
To create an application that uses IAM Identity Center authentication, you'll need the following permissions. Replace the *placeholder values* with your own information. Contact an account administrator for assistance if required.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "IDCPermissions",
"Effect": "Allow",
"Action": [
"es:CreateApplication",
"es:DeleteApplication",
"es:GetApplication",
"es:ListApplications",
"es:UpdateApplication",
"es:AddTags",
"es:ListTags",
"es:RemoveTags",
"aoss:BatchGetCollection",
"aoss:ListCollections",
"es:DescribeDomain",
"es:DescribeDomains",
"es:ListDomainNames",
"es:GetDirectQueryDataSource",
"es:ListDirectQueryDataSources",
"sso:CreateApplication",
"sso:DeleteApplication",
"sso:PutApplicationGrant",
"sso:PutApplicationAccessScope",
"sso:PutApplicationAuthenticationMethod",
"sso:ListInstances",
"sso:DescribeApplicationAssignment",
"sso:DescribeApplication",
"sso:CreateApplicationAssignment",
"sso:ListApplicationAssignments",
"sso:DeleteApplicationAssignment",
"sso-directory:SearchGroups",
"sso-directory:SearchUsers",
"sso:ListDirectoryAssociations",
"identitystore:DescribeUser",
"identitystore:DescribeGroup",
"iam:ListRoles"
],
"Resource": "*"
},
{
"Sid": "SLRPermission",
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/opensearchservice.amazonaws.com/AWSServiceRoleForAmazonOpenSearchService"
},
{
"Sid": "PassRolePermission",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/iam-role-for-identity-center"
}
]
}
```
------
## Creating an OpenSearch UI application
Create an application that specifies and application name, authentication method, and administrators using one of the following procedures.
**Topics**
+ [
### Creating an OpenSearch UI application that uses IAM authentication in the console
](#create-application-iam-authentication-console)
+ [
### Creating an OpenSearch UI application that uses AWS IAM Identity Center authentication in the console
](#create-application-iam-identity-center-authentication-console)
+ [
### Creating an OpenSearch UI application that uses AWS IAM Identity Center authentication using the AWS CLI
](#create-application-iam-identity-center-authentication-cli)
### Creating an OpenSearch UI application that uses IAM authentication in the console
**To create an OpenSearch UI application that uses IAM authentication in the console**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation pane, choose **OpenSearch UI (Dashboards)**.
1. Choose **Create application**.
1. For **Application name**, enter a name for the application.
1. Do not select the **Authentication with IAM Identity Center** check box. For information about creating an application with authentication through AWS IAM Identity Center, see [Creating an OpenSearch UI application that uses AWS IAM Identity Center authentication in the console](#create-application-iam-identity-center-authentication-console) later in this topic.
1. (Optional) You are automatically added as an administrator of the application you are creating. In the **OpenSearch application admins management** area, you can grant administrator permissions to other users.
**Note**
The OpenSearch UI application administrator role grants permissions to edit and delete an OpenSearch UI application. Application administrators can also create, edit and delete workspaces in an OpenSearch UI application.
To grant administrator permissions to other users, choose one of the following:
+ **Grant administrator's permission to specific user(s)** – In the **OpenSearch application admins** field, in the **Properties** pop-up list, select **IAM users** or
**AWS IAM Identity Center users**, and then choose the individual users to grant administrator permissions to.
+ **Grant administrator permission to all users** – All users in your organization or account are granted administrator permissions.
1. (Optional) Configure encryption settings. By default, OpenSearch UI metadata is encrypted with AWS owned keys. To use your own customer managed key (CMK) for encryption, see [Encrypting OpenSearch UI application metadata with customer managed keys](application-encryption-cmk.md).
1. (Optional) In the **Tags** area, apply one or more tag key name/value pairs to the application.
Tags are optional metadata that you assign to a resource. Tags allow you to categorize a resource in different ways, such as by purpose, owner, or environment.
1. Choose **Create**.
### Creating an OpenSearch UI application that uses AWS IAM Identity Center authentication in the console
In order create an OpenSearch UI application that uses AWS IAM Identity Center authentication, you must have the IAM permissions described earlier in this topic in [Permissions to create an application that uses IAM Identity Center authentication (optional)](#prerequisite-permissions-idc).
**To create an OpenSearch UI application that uses AWS IAM Identity Center authentication in the console**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation pane, choose **OpenSearch UI (Dashboards)**.
1. Choose **Create application**.
1. For **Application name**, enter a name for the application.
1. (Optional) To enable single sign-on for your organization or account, do the following:
1. Select the **Authentication with IAM Identity Center** check box, as shown in the following image:
![\[The "Single sign-on authetication" area with the "Authentication with IAM Identity Center" box selected.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/ui-Single-sign-on-authentication.png)
1. Do one of the following:
+ In the **IAM role for Identity Center application** list, choose an existing IAM role that provides the required permissions for IAM Identity Center to access OpenSearch UI and the associated data sources. See the policies in the next bullet for the permissions the role must have.
+ Create a new role with the required permissions. Use the following procedures in the *IAM User Guide* with the specified options to create a new role and with the necessary permission policy and trust policy.
+ Procedure: [Create IAM policies (console)](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/access_policies_create-console.html)
As you follow the steps in this procedure, paste the following policy into the policy editor **JSON** field:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "IdentityStoreOpenSearchDomainConnectivity",
"Effect": "Allow",
"Action": [
"identitystore:DescribeUser",
"identitystore:ListGroupMembershipsForMember",
"identitystore:DescribeGroup"
],
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledViaLast": "es.amazonaws.com"
}
}
},
{
"Sid": "OpenSearchDomain",
"Effect": "Allow",
"Action": [
"es:ESHttp*"
],
"Resource": "*"
},
{
"Sid": "OpenSearchServerless",
"Effect": "Allow",
"Action": [
"aoss:APIAccessAll"
],
"Resource": "*"
}
]
}
```
------
+ Procedure: [Create a role using custom trust policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html)
As you follow the steps in this procedure, replace the placeholder JSON in the **Custom trust policy** box with the following:
**Tip**
If you are adding the trust policy to an existing role, add the policy on the role's **Trust relationship** tab.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "application.opensearchservice.amazonaws.com"
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"Service": "application.opensearchservice.amazonaws.com"
},
"Action": "sts:SetContext",
"Condition": {
"ForAllValues:ArnEquals": {
"sts:RequestContextProviders": "arn:aws:iam::123456789012:oidc-provider/portal.sso.us-east-1.amazonaws.com/apl/application-id"
}
}
}
]
}
```
------
1. If an IAM Identity Center instance has been created in your organization or account already, the console reports that Amazon OpenSearch Dashboards is already connected to an organization instance of IAM Identity Center, as shown in the following image.
![\[The "Amazon OpenSearch Dashboard connected to an account instance of IAM Identity Center" area shows the URL of the existing IAM Identity Center account instance.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/ui-connected-instance.png)
If IAM Identity Center is not yet available in your organization or account, you or an administrator with the necessary permissions can create an organization instance or account instance. The **Connect Amazon OpenSearch Dashboards to IAM Identity Center** area provides options for both, as shown in the following image:
![\[The "Connect Amazon OpenSearch Dashboards to IAM Identity Center" area provides buttons to create an organization instance or an account instance.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/ui-no-connected-instance.png)
In this case, you can create an account instance in IAM Identity Center for testing, or request that an administrator create an organizational instance in IAM Identity Center. For more information, see the following topics in the *AWS IAM Identity Center User Guide*:
**Note**
If you want to create OpenSearch UI applications in a different AWS Region from your IAM Identity Center organizational instance, see [Using IAM Identity Center across multiple AWS Regions](https://docs.aws.amazon.com/singlesignon/latest/userguide/multi-region-iam-identity-center.html).
+ [Organization instances of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/organization-instances-identity-center.html)
+ [Account instances of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/account-instances-identity-center.html)
+ [Enable AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/enable-identity-center.html)
1. (Optional) You are automatically added as an administrator of the application you are creating. In the **OpenSearch application admins management** area, you can grant administrator permissions to other users, as shown in the following image:
![\[The "OpenSearch application admins management" area provides options for granting administrator permissions to select users or all all users.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/ui-admins-management.png)
**Note**
The OpenSearch UI application administrator role grants permissions to edit and delete an OpenSearch UI application. Application administrators can also create, edit and delete workspaces in an OpenSearch UI application.
To grant administrator permissions to other users, choose one of the following:
+ **Grant administrator's permission to specific user(s)** – In the **OpenSearch application admins** field, in the **Properties** pop-up list, select **IAM users** or
**AWS IAM Identity Center users**, and then choose the individual users to grant administrator permissions to.
+ **Grant administrator permission to all users** – All users in your organization or account are granted administrator permissions.
1. (Optional) In the **Tags** area, apply one or more tag key name/value pairs to the application.
Tags are optional metadata that you assign to a resource. Tags allow you to categorize a resource in different ways, such as by purpose, owner, or environment.
1. Choose **Create**.
### Creating an OpenSearch UI application that uses AWS IAM Identity Center authentication using the AWS CLI
To create an OpenSearch UI application that uses AWS IAM Identity Center authentication using the AWS CLI, use the [create-application](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-application.html) command with the following options:
+ `--name` – The name of the application.
+ `--iam-identity-center-options` – (Optional) The IAM Identity Center instance and the IAM role that OpenSearch will use for authentication and access control.
Replace the *placeholder values* with your own information.
```
aws opensearch create-application \
--name application-name \
--iam-identity-center-options "
{
\"enabled\":true,
\"iamIdentityCenterInstanceArn\":\"arn:aws:sso:::instance/sso-instance\",
\"iamRoleForIdentityCenterApplicationArn\":\"arn:aws:iam::account-id:role/role-name\"
}
"
```
## Managing application administrators
An OpenSearch UI application administrator is a defined role with permission to edit and delete an OpenSearch UI application.
By default, as the creator of an OpenSearch UI application, you are the first administrator of the OpenSearch UI application.
### Managing OpenSearch UI administrators using the console
You can add additional administrators to an OpenSearch UI application in the AWS Management Console, either during the application creation workflow or in the **Edit** page after the application has been created.
The OpenSearch UI application administrator role grants permissions to edit and delete an OpenSearch UI application. Application administrators can also create, edit and delete workspaces in an OpenSearch UI application.
On an application detail page, you can search for the Amazon Resource Name (ARN) of an IAM principal or search for the name of IAM Identity Center user.
**To manage OpenSearch UI administrators using the console**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation pane, choose **OpenSearch UI (Dashboards)**.
1. In the **OpenSearch applications** area, choose the name of an existing application.
1. Choose **Edit**
1. To grant administrator permissions to other users, choose one of the following:
+ **Grant administrator's permission to specific user(s)** – In the **OpenSearch application admins** field, in the **Properties** pop-up list, select **IAM users** or
**AWS IAM Identity Center users**, and then choose the individual users to grant administrator permissions to.
+ **Grant administrator permission to all users** – All users in your organization or account are granted administrator permissions.
1. Choose **Update**.
You can remove additional administrators, but each OpenSearch UI application must retain at least one administrator.
### Managing OpenSearch UI administrators using the AWS CLI
You can create and update OpenSearch UI application administrators using the AWS CLI.
#### Creating OpenSearch UI administrators using the AWS CLI
The following are examples of adding IAM principals and IAM Identity Center users as administrators when creating an OpenSearch UI application.
##### Example 1: Create an OpenSearch UI application that adds an IAM user as an administrator
Run the following command to create an OpenSearch UI application that adds an IAM user as an administrator. Replace the *placeholder values* with your own information.
```
aws opensearch create-application \
--name application-name \
--app-configs "
{
\"key\":\"opensearchDashboards.dashboardAdmin.users\",
\"value\":\"arn:aws:iam::account-id:user/user-id\"
}
"
```
##### Example 2: Create an OpenSearch UI application that enables IAM Identity Center and adds an IAM Identity Center user ID as an OpenSearch UI application administrator
Run the following command to create an OpenSearch UI application that enables IAM Identity Center and adds an IAM Identity Center user ID as an OpenSearch UI application administrator. Replace the *placeholder values* with your own information.
`key` specifies the configuration item to set, such as the administrator role for the OpenSearch UI application. Valid values include `opensearchDashboards.dashboardAdmin.users` and `opensearchDashboards.dashboardAdmin.groups`.
*xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx* represents the value assigned to the key, such as the Amazon Resource Name (ARN) of an IAM user.
```
aws opensearch create-application \
--name myapplication \
--iam-identity-center-options "
{
\"enabled\":true,
\"iamIdentityCenterInstanceArn\":\"arn:aws:sso:::instance/ssoins-instance-id\",
\"iamRoleForIdentityCenterApplicationArn\":\"arn:aws:iam::account-id:role/role-name\"
}
" \
--app-configs "
{
\"key\":\"opensearchDashboards.dashboardAdmin.users\",
\"value\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"
}
"
```
#### Updating OpenSearch UI administrators using the AWS CLI
The following are examples of updating the IAM principals and IAM Identity Center users assigned as administrators for an existing OpenSearch application.
##### Example 1: Add an IAM user as an administrator for an existing OpenSearch application
Run the following command to update an OpenSearch UI application to add an IAM user as an administrator. Replace the *placeholder values* with your own information.
```
aws opensearch update-application \
--id myapplication \
--app-configs "
{
\"key\":\"opensearchDashboards.dashboardAdmin.users\",
\"value\":\"arn:aws:iam::account-id:user/user-id\"
}
"
```
##### Example 2: Update an OpenSearch UI application to add an IAM Identity Center user ID as an OpenSearch UI application administrator
Run the following command to update an OpenSearch UI application to add an IAM Identity Center user ID as an OpenSearch UI application administrator. Replace the *placeholder values* with your own information.
`key` specifies the configuration item to set, such as the administrator role for the OpenSearch UI application. Valid values include `opensearchDashboards.dashboardAdmin.users` and `opensearchDashboards.dashboardAdmin.groups`.
*xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx* represents the value assigned to the key, such as the Amazon Resource Name (ARN) of an IAM user.
```
aws opensearch update-application \
--id myapplication \
--app-configs "
{
\"key\":\"opensearchDashboards.dashboardAdmin.users\",
\"value\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"
}
"
```
# Agentic AI in Amazon OpenSearch Service
OpenSearch UI includes a suite of agentic AI capabilities designed to simplify operational analytics and accelerate incident investigations for your engineering and support teams.
On every page of your OpenSearch UI application, choose the **Ask AI** button to open Agentic Chat. Agentic Chat understands the context of the page you're viewing, uses agentic tools to analyze the underlying data, updates queries to display results in Discover, and answers your questions with clarity and accuracy. When a complex root cause analysis requires a deeper investigation, you can trigger the Investigation Agent to autonomously plan, execute, and reflect through a multi-step workflow, delivering structured hypotheses backed by data evidence. Powering both agentic capabilities is Agentic Memory, a memory layer that retains context within your conversation or investigation, so that you can continue to ask follow up questions with the same, consistent context across different web sessions.
![\[The Discover page in OpenSearch UI showing Agentic Chat generating a PPL query from the natural language input "find all requests with latency greater than 10 seconds," with the Ask AI panel displaying the query explanation and a Start Investigation button.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/agentic-chat-discover-ppl.png)
## Key capabilities
+ **Agentic Chat** – Embedded in the Ask AI feature on every page of OpenSearch UI, Agentic Chat understands your current context and calls tools to analyze data to best answer your questions. On Discover, enter natural language in the chat interface to generate and iterate Piped Processing Language (PPL) queries, so you don't need to be an expert in PPL to get actionable insights. You can also start conversations directly from visualizations, where Agentic Chat can identify anomalies in your graphs, correlate with the underlying data, and generate analysis. When a complex root cause analysis is needed, use the `/investigate` slash command to launch the Investigation Agent based on the ongoing conversation or with new instructions.
+ **Investigation Agent** – A goal-driven deep research agent that you activate by typing `/investigate` in chat or by choosing the **Start Investigation** button on feature pages. Enter an investigation goal such as "find the root cause of this latency spike." The Investigation Agent autonomously plans using your data and the stated goal, executes queries and analysis, and reflects through a multi-step workflow. When the investigation completes, typically within a few minutes, it generates structured hypotheses ranked by likelihood, each backed by data evidence. It provides full transparency into every step of its reasoning, so that you can verify and trust the results.
+ **Agentic Memory** – A service-managed memory layer that retains context within your conversation or investigation, so that you can continue to ask questions or investigate within a consistent context. Agentic Memory enables both Agentic Chat and the Investigation Agent to maintain continuity throughout a session.
## Pricing and usage limits
The agentic AI features are free to use. Token-based usage limits apply per account to prevent abuse.
The agentic AI features use a foundation model in Amazon Bedrock. All Amazon Bedrock security and data governance configurations apply to the agentic AI features. For more information, see [Data protection in Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/data-protection.html).
## Security
The agentic AI features operate within your existing security framework and do not bypass or override any configured access controls. When you interact with Agentic Chat or launch an Investigation Agent, the AI capabilities authenticate using your current IAM or IAM Identity Center credentials and inherit all associated permissions. The AI assistant can only query data sources, indices, and visualizations that you already have explicit access to through your existing role-based access control (RBAC) policies.
If your OpenSearch domain implements fine-grained access control with field-level or document-level security, the AI respects these restrictions and cannot surface data from restricted fields or documents that fall outside your permission scope. Similarly, any PPL queries generated by Agentic Chat or data retrievals performed during investigations are executed with your user context, ensuring that all configured security policies remain fully enforced.
This permission inheritance model ensures that enabling AI features does not create new security vulnerabilities or require administrators to manage separate permission structures for AI interactions.
## Enabling and disabling agentic AI features
The agentic AI features are automatically enabled for new OpenSearch UI applications, and for existing applications unless you have explicitly disabled AI features in any of your OpenSearch domains.
To enable or disable the AI features, you can use either the AWS Management Console or the API:
+ **Console** – Navigate to the details page of the OpenSearch UI application and update the AI features from there.
![\[The Manage AI Assistant features page in the console showing the Enable Chatbot and Agentic investigation feature checkbox and the Update button.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/agentic-ai-manage-features.png)
+ **API** – Use the [RegisterCapability](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_RegisterCapability.html) API to enable the AI features, or use the [DeregisterCapability](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DeregisterCapability.html) API to disable them.
## Region availability
The agentic AI features are available in the following AWS Regions:
+ Asia Pacific (Tokyo) – ap-northeast-1
+ Asia Pacific (Sydney) – ap-southeast-2
+ Europe (Frankfurt) – eu-central-1
+ Europe (Stockholm) – eu-north-1
+ Europe (Spain) – eu-south-2
+ Europe (Ireland) – eu-west-1
+ US East (N. Virginia) – us-east-1
+ US East (Ohio) – us-east-2
+ US West (Oregon) – us-west-2
**Topics**
+ [
## Key capabilities
](#application-ai-assistant-key-capabilities)
+ [
## Pricing and usage limits
](#application-ai-assistant-pricing)
+ [
## Security
](#application-ai-assistant-security)
+ [
## Enabling and disabling agentic AI features
](#application-ai-assistant-enable-disable)
+ [
## Region availability
](#application-ai-assistant-regions)
+ [
# Agentic Chat in Amazon OpenSearch Service
](application-agentic-chat.md)
+ [
# Investigation Agent in Amazon OpenSearch Service
](application-investigation-agent.md)
+ [
# Agentic Memory in Amazon OpenSearch Service
](application-agentic-memory.md)
# Agentic Chat in Amazon OpenSearch Service
Agentic Chat is an AI assistant embedded in every page of OpenSearch UI. Choose the **Ask AI** button to open the chat panel, where you can ask questions about your data, generate queries, and initiate investigations. Agentic Chat understands the context of the page you're viewing in Discover and Investigation, and uses agentic tools to analyze the underlying data.
![\[The Discover page in OpenSearch UI with the Ask AI button highlighted in the top right corner.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/agentic-chat-ask-ai-button.png)
When you open the chat panel, Agentic Chat presents options to help you get started: ask questions about your data, investigate an issue, or explain a concept. If you previously started a conversation, it remains visible in the chat panel as you navigate between pages, so that you can continue where you left off. Alternatively, choose the **New Chat** button in the top right corner to start a new conversation.
![\[The Agentic Chat panel showing the AI Assistant welcome message with options to ask questions about your data, investigate an issue, or explain a concept.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/agentic-chat-ask-ai-panel.png)
## Using Agentic Chat with Discover
On the Discover page in Observability workspaces, you can enter natural language in the chat interface to generate PPL queries. Agentic Chat translates your questions into PPL, executes the query, and displays the results directly in the Discover view. You don't need to be an expert in PPL to get actionable insights from your data.
To refine a generated query, ask follow-up questions in natural language, such as "add a filter for status code 500." Agentic Chat understands the context of the current query and modifies it accordingly. You can also ask to adjust aggregations, change time ranges, or add additional fields to the results. Each iteration updates the Discover view with the new query results.
## Using Agentic Chat with visualizations
You can start a conversation with Agentic Chat directly from a visualization. Open the context menu on a visualization panel and choose **Ask AI**. Agentic Chat analyzes the visualization, identifies anomalies in your graphs, correlates with the underlying data, and generates analysis.
![\[A visualization in OpenSearch UI showing the Ask AI option in the context menu, with the Agentic Chat panel analyzing the visualization.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/agentic-chat-visualization.png)
## Starting an investigation from chat
When a complex root cause analysis is needed, you can launch the Investigation Agent directly from Agentic Chat. Use the `/investigate` slash command in the chat input, or choose the **Start Investigation** button on feature pages.
For more information about the Investigation Agent, see [Investigation Agent in Amazon OpenSearch Service](application-investigation-agent.md).
## Supported tools
Agentic Chat uses the following tools to analyze your data and answer questions. To see the most up-to-date list of available tools, type "what tools can you use" in the chat interface.
**Frontend tools**
These tools update the OpenSearch UI:
+ `create_investigation` – Creates a new agentic investigation notebook with details such as goals, symptoms, index, and time range.
+ `execute_ppl_query` – Runs PPL queries against the current dataset and displays results in the Discover page.
+ `update_time_range` – Updates the global time range filter on the current Discover page (for example, "last 24 hours" or "last week").
**Backend tools**
These tools interact directly with OpenSearch data and APIs:
+ `SearchIndexTool` – Searches an index using DSL queries.
+ `MsearchTool` – Executes multiple search operations in a single request.
+ `CountTool` – Returns the number of documents matching a query.
+ `ExplainTool` – Explains why a document matches or doesn't match a query.
+ `ListIndexTool` – Lists indices in the cluster with optional detail.
+ `IndexMappingTool` – Retrieves index mappings and settings.
+ `GetShardsTool` – Gets shard information for an index.
+ `ClusterHealthTool` – Returns cluster health information.
+ `LogPatternAnalysisTool` – Analyzes log patterns, compares time ranges, or performs trace sequence analysis.
+ `MetricChangeAnalysisTool` – Compares percentile distributions of numeric fields between two time ranges.
+ `DataDistributionTool` – Analyzes field value distributions in a target time range, optionally compared to a baseline.
+ `GenericOpenSearchApiTool` – A flexible tool for calling any OpenSearch API endpoint directly.
# Investigation Agent in Amazon OpenSearch Service
The Investigation Agent is a goal-driven deep research agent in OpenSearch UI that autonomously investigates complex issues on your behalf. It plans using your data and the stated goal, executes queries and analysis, and reflects through a multi-step workflow. When the investigation completes, typically within a few minutes, it generates structured hypotheses ranked by likelihood, each backed by data evidence. It provides full transparency into every step of its reasoning, so that you can verify and trust the results.
## Starting an investigation
You can start an investigation in two ways:
+ From Discover, Visualization, or other supported feature pages, choose the **Start Investigation** button. A dialog appears where you can enter your investigation goal and select from suggested templates such as "Root cause analytics" or "Performance issues."
+ From Agentic Chat, type the `/investigate` slash command in the chat input with your investigation goal.
![\[The Start investigation dialog showing a text field for the investigation goal and suggested templates for root cause analytics and performance issues.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/investigation-agent-start.png)
For more information about Agentic Chat, see [Agentic Chat in Amazon OpenSearch Service](application-agentic-chat.md).
## Reviewing investigation results
When the investigation completes, the Investigation Agent presents a primary hypothesis with a confidence level and supporting evidence. The results page shows the investigation steps taken, relevant findings ranked by importance, and alternative hypotheses.
![\[The investigation results page showing a primary hypothesis with Accept and Rule out options, relevant findings ranked by importance, and alternative hypotheses.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/investigation-agent-results.png)
You can review the findings behind each hypothesis, then choose **Accept** to confirm the hypothesis or **Rule out** to reject it. Alternative hypotheses with lower likelihood are also available for review. You can select any alternative hypothesis as the final conclusion if it better matches your assessment.
## Reinvestigating
If the investigation results require more clarification, or if the Investigation Agent determines that the investigation question cannot be answered by the available datasets, you can use the **Reinvestigate** option to adjust and rerun the investigation. Choose **Reinvestigate** to edit the initial goal, adjust the time range, and optionally bring the existing hypotheses and findings into the new investigation.
![\[The Reinvestigate the issue dialog showing options to edit the initial goal, adjust the time range, and bring existing hypotheses and findings into the new investigation.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/investigation-agent-reinvestigate.png)
# Agentic Memory in Amazon OpenSearch Service
Agentic Memory is a service-managed memory layer that powers Agentic Chat and the Investigation Agent. It retains context within your conversation or investigation, so that you have a consistent experience across different feature pages, browser tabs, and page refreshes. Agentic Memory works automatically and requires no user configuration.
Agentic Memory is built on the OpenSearch agent memory framework. Memory storage is isolated by user ID for privacy.
## Data protection
Agentic Memory is free to use. Customer data stored in Agentic Memory is encrypted with a service-managed key. If you enabled customer managed key (CMK) encryption for your OpenSearch UI application, your memory data will be encrypted with your CMK instead. Memory is stored in a service-managed Amazon OpenSearch Serverless collection.
For more information about CMK encryption, see [Encrypting OpenSearch UI application metadata with customer managed keys](application-encryption-cmk.md).
## Limitations
Agentic Memory cannot retain context across different conversation threads.
# Encrypting OpenSearch UI application metadata with customer managed keys
Visual assets and configurations are stored as metadata for your OpenSearch UI applications. This includes saved queries, visualizations, and dashboards. Data from the associated data sources is not stored in the metadata. For information about encrypting data in your data sources, see [Data protection in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/data-protection.html) for OpenSearch domains and [Encryption in Amazon OpenSearch Serverless](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-encryption.html) for serverless collections.
Your OpenSearch UI metadata is protected with encryption at rest. This prevents unauthorized access. The encryption uses AWS Key Management Service (AWS KMS) to store and manage the encryption keys. By default, OpenSearch UI metadata is encrypted with AWS owned keys.
You can also use the customer managed key (CMK) feature to manage your own encryption keys. This helps you meet regulatory and compliance requirements. To use CMK, you must create a new OpenSearch UI application and enable CMK in the creation process. It is not currently supported to update an existing OpenSearch UI application from AWS owned key to CMK.
When to use customer managed keys:
+ Your organization has regulatory compliance requirements for key management
+ You need audit trails for encryption key usage
+ You want to control key rotation schedules
+ You need to integrate with existing key management workflows
When you use a customer managed key, you have full control over the key. This includes the ability to:
+ Establish and maintain key policies
+ Establish and maintain IAM policies and grants
+ Enable and disable the key
+ Rotate the key's cryptographic material
+ Add tags to the key
+ Create key aliases
+ Schedule the key for deletion
**Note**
The customer managed key must be in the same AWS Region as the OpenSearch UI application. You cannot use a key from a different Region.
**Topics**
+ [
## Prerequisites for using customer managed keys
](#application-encryption-cmk-prerequisites)
+ [
## Creating an application with customer managed key encryption using the console
](#application-encryption-cmk-create-console)
+ [
## Creating an application with customer managed key encryption using the AWS CLI
](#application-encryption-cmk-create-cli)
+ [
## Monitoring customer managed key usage
](#application-encryption-cmk-monitoring)
+ [
## Updating encryption settings
](#application-encryption-cmk-update)
## Prerequisites for using customer managed keys
Before you can use a customer managed key to encrypt your OpenSearch UI application metadata, you must create a symmetric encryption key in AWS KMS. For instructions on creating keys, see [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS KMS Developer Guide*.
The key policy for your customer managed key must grant OpenSearch UI permission to use the key. Use the following key policy, replacing the *placeholder values* with your own information:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowOpenSearchUIToUseKey",
"Effect": "Allow",
"Principal": {
"Service": [
"application.opensearchservice.amazonaws.com"
]
},
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:DescribeKey"
],
"Resource": "*"
},
{
"Sid": "AllowKeyAdministration",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::account-id:root"
},
"Action": "kms:*",
"Resource": "*"
}
]
}
```
The policy includes two statements:
+ The first statement allows OpenSearch UI to use the key for encryption operations.
+ The second statement allows users in your AWS account to administer the key. This includes permissions to update the key policy, enable or disable the key, and schedule the key for deletion. You can further restrict these permissions by replacing the root principal with specific IAM users or roles.
For more information about key policies, see [Using key policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) in the *AWS KMS Developer Guide*.
## Creating an application with customer managed key encryption using the console
When you create an OpenSearch UI application in the console, you can specify a customer managed key for encrypting the application's metadata.
**To create an OpenSearch UI application with customer managed key encryption using the console**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation pane, choose **OpenSearch UI (Dashboards)**.
1. Choose **Create application**.
1. For **Application name**, enter a name for the application.
1. Configure authentication and administrator settings as needed. For more information, see [Getting started with the OpenSearch user interface in Amazon OpenSearch Service](application-getting-started.md).
1. In the **Encryption** section, for **Encryption at rest**, choose **Use customer managed key**.
1. Select an existing customer managed key from the list, or choose **Create a key** to create a new key in AWS KMS.
**Note**
The key must be in the same AWS Region as the application you are creating.
1. (Optional) Add tags to the application.
1. Choose **Create**.
## Creating an application with customer managed key encryption using the AWS CLI
To create an OpenSearch UI application with customer managed key encryption using the AWS CLI, use the [create-application](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-application.html) command with the `--kms-key-arn` parameter.
Replace the *placeholder values* with your own information.
```
aws opensearch create-application \
--name my-application \
--kms-key-arn arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
```
If you don't specify the `--kms-key-arn` parameter, OpenSearch uses an AWS-managed key to encrypt the application's metadata.
## Monitoring customer managed key usage
When you use a customer managed key with an OpenSearch UI application, AWS KMS records every use of the key in AWS CloudTrail logs. You can use these logs to monitor how and when your key is used. The logs show which user or service accessed the key.
AWS AWS KMS automatically rotates customer managed keys every year. You can also manually rotate keys as needed. For more information about key rotation, see [Rotating KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) in the *AWS KMS Developer Guide*.
For more information about monitoring key usage, see [Logging AWS KMS API calls with AWS CloudTrail](https://docs.aws.amazon.com/kms/latest/developerguide/logging-using-cloudtrail.html) in the *AWS KMS Developer Guide*.
**Note**
Using customer managed keys incurs AWS KMS charges. Charges are based on the number of API requests and keys stored. For pricing details, see [AWS Key Management Service Pricing](https://aws.amazon.com/kms/pricing/).
## Updating encryption settings
After you create an OpenSearch UI application, you cannot change its encryption settings. If you need to use a different customer managed key, you must create a new application. If you need to switch between AWS-managed and customer managed keys, you must also create a new application with the desired encryption settings.
**Important**
Before you disable or delete a customer managed key, consider the following:
If you disable the key, the application will lose access to its encrypted metadata. You must re-enable the same key to restore access.
If you delete the key, the application's saved objects become permanently inaccessible. This includes queries, visualizations, and dashboards. Deleted keys cannot be recovered.
We recommend documenting your key ARN before making any changes to the key status.
**Next steps**
After you configure CMK encryption for your application, you can:
+ Associate data sources with your application. For more information, see [Managing data source associations and Virtual Private Cloud access permissions](application-data-sources-and-vpc.md).
+ Create workspaces for your team. For more information, see [Using Amazon OpenSearch Service workspaces](application-workspaces.md).
+ Set up AWS CloudTrail monitoring for key usage. For more information, see [Monitoring customer managed key usage](#application-encryption-cmk-monitoring).
# Enabling SAML federation with AWS Identity and Access Management
OpenSearch UI supports Security Assertion Markup Language 2.0 (SAML), an open standard that many identity providers use. This enables identity federation with AWS Identity and Access Management (IAM). With this support, users in your account or organization can directly access OpenSearch UI by assuming IAM roles. You can create an identity provider-initiated (IdP) single sign-on experience for your end users, where they can authenticate in the external identity provider and be routed directly to your defined page in OpenSearch UI. You can also implement fine-grained access control by configuring your end-users or groups to assume different IAM roles with different permissions for accessing OpenSearch UI and the associated data sources.
This topic presents step-by-step instructions for configuring SAML use with OpenSearch UI. In these procedures, we use the steps for configuring the Okta identity and access management application as an example. The configuration steps for other identity providers, such as Azure Active Directory and Ping, are similar.
**Topics**
+ [
## Step 1: Set up identity provider application (Okta)
](#SAML-identity-federation-step-1)
+ [
## Step 2: Set up AWS configuration for Okta
](#SAML-identity-federation-step-2)
+ [
## Step 3: Create the Amazon OpenSearch Service access policy in IAM
](#SAML-identity-federation-step-3)
+ [
## Step 4: Verify the identity provider-initiated Single Sign-On experience with SAML
](#SAML-identity-federation-step-4)
+ [
## Step 5: Configure SAML attribute-based fine-grained access control
](#SAML-identity-federation-step-5)
## Step 1: Set up identity provider application (Okta)
To use SAML with OpenSearch UI, the first step is to set up your identity provider.
**Task 1: Create Okta users**
1. Sign in to your Okta organization at [https://login.okta.com/](https://login.okta.com/) as a user with administrative privileges.
1. On the admin console, under **Directory** in the navigation pane, choose **People**.
1. Choose **Add person**.
1. For **First Name**, enter the user’s first name.
1. For **Last Name**, enter the user’s last name.
1. For **Username**, enter the user’s user name in email format.
1. Choose **I will set password** and enter a password
1. (Optional) Clear the **User must change password on first login** box if you don’t want the user to change the password at first sign in.
1. Choose **Save**.
**Task 2: Create and assign groups**
1. Sign in to your Okta organization at [https://login.okta.com/](https://login.okta.com/) as a user with administrative privileges.
1. On the admin console, under **Directory** in the navigation pane, choose **Groups**.
1. Choose **Add group**.
1. Enter a group name and choose **Save**.
1. Choose the newly created group, and then choose **Assign people**.
1. Choose the plus sign (**\$1**), and then choose **Done**.
1. (Optional) Repeat Steps 1–6 to add more groups.
**Task 3: Create Okta applications**
1. Sign in to your Okta organization at [https://login.okta.com/](https://login.okta.com/) as a user with administrative privileges.
1. On the admin console, under **Applications** in the navigation pane, choose **Applications**.
1. Choose **Create App Integration**.
1. Choose SAML 2.0 as the sign-in method, and then choose **Next**.
1. Enter a name for your app integration (for example, **OpenSearch\$1UI**), and then choose **Next**.
1. Enter following values in the app; you don't need to change other values:
1. 1. For **Single Sign On URL**, enter **https://signin.aws.amazon.com/saml** for the commercial AWS Regions, or the URL specific to your Region.
1. 2. For **Audience URI (SP Entity ID)**, enter **urn:amazon:webservices**.
1. 3. For **Name ID format**, enter **EmailAddress**.
1. Choose **Next**.
1. Choose **I’m an Okta customer adding an internal app**, and then choose **This is an internal app that we have created**.
1. Choose **Finish**.
1. Choose **Assignments**, and then choose **Assign**.
1. Choose **Assign to groups**, and then select **Assign** next to the groups that you want to add.
1. Choose **Done**.
**Task 4: Set up Okta advanced configuration**
After you create the custom SAML application, complete the following steps:
1. Sign in to your Okta organization at [https://login.okta.com/](https://login.okta.com/) as a user with administrative privileges.
On the administrator console, in the **General** area, choose **Edit** under **SAML settings**.
1. Choose **Next**.
1. Set **Default Relay State** to the OpenSearch UI endpoint, using the format:
`https://region.console.aws.amazon.com/aos/home?region=region#opensearch/applications/application-id/redirectToDashboardURL`.
The following is an example:
`https://us-east-2.console.aws.amazon.com/aos/home?region=us-east-2#opensearch/applications/abc123def4567EXAMPLE/redirectToDashboardURL`
1. Under **Attribute Statements (optional)**, add the following properties:
1. Provide the IAM role and identity provider in comma-separated format using the **Role** attribute. You’ll use this same IAM role and identity provider in a later step when setting up AWS configuration.
1. Set **user.login** for **RoleSessionName**. This is used as an identifier for the temporary credentials that are issued when the role is assumed.
For reference:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/application-enable-SAML-identity-federation.html)
1. After you add the attribute properties, choose **Next**, and then choose **Finish**.
Your attributes should be similar in format to those shown in the following image. The **Default Relay State** value is the URL to define the landing page for end-users in your account or organization after they complete the single sign-on validation from Okta. You can set it to any page in OpenSearch UI, and then provide that URL to its intended end-users.
![\[The "SAML 2.0" area reports the default relay state URL and metadata URL for an application.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/ui-saml-2.0-area-okta.png)
## Step 2: Set up AWS configuration for Okta
Complete the following tasks to set up your AWS configuration for Okta.
**Task 1: Gather Okta Information**
For this step, you will need to gather your Okta information so that you can later configure it in AWS.
1. Sign in to your Okta organization at [https://login.okta.com/](https://login.okta.com/) as a user with administrative privileges.
1. On the **Sign On** tab, in the lower right corner of the page, choose **View SAML setup instructions**.
1. Take note of the value for **Identity Provider Single Sign-on URL**. You can use this URL when connecting to any third-party SQL client such as [SQL Workbench/J](https://www.sql-workbench.eu/).
1. Use the identity provider metadata in block 4, and then save the metadata file in .xml format (for example, `metadata.xml`).
**Task 2: Create the IAM provider**
To create your IAM provider, complete the following steps:
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, under **Access management **, choose **Identity providers**.
1. Choose **Add provider**.
1. For **Provider type**¸ select **SAML**.
1. For **Provider name**¸ enter a name.
1. For **Metadata document**, choose **Choose file** and upload the metadata file (.xml) you downloaded earlier.
1. Choose **Add provider**.
**Task 3: Create IAM role**
To create your AWS Identity and Access Management role, complete the following steps:
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, under **Access management **, choose **Roles**.
1. Choose **Create role**.
1. For **Trusted entity type**, select **SAML 2.0 federation**.
1. For **SAML 2.0-based provider**, choose the identity provider you created earlier.
1. Select **Allow programmatic and AWS Management Console access**.
1. Choose **Next**.
1. In the **Permissions policies** list, select the check boxes for policies that grant OpenSearch Service permissions, for example, AWS managed policy **AmazonOpenSearchServiceFullAccess**.
1. Choose **Next**.
1. In the **Review** area, for **Role name**, enter the name of your role; for example, **oktarole**.
1. (Optional) For **Description**, enter a brief description of the purpose of the role.
1. Choose **Create role**.
1. Navigate to the role that you just created, choose the **Trust Relationships** tab, and then choose **Edit trust policy**.
1. In the **Edit statement** pane, under **Add actions for STS**, select the box for **TagSession**.
1. Choose **Update policy**.
## Step 3: Create the Amazon OpenSearch Service access policy in IAM
Learn how to configure your IAM roles for OpenSearch access control. With IAM roles, you can implement fine-grained access control for your Okta user groups to access OpenSearch resources. This topic demonstrates the IAM role-based configuration using two example groups.
------
#### [ Sample group: Alice ]
Request:
```
GET _plugins/_security/api/roles/alice-group
```
Result:
```
{
"alice-group": {
"reserved": false,
"hidden": false,
"cluster_permissions": [
"unlimited"
],
"index_permissions": [
{
"index_patterns": [
"alice*"
],
"dls": "",
"fls": [],
"masked_fields": [],
"allowed_actions": [
"indices_all"
]
}
],
"tenant_permissions": [
{
"tenant_patterns": [
"global_tenant"
],
"allowed_actions": [
"kibana_all_write"
]
}
],
"static": false
}
}
```
------
#### [ Sample group: Bob ]
Request:
```
GET _plugins/_security/api/roles/bob-group
```
Result:
```
{
"bob-group": {
"reserved": false,
"hidden": false,
"cluster_permissions": [
"unlimited"
],
"index_permissions": [
{
"index_patterns": [
"bob*"
],
"dls": "",
"fls": [],
"masked_fields": [],
"allowed_actions": [
"indices_all"
]
}
],
"tenant_permissions": [
{
"tenant_patterns": [
"global_tenant"
],
"allowed_actions": [
"kibana_all_write"
]
}
],
"static": false
}
}
```
------
You can map the Amazon OpenSearch Service domain roles to IAM roles using backend roles mapping, as demonstrated in the following example:
```
{
"bob-group": {
"hosts": [],
"users": [],
"reserved": false,
"hidden": false,
"backend_roles": [
"arn:aws:iam::111222333444:role/bob-group"
],
"and_backend_roles": []
},
"alice-group": {
"hosts": [],
"users": [],
"reserved": false,
"hidden": false,
"backend_roles": [
"arn:aws:iam::111222333444:role/alice-group"
],
"and_backend_roles": []
}
}
```
## Step 4: Verify the identity provider-initiated Single Sign-On experience with SAML
Open the URL for **Default Relay State** to open the Okta authentication page. Enter the credentials of an end-user. You are automatically redirected to OpenSearch UI.
You can check for your current credentials by choosing the user icon on the bottom of the navigation panel, as illustrated in the following image:
![\[Choosing the user icon in the Okta "Settings and setup" page displays the current user's credentials.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/ui-okta-user-icon.png)
You can also verify the fine-grained access control permissions for the user by accessing the Developer Tools on the bottom of the navigation panel and running queries in the console. The following are sample queries.
------
#### [ Example 1: Displays information about the current user ]
Request:
```
GET _plugins/_security/api/account
```
Result:
```
{
"user_name": "arn:aws:iam::XXXXXXXXXXXX:role/bob-group",
"is_reserved": false,
"is_hidden": false,
"is_internal_user": false,
"user_requested_tenant": null,
"backend_roles": [
"arn:aws:iam::XXXXXXXXXXXX:role/bob-group"
],
"custom_attribute_names": [],
"tenants": {
"global_tenant": true,
"arn:aws:iam::XXXXXXXXXXXX:role/bob-group": true
},
"roles": [
"bob-group"
]
}
```
------
#### [ Example 2: Displays actions permitted for a user ]
Request:
```
GET bob-test/_search
```
Result:
```
{
"took": 390,
"timed_out": false,
"_shards": {
"total": 5,
"successful": 5,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 1,
"hits": [
{
"_index": "bob-test",
"_id": "ui01N5UBCIHpjO8Jlvfy",
"_score": 1,
"_source": {
"title": "Your Name",
"year": "2016"
}
}
]
}
}
```
------
#### [ Example 3: Displays actions not permitted for a user ]
Request:
```
GET alice-test
```
Result:
```
{
"error": {
"root_cause": [
{
"type": "security_exception",
"reason": "no permissions for [indices:admin/get] and User [name=arn:aws:iam::111222333444:role/bob-group, backend_roles=[arn:aws:iam::111222333444:role/bob-group], requestedTenant=null]"
}
],
"type": "security_exception",
"reason": "no permissions for [indices:admin/get] and User [name=arn:aws:iam::111222333444:role/bob-group, backend_roles=[arn:aws:iam::111222333444:role/bob-group], requestedTenant=null]"
},
"status": 403
}
```
------
## Step 5: Configure SAML attribute-based fine-grained access control
With Amazon OpenSearch Service, you can use fine-grained access control with SAML to map users and groups from your identity provider to OpenSearch fine-grained access control users and roles dynamically. You can scope these roles to specific OpenSearch domains and serverless collections, and define index-level permissions and document-level security.
**Note**
For more information about fine-grained access control, see [Fine-grained access control in Amazon OpenSearch Service](fgac.md).
**Topics**
+ [
### SAML attributes for fine-grained access control
](#saml-fgac-key-attributes)
+ [
### Task 1: Configure Okta for fine-grained access control
](#configure-okta-fgac)
+ [
### Task 2: Configure SAML in OpenSearch domain
](#configure-opensearch-domain-fgac)
+ [
### Task 3: Configure SAML in OpenSearch Serverless collections
](#saml-configure-collections)
### SAML attributes for fine-grained access control
**subjectKey**
Maps to a unique user attribute, such as email or username, that identifies the user for authentication.
**rolesKey**
Maps to group or role attributes in your IdP that determine the roles or permissions for authorization.
### Task 1: Configure Okta for fine-grained access control
**To configure Okta for fine-grained access control**
1. Add a new attribute for the OpenSearch user principal in the **Attribute Statements** section:
+ Name: `UserName`
+ Value: `${user-email}`
This attribute is used as the **Subject key** in the OpenSearch fine-grained access control configuration for authentication.
1. Add a group attribute for roles in the **Group Attribute Statement** section:
+ Name: `groups`
+ Filter: `OpenSearch_xxx`
This attribute is used as the **Role key**for mapping groups to OpenSearch fine-grained access control roles for authorization.
### Task 2: Configure SAML in OpenSearch domain
**To configure SAML in OpenSearch domain**
1. In the AWS Management Console, identify the OpenSearch Service domain for which you want to enable fine-graned access control for the OpenSearch UI users.
1. Navigate to the details page of the specific domain.
1. Select the **Security configuration** tab and click **Edit**.
1. Expand **SAML via IAM Federate**.
1. Enter the `subjectKey` and `roleKey` that you defined in Okta.
1. Select**Save changes**.
You can also configure fine-grained access control using the AWS CLI.
```
aws opensearch create-domain \
--domain-name testDomain \
--engine-version OpenSearch_1.3 \
--cluster-config InstanceType=r5.xlarge.search,InstanceCount=1,DedicatedMasterEnabled=false,ZoneAwarenessEnabled=false,WarmEnabled=false \
--access-policies '{"Version": "2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"AWS":"*"},"Action":"es:*","Resource":"arn:aws:es:us-east-1:12345678901:domain/neosaml10/*"}]}' \
--domain-endpoint-options '{"EnforceHTTPS":true,"TLSSecurityPolicy":"Policy-Min-TLS-1-2-2019-07"}' \
--node-to-node-encryption-options '{"Enabled":true}' \
--encryption-at-rest-options '{"Enabled":true}' \
--advanced-security-options '{"Enabled":true,"InternalUserDatabaseEnabled":true,"MasterUserOptions":{"MasterUserName":"********","MasterUserPassword":"********"}, "IAMFederationOptions":{"Enabled": true,"SubjectKey":"TestSubjectKey","RolesKey":"TestRolesKey"}}' \
--ebs-options "EBSEnabled=true,VolumeType=gp2,VolumeSize=300" \
--no-verify-ssl \
--endpoint-url https://es.us-east-1.amazonaws.com \
--region us-east-1
```
To update an existing domain:
```
aws opensearch update-domain-config \
--domain-name testDomain \
--advanced-security-options '{"Enabled":true,"InternalUserDatabaseEnabled":true,"MasterUserOptions":{"MasterUserName":"********","MasterUserPassword":"********"}, "IAMFederationOptions":{"Enabled": true,"SubjectKey":"TestSubjectKey","RolesKey":"TestRolesKey"}}' \
--ebs-options "EBSEnabled=true,VolumeType=gp2,VolumeSize=300" \
--no-verify-ssl \
--endpoint-url https://es.us-east-1.amazonaws.com \
--region us-east-1
```
### Task 3: Configure SAML in OpenSearch Serverless collections
**To configure SAML-based fine-grained access control in OpenSearch Serverless**
1. Open the AWS Management Console and navigate to Amazon OpenSearch Service.
1. In the navigation pane, under **Serverless**, choose **Security**, and then choose **Authentication**.
1. In the **IAM Federation** section, select **Edit**.
You can control the SAML attribute-based fine-grained access control using this configuration. IAM Federation is disabled by default.
1. Select **Enable IAM Federation**.
1. Enter the `subjectKey` and `roleKey` values that you defined in Okta.
For more information, see [SAML attributes for fine-grained access control](#saml-fgac-key-attributes).
1. Select **Save**.
1. In the navigation pane under **Serverless**, choose **Data access policy**.
1. Either update an existing policy or create a new one.
1. Expand a rule, choose **Add principals**, and then select **IAM Federation users and groups**.
1. Add the required principals and choose **Save**.
1. Choose **Grant**.
1. Under this rule, do the following:
+ Select the permissions you want to define for the selected principals.
+ Specify the collections where you want to apply the permissions.
+ Optionally, define index-level permissions.
**Note**
You can create multiple rules to assign different permissions to different groups of principals.
1. When finished, choose **Save**.
1. Choose **Create**.
Alternatively, you can use CLI to create the security configurations for collections, as given below:
```
aws opensearchserverless create-security-config --region "region" --type iamfederation --name "configuration_name" --description "description" --iam-federation-options '{"groupAttribute":"GroupKey","userAttribute":"UserKey"}'
```
# Managing data source associations and Virtual Private Cloud access permissions
Use the procedures in this section to manage data source associations and to configure any needed access permissions for a virtual private cloud (VPC).
**Topics**
+ [
## Associating a data source with an OpenSearch UI application
](#application-data-source-association)
+ [
## Managing access to domains in a VPC
](#application-manage-vpc-access)
+ [
## Configuring access to OpenSearch Serverless collections in a VPC
](#application-configure-vpc-access-serverless-connections)
## Associating a data source with an OpenSearch UI application
After creating an OpenSearch UI application, you can use the console or AWS CLI to associate it with one or more data sources. After this, end-users can retrieve data from these data sources for searching, working with dashboards, and so on.
### Associate a data source with an OpenSearch UI application (console)
**To associate a data source with an OpenSearch UI application using the console**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. Choose **OpenSearch UI (Dashboards)**, and then choose the name of an OpenSearch UI application.
1. In the **Associated data sources** area, choose **Manage data sources**.
1. Choose from the OpenSearch domains and collections that you want to associate with the application.
**Tip**
If you are not finding the data sources you are looking for, contact your administrators to grant you the necessary permission. For more information, see [Permissions to create an application that uses IAM Identity Center authentication (optional)](application-getting-started.md#prerequisite-permissions-idc).
1. Choose **Next**, and then choose **Save**.
After you have associated a data source with the application, the **Launch Application** button is enabled on the application detail page. You can choose **Launch Application** to open the **Welcome to OpenSearch** page, where you can create and manage workspaces.
For information about working with workspaces, see [Using Amazon OpenSearch Service workspaces](application-workspaces.md).
## Managing access to domains in a VPC
If an OpenSearch domain in a VPC was associated with the application, a VPC administrator must authorize access between OpenSearch UI and VPC using the console or AWS CLI.
### Managing access to domains in a VPC (console)
**To configure the access to a VPC domain using the AWS Management Console:**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation pane, choose **Domains**, and the choose the name of the VPC domain.
-or-
Choose **Create domain**, and then configure the details for the domain.
1. Choose the **VPC endpoints** tab, and then choose **Authorize principal**.
1. In the **Authorize principals** dialog box, select **Authorize Principals from other AWS Services**, and then choose **OpenSearch applications (Dashboard)** from the list.
1. Choose **Authorize**.
### Managing access to domains in a VPC (AWS CLI)
**To authorize a VPC domain using the AWS CLI**
To authorize VPC domain using the AWS CLI, run the following command. Replace the *placeholder values* with your own information.
```
aws opensearch authorize-vpc-endpoint-access \
--domain-name domain-name \
--service application.opensearchservice.amazonaws.com \
--region region-id
```
**To revoke a VPC domain association using the console**
When an association is no longer needed, the VPC domain owner can revoke access using the following procedure.
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation pane, choose **Domains**, and the choose the name of the VPC domain.
1. Choose the **VPC endpoints** tab, and then select the button for the **OpenSearch applications (Dashboard)** row.
1. Choose **Revoke access**.
**To revoke a VPC domain association using the AWS CLI**
To revoke a VPC domain association with the OpenSearch UI application, run the following command. Replace the *placeholder values* with your own information.
```
aws opensearch revoke-vpc-endpoint-access \
--domain-name domain-name \
--service application.opensearchservice.amazonaws.com \
--region region-id
```
## Configuring access to OpenSearch Serverless collections in a VPC
If an Amazon OpenSearch Serverless collection in a VPC was associated with the application, a VPC administrator can authorize access by creating a new network policy and attaching it to the collection.
### Configuring access to OpenSearch Serverless collections in a VPC (console)
**To configure access to OpenSearch Serverless collections in a VPC using the console**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation, choose **Network policies**, choose the name of the network policy, and then choose **Edit**.
-or-
Choose **Create network policy**, and then configure the details for the policy.
1. In the **Access type** area, choose **Private (recommended)**, and then select **AWS service private access**.
1. In the search field, choose **Service**, and then choose `application.opensearchservice.amazonaws.com`.
1. In the **Resource type** area, select the **Enable access to OpenSearch endpoint** box.
1. For **Search collection(s), or input specific prefix term(s)**, in the search field, select **Collection Name**, and then enter or select the name of the collections to associate with the network policy.
1. Choose **Create** for a new network policy or **Update** for an existing network policy.
### Configuring access to OpenSearch Serverless collections in a VPC (AWS CLI)
**To configure access to OpenSearch Serverless collections in a VPC using the AWS CLI**
1. Create a .json file similar to the following. Replace the *placeholder values* with your own information.
```
{
"Description" : "policy-description",
"Rules": [{
"ResourceType" : "collection",
"Resource" : ["collection/collection_name"]
}],
"SourceServices" : [
"application.opensearchservice.amazonaws.com"
],
"AllowFromPublic" : false
}
```
1. Create or update a network policy for a collection in a VPC to work with OpenSearch UI applications.
------
#### [ Create a network policy ]
Run the following command. Replace the *placeholder values* with your own information.
```
aws opensearchserverless create-security-policy \
--type network \
--region region \
--endpoint-url endpoint-url \
--name network-policy-name \
--policy file:/path_to_network_policy_json_file
```
The command returns information similar to the following:
```
{
"securityPolicyDetail": {
"createdDate": ******,
"lastModifiedDate": ******,
"name": "network-policy-name",
"policy": [
{
"SourceVPCEs": [],
"AllowFromPublic": false,
"Description": "",
"Rules": [
{
"Resource": [
"collection/network-policy-name"
],
"ResourceType": "collection"
}
],
"SourceServices": [
"application.opensearchservice.amazonaws.com"
]
}
],
"policyVersion": "******",
"type": "network"
}
}
```
------
#### [ Update a network policy ]
Run the following command. Replace the *placeholder values* with your own information.
```
aws opensearchserverless update-security-policy \
--type network \
--region region \
--endpoint-url endpoint-url \
--name network-policy-name \
--policy-version "policy_version_from_output_of_network_policy_creation" \
--policy file:/path_to_network_policy_json_file
```
The command returns information similar to the following:
```
{
"securityPolicyDetail": {
"createdDate": ******,
"lastModifiedDate": ******,
"name": "network-policy-name",
"policy": [
{
"SourceVPCEs": [],
"AllowFromPublic": false,
"Description": "",
"Rules": [
{
"Resource": [
"collection/network-policy-name"
],
"ResourceType": "collection"
}
],
"SourceServices": [
"application.opensearchservice.amazonaws.com"
]
}
],
"policyVersion": "******",
"type": "network"
}
}
```
------
# Using Amazon OpenSearch Service workspaces
Amazon OpenSearch Service supports creating multiple use case-specific workspaces. Each workspace provides a curated experience for popular use cases such as Observability, Security Analytics and Search. Workspace also supports collaborator management, so that you can share your workspace with only your intended collaborators and manage the permissions for each one.
## Creating OpenSearch UI application workspaces
After an OpenSearch UI application has been created and associated with data sources, and user permissions have been configured for the application, you can launch the OpenSearch UI application to create workspaces.
To start creating a workspace, you can select the **Launch application** button on the application detail page or use the OpenSearch UI application URL to open the OpenSearch UI application homepage in a new browser window.
The OpenSearch UI application provides options for creating workspaces and lists all the existing workspaces in the homepage, categorized by use case.
![\[The "My workspaces" area in the console can be used to create five different types of workspaces: Observability, Security analytics, Search, Essentials, and Analytics. You can also view all existing workspaces in the "My workspaces" area.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/workspaces.png)
For more information about the supported types of workspaces, see [Workspace types](#application-workspaces-types).
## Workspace privacy and collaborators
You can define a privacy setting for a workspace as the default permission level for all users. You can do this while creating a workspace or modify an existing workspace (on the workspace **Collaborators** tab). There are three privacy options to choose from:
+ **Private to collaborators** – Only collaborators you explicitly add to the workspace can access the workspace. You can define permission levels for each collaborator.
+ ****Anyone can view**** – Anyone who has access to the OpenSearch UI application can access the workspace and view its assets, but they can't make any changes in the workspace.
+ ****Anyone can edit**** – Anyone who has access to the OpenSearch UI application can access the workspace, view assets in it, and make changes to the assets in the workspace.
On the workspace **Collaborators** tab, you can add IAM users or roles and AWS IAM Identity Center users as collaborators in a workspace. There are three levels of permissions for collaborators to choose from:
+ **Read only** – The collaborator can only view the assets in the workspace. This setting is overridden if the workspace is configured to use the **Anyone can edit** privacy setting.
+ **Read and write** – The collaborator can view and edit assets in the workspace. If the workspace configured to use the **Anyone can view** privacy setting, the collaborator can still edit.
+ **Admin** – The collaborator can update settings and delete the workspace. The collaborator can also change workspace privacy settings and manage collaborators. The user who creates the workspace is automatically assigned to be a workspace administrator.
## Workspace types
Amazon OpenSearch Service provides five workspace types, each with different features for the different use cases:
+ The **Observability** workspace is designed for gaining visibility into system health, performance, and reliability through monitoring of logs, metrics and traces.
+ The **Security Analytics** workspace is designed for detecting and investigating potential security threats and vulnerabilities across your systems and data.
+ The **Search** workspace is designed for quickly finding and exploring relevant information across your organization's data sources.
+ The **Essentials** workspace is designed for OpenSearch Serverless as a data source, and enables analyzing data to derive insights, identify patterns and trends, and make data-driven decisions quickly. You can find and explore relevant information across your organization's data sources in an **Essentials** workspace.
+ The **Analytics** (all features) workspace is designed for multi-purpose use cases and supports all the features available in OpenSearch Service UI (Dashboards).
# Cross-Region and cross-account data access
OpenSearch UI supports accessing data from OpenSearch domains across different AWS accounts and AWS Regions. You can choose from two approaches depending on your requirements. The following table compares the two approaches.
**Note**
Both cross-account data access and cross-cluster search work only with OpenSearch domains. Neither approach supports OpenSearch Serverless collections.
| Aspect | Cross-account data access | Cross-cluster search |
| --- | --- | --- |
| Feature | Associate domains from other accounts as direct data sources in OpenSearch UI | Query data across connected domains using cross-cluster search connections |
| Mechanism | Direct access – OpenSearch UI connects directly to the target domain in another account | Indirect access – requires a local domain in the same account as OpenSearch UI to relay requests to remote domains |
| Cross-account support | Yes | Yes |
| Cross-Region support | No – source and target domains must be in the same AWS Region | Yes – source and destination domains can be in different AWS Regions |
| Union data across domains | No – each domain is queried independently as a separate data source | Yes – a single query can aggregate results from multiple connected domains |
| Authentication methods | IAM and AWS IAM Identity Center | IAM (with fine-grained access control) |
| Setup complexity | Lower – requires a cross-account IAM role for validation | Higher – requires cross-cluster connections, access policies on both domains, and fine-grained access control |
| Data source visibility in OpenSearch UI | Each cross-account domain appears as a separate data source | Remote domains are accessed through the local source domain's connection aliases |
| Write access to remote domain | Yes – controlled by the target domain's access policy | No – cross-cluster search provides read-only access to remote domains |
**Topics**
+ [
# Cross-account data access to OpenSearch domains
](application-cross-account-data-access-domains.md)
+ [
# Cross-cluster search
](application-cross-cluster-search.md)
# Cross-account data access to OpenSearch domains
You can configure your OpenSearch UI applications in one account to access OpenSearch domains in different accounts. When you create an OpenSearch UI application with cross-account data sources, you provide an `iamRoleForDataSourceArn` that points to an IAM role in the target account. OpenSearch UI validates the request by assuming this role and calling `es:DescribeDomain` to verify domain accessibility. The cross-account role is used only for control plane validation. Data plane access is controlled separately by the target domain's access policy.
**Sample code**
The code examples in this topic are for illustration purposes only. They demonstrate basic functionality and may not include error handling, security best practices, or production-ready features. Before using sample code in production, review and modify it to meet your specific requirements, and test thoroughly in your environment.
## Key concepts
Source account
The AWS account that hosts your OpenSearch UI application.
Target account
The AWS account where the OpenSearch domain resides.
Cross-account role
An IAM role in the target account that is used for control plane validation only. This role requires only the `es:DescribeDomain` permission.
IAM Identity Center application role
An IAM role in the source account that is used for IAM Identity Center user data plane access.
## Prerequisites
Before you set up cross-account data access, ensure that you have the following:
+ AWS CLI installed and configured
+ Access to both the source and target AWS accounts
+ For IAM Identity Center flows: An AWS IAM Identity Center organization instance
## Scenarios
Choose the scenario that matches your authentication method and domain configuration:
+ [Scenario 1: IAM user accessing a public domain](#cross-account-scenario-1)
+ [Scenario 2: IAM Identity Center user accessing a public domain](#cross-account-scenario-2)
+ [Scenario 3: IAM user accessing a VPC domain](#cross-account-scenario-3)
+ [Scenario 4: IAM Identity Center user accessing a VPC domain](#cross-account-scenario-4)
## Scenario 1: IAM user accessing a public domain
### Step 1: Create the cross-account IAM role (target account)
Create an IAM role in the target account that allows the source account to assume it for domain validation.
**To create the cross-account role**
1. Create a trust policy that allows the source account to assume the role:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::source-account-id:root"
},
"Action": "sts:AssumeRole"
}]
}
```
1. Create the role:
```
aws iam create-role \
--role-name OpenSearchUIAccessRole \
--assume-role-policy-document file://trust-policy.json
```
1. Create a permissions policy with only the `es:DescribeDomain` action:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "es:DescribeDomain",
"Resource": "arn:aws:es:region:target-account-id:domain/*"
}]
}
```
1. Attach the permissions policy to the role:
```
aws iam put-role-policy \
--role-name OpenSearchUIAccessRole \
--policy-name ValidationOnly \
--policy-document file://permissions-policy.json
```
### Step 2: Create the OpenSearch domain (target account)
Create an OpenSearch domain in the target account with fine-grained access control and encryption enabled:
```
aws opensearch create-domain \
--domain-name domain-name \
--engine-version OpenSearch_2.19 \
--cluster-config InstanceType=m5.large.search,InstanceCount=1 \
--ebs-options "EBSEnabled=true,VolumeType=gp3,VolumeSize=100" \
--advanced-security-options '{"Enabled":true,"InternalUserDatabaseEnabled":true,"MasterUserOptions":{"MasterUserName":"admin","MasterUserPassword":"master-password"}}' \
--node-to-node-encryption-options '{"Enabled":true}' \
--encryption-at-rest-options '{"Enabled":true}' \
--domain-endpoint-options '{"EnforceHTTPS":true,"TLSSecurityPolicy":"Policy-Min-TLS-1-2-2019-07"}' \
--access-policies '{"Version":"2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"AWS":"*"},"Action":"es:ESHttp*","Resource":"arn:aws:es:region:target-account-id:domain/domain-name/*"}]}' \
--region region
```
Wait for the domain status to become `Active` before proceeding.
### Step 3: Create the OpenSearch UI application (source account)
Create the application in the source account with the cross-account data source:
```
aws opensearch create-application \
--region region \
--name "cross-account-iam-app" \
--data-sources '[{
"dataSourceArn":"arn:aws:es:region:target-account-id:domain/domain-name",
"dataSourceDescription":"Cross-account domain",
"iamRoleForDataSourceArn":"arn:aws:iam::target-account-id:role/OpenSearchUIAccessRole"
}]' \
--app-configs '[{"key":"opensearchDashboards.dashboardAdmin.users","value":"[\"*\"]"}]'
```
### Step 4: Verify and access
Retrieve the application details to get the endpoint URL:
```
aws opensearch get-application \
--region region \
--id application-id
```
+ Navigate to the application endpoint URL from the response.
+ Sign in with IAM credentials.
+ The IAM user signs data plane requests with their own credentials.
+ The target domain access policy controls what data the user can access.
## Scenario 2: IAM Identity Center user accessing a public domain
### Step 1: Create the cross-account IAM role (target account)
Create an IAM role in the target account that allows the source account to assume it for domain validation.
**To create the cross-account role**
1. Create a trust policy that allows the source account to assume the role:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::source-account-id:root"
},
"Action": "sts:AssumeRole"
}]
}
```
1. Create the role:
```
aws iam create-role \
--role-name OpenSearchUIAccessRole \
--assume-role-policy-document file://trust-policy.json
```
1. Create a permissions policy with only the `es:DescribeDomain` action:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "es:DescribeDomain",
"Resource": "arn:aws:es:region:target-account-id:domain/*"
}]
}
```
1. Attach the permissions policy to the role:
```
aws iam put-role-policy \
--role-name OpenSearchUIAccessRole \
--policy-name ValidationOnly \
--policy-document file://permissions-policy.json
```
### Step 2: Create the OpenSearch domain (target account)
Create an OpenSearch domain in the target account. Use the same command as [Step 2: Create the OpenSearch domain (target account)](#scenario-1-step-2), but update the access policy to allow the IAM Identity Center application role from the source account:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::source-account-id:role/NeoIdCAppRole"
},
"Action": "es:ESHttp*",
"Resource": "arn:aws:es:region:target-account-id:domain/domain-name/*"
}]
}
```
Wait for the domain status to become `Active` before proceeding.
### Step 3: Create the IAM role for IAM Identity Center application (source account)
Create an IAM role in the source account that OpenSearch UI uses for IAM Identity Center user data plane access.
**To create the IAM Identity Center application role**
1. Create a trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "application.opensearchservice.amazonaws.com"
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"Service": "application.opensearchservice.amazonaws.com"
},
"Action": "sts:SetContext",
"Condition": {
"ForAllValues:ArnEquals": {
"sts:RequestContextProviders": "arn:aws:iam::source-account-id:oidc-provider/portal.sso.region.amazonaws.com/apl/application-id"
}
}
}
]
}
```
1. Create a permissions policy:
```
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "OpenSearchDomain",
"Effect": "Allow",
"Action": ["es:ESHttp*"],
"Resource": "*"
}]
}
```
1. Create the role and attach the policies:
```
aws iam create-role \
--role-name NeoIdCAppRole \
--assume-role-policy-document file://neoidc-trust-policy.json
aws iam put-role-policy \
--role-name NeoIdCAppRole \
--policy-name NeoIdCAppPermissions \
--policy-document file://neoidc-permissions-policy.json
```
### Step 4: Create the OpenSearch UI application with IAM Identity Center (source account)
```
aws opensearch create-application \
--region region \
--name "cross-account-idc-app" \
--iam-identity-center-options '{
"enabled":true,
"iamIdentityCenterInstanceArn":"arn:aws:sso:::instance/ssoins-instance-id",
"iamRoleForIdentityCenterApplicationArn":"arn:aws:iam::source-account-id:role/NeoIdCAppRole"
}' \
--data-sources '[{
"dataSourceArn":"arn:aws:es:region:target-account-id:domain/domain-name",
"dataSourceDescription":"Cross-account domain",
"iamRoleForDataSourceArn":"arn:aws:iam::target-account-id:role/OpenSearchUIAccessRole"
}]' \
--app-configs '[{"key":"opensearchDashboards.dashboardAdmin.users","value":"[\"*\"]"}]'
```
### Step 5: Create and assign IAM Identity Center users and groups
**Create an IAM Identity Center user**
Run the following command. Replace the *placeholder values* with your own information.
```
aws identitystore create-user \
--identity-store-id d-directory-id \
--user-name user-email \
--display-name "display-name" \
--name Formatted=string,FamilyName=last-name,GivenName=first-name \
--emails Value=user-email,Type=work,Primary=true
```
**Create an IAM Identity Center group and add the user**
Run the following commands:
```
aws identitystore create-group \
--identity-store-id d-directory-id \
--display-name "OpenSearchUsers" \
--description "Users with OpenSearch access"
aws identitystore create-group-membership \
--identity-store-id d-directory-id \
--group-id group-id \
--member-id UserId=user-id
```
**Assign the user or group to the application**
Run the following command:
```
aws sso-admin create-application-assignment \
--application-arn "arn:aws:sso:::source-account-id:application/ssoins-instance-id/apl-application-id" \
--principal-id user-id-or-group-id \
--principal-type USER
```
**Configure backend role mapping on the target domain**
Map the IAM Identity Center group to an OpenSearch security role on the target domain:
```
curl -XPUT "https://domain-endpoint/_plugins/_security/api/rolesmapping/all_access" \
-u admin:master-password \
-H 'Content-Type: application/json' \
-d '{
"backend_roles": ["group-id"],
"hosts": [],
"users": []
}'
```
### Step 6: Verify and access
```
aws opensearch get-application \
--region region \
--id application-id
```
+ Navigate to the application endpoint URL.
+ Sign in with IAM Identity Center user credentials.
+ IAM Identity Center users' data requests are signed with the IAM Identity Center application role, not the cross-account role.
+ Backend role mappings on the domain control data access permissions.
## Scenario 3: IAM user accessing a VPC domain
### Step 1: Create the cross-account IAM role (target account)
Create an IAM role in the target account that allows the source account to assume it for domain validation.
**To create the cross-account role**
1. Create a trust policy that allows the source account to assume the role:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::source-account-id:root"
},
"Action": "sts:AssumeRole"
}]
}
```
1. Create the role:
```
aws iam create-role \
--role-name OpenSearchUIAccessRole \
--assume-role-policy-document file://trust-policy.json
```
1. Create a permissions policy with only the `es:DescribeDomain` action:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "es:DescribeDomain",
"Resource": "arn:aws:es:region:target-account-id:domain/*"
}]
}
```
1. Attach the permissions policy to the role:
```
aws iam put-role-policy \
--role-name OpenSearchUIAccessRole \
--policy-name ValidationOnly \
--policy-document file://permissions-policy.json
```
### Step 2: Set up the VPC (target account)
Skip this step if a VPC already exists in the target account.
```
# Create VPC
aws ec2 create-vpc \
--cidr-block 10.0.0.0/16 \
--region region
# Create subnet
aws ec2 create-subnet \
--vpc-id vpc-id \
--cidr-block 10.0.1.0/24 \
--availability-zone regiona \
--region region
# Create security group
aws ec2 create-security-group \
--group-name opensearch-vpc-sg \
--description "Security group for OpenSearch VPC domain" \
--vpc-id vpc-id \
--region region
# Allow inbound HTTPS
aws ec2 authorize-security-group-ingress \
--group-id security-group-id \
--protocol tcp \
--port 443 \
--cidr 10.0.0.0/16 \
--region region
```
Learn more about [VPC domain creation](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/vpc.html).
### Step 3: Create the VPC domain (target account)
```
aws opensearch create-domain \
--domain-name vpc-domain-name \
--engine-version OpenSearch_2.19 \
--cluster-config InstanceType=m5.large.search,InstanceCount=1 \
--ebs-options "EBSEnabled=true,VolumeType=gp3,VolumeSize=100" \
--vpc-options "SubnetIds=subnet-id,SecurityGroupIds=security-group-id" \
--advanced-security-options '{"Enabled":true,"InternalUserDatabaseEnabled":true,"MasterUserOptions":{"MasterUserName":"admin","MasterUserPassword":"master-password"}}' \
--node-to-node-encryption-options '{"Enabled":true}' \
--encryption-at-rest-options '{"Enabled":true}' \
--domain-endpoint-options '{"EnforceHTTPS":true,"TLSSecurityPolicy":"Policy-Min-TLS-1-2-2019-07"}' \
--access-policies '{"Version":"2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"AWS":"*"},"Action":"es:ESHttp*","Resource":"arn:aws:es:region:target-account-id:domain/vpc-domain-name/*"}]}' \
--region region
```
Wait for the domain status to become `Active` before proceeding.
### Step 4: Authorize the VPC endpoint for the OpenSearch UI service principal (target account)
**Important**
This is a critical step that is unique to VPC domains. The OpenSearch UI service must be explicitly authorized to access the VPC endpoint.
```
# Authorize the service principal
aws opensearch authorize-vpc-endpoint-access \
--domain-name vpc-domain-name \
--service "application.opensearchservice.amazonaws.com" \
--region region
# Verify authorization
aws opensearch list-vpc-endpoint-access \
--domain-name vpc-domain-name \
--region region
```
Expected response:
```
{
"AuthorizedPrincipalList": [
{
"PrincipalType": "AWS_SERVICE",
"Principal": "application.opensearchservice.amazonaws.com"
}
]
}
```
### Step 5: Create the OpenSearch UI application (source account)
```
aws opensearch create-application \
--region region \
--name "cross-account-vpc-iam-app" \
--data-sources '[{
"dataSourceArn":"arn:aws:es:region:target-account-id:domain/vpc-domain-name",
"dataSourceDescription":"Cross-account VPC domain",
"iamRoleForDataSourceArn":"arn:aws:iam::target-account-id:role/OpenSearchUIAccessRole"
}]' \
--app-configs '[{"key":"opensearchDashboards.dashboardAdmin.users","value":"[\"*\"]"}]'
```
### Step 6: Verify and access
Retrieve the application details to get the endpoint URL:
```
aws opensearch get-application \
--region region \
--id application-id
```
+ Navigate to the application endpoint URL from the response.
+ Sign in with IAM credentials.
+ The IAM user signs data plane requests with their own credentials.
+ The target domain access policy controls what data the user can access.
## Scenario 4: IAM Identity Center user accessing a VPC domain
### Step 1: Create the cross-account IAM role (target account)
Create an IAM role in the target account that allows the source account to assume it for domain validation.
**To create the cross-account role**
1. Create a trust policy that allows the source account to assume the role:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::source-account-id:root"
},
"Action": "sts:AssumeRole"
}]
}
```
1. Create the role:
```
aws iam create-role \
--role-name OpenSearchUIAccessRole \
--assume-role-policy-document file://trust-policy.json
```
1. Create a permissions policy with only the `es:DescribeDomain` action:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "es:DescribeDomain",
"Resource": "arn:aws:es:region:target-account-id:domain/*"
}]
}
```
1. Attach the permissions policy to the role:
```
aws iam put-role-policy \
--role-name OpenSearchUIAccessRole \
--policy-name ValidationOnly \
--policy-document file://permissions-policy.json
```
### Step 2: Set up the VPC (target account)
Skip this step if a VPC already exists in the target account.
```
# Create VPC
aws ec2 create-vpc \
--cidr-block 10.0.0.0/16 \
--region region
# Create subnet
aws ec2 create-subnet \
--vpc-id vpc-id \
--cidr-block 10.0.1.0/24 \
--availability-zone regiona \
--region region
# Create security group
aws ec2 create-security-group \
--group-name opensearch-vpc-sg \
--description "Security group for OpenSearch VPC domain" \
--vpc-id vpc-id \
--region region
# Allow inbound HTTPS
aws ec2 authorize-security-group-ingress \
--group-id security-group-id \
--protocol tcp \
--port 443 \
--cidr 10.0.0.0/16 \
--region region
```
Learn more about [VPC domain creation](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/vpc.html).
### Step 3: Create the VPC domain (target account)
Use the same command as [Step 3: Create the VPC domain (target account)](#scenario-3-step-3), but update the access policy to allow the IAM Identity Center application role from the source account:
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::source-account-id:role/NeoIdCAppRole"
},
"Action": "es:ESHttp*",
"Resource": "arn:aws:es:region:target-account-id:domain/vpc-domain-name/*"
}]
}
```
Wait for the domain status to become `Active` before proceeding.
### Step 4: Authorize the VPC endpoint for the OpenSearch UI service principal (target account)
**Important**
This is a critical step that is unique to VPC domains. The OpenSearch UI service must be explicitly authorized to access the VPC endpoint.
```
# Authorize the service principal
aws opensearch authorize-vpc-endpoint-access \
--domain-name vpc-domain-name \
--service "application.opensearchservice.amazonaws.com" \
--region region
# Verify authorization
aws opensearch list-vpc-endpoint-access \
--domain-name vpc-domain-name \
--region region
```
Expected response:
```
{
"AuthorizedPrincipalList": [
{
"PrincipalType": "AWS_SERVICE",
"Principal": "application.opensearchservice.amazonaws.com"
}
]
}
```
### Step 5: Create the IAM role for IAM Identity Center application (source account)
Create an IAM role in the source account that OpenSearch UI uses for IAM Identity Center user data plane access.
**To create the IAM Identity Center application role**
1. Create a trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "application.opensearchservice.amazonaws.com"
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"Service": "application.opensearchservice.amazonaws.com"
},
"Action": "sts:SetContext",
"Condition": {
"ForAllValues:ArnEquals": {
"sts:RequestContextProviders": "arn:aws:iam::source-account-id:oidc-provider/portal.sso.region.amazonaws.com/apl/application-id"
}
}
}
]
}
```
1. Create a permissions policy:
```
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "OpenSearchDomain",
"Effect": "Allow",
"Action": ["es:ESHttp*"],
"Resource": "*"
}]
}
```
1. Create the role and attach the policies:
```
aws iam create-role \
--role-name NeoIdCAppRole \
--assume-role-policy-document file://neoidc-trust-policy.json
aws iam put-role-policy \
--role-name NeoIdCAppRole \
--policy-name NeoIdCAppPermissions \
--policy-document file://neoidc-permissions-policy.json
```
### Step 6: Create the OpenSearch UI application with IAM Identity Center (source account)
```
aws opensearch create-application \
--region region \
--name "cross-account-vpc-idc-app" \
--iam-identity-center-options '{
"enabled":true,
"iamIdentityCenterInstanceArn":"arn:aws:sso:::instance/ssoins-instance-id",
"iamRoleForIdentityCenterApplicationArn":"arn:aws:iam::source-account-id:role/NeoIdCAppRole"
}' \
--data-sources '[{
"dataSourceArn":"arn:aws:es:region:target-account-id:domain/vpc-domain-name",
"dataSourceDescription":"Cross-account VPC domain",
"iamRoleForDataSourceArn":"arn:aws:iam::target-account-id:role/OpenSearchUIAccessRole"
}]' \
--app-configs '[{"key":"opensearchDashboards.dashboardAdmin.users","value":"[\"*\"]"}]'
```
### Step 7: Create and assign IAM Identity Center users and groups
**Create an IAM Identity Center user**
Run the following command. Replace the *placeholder values* with your own information.
```
aws identitystore create-user \
--identity-store-id d-directory-id \
--user-name user-email \
--display-name "display-name" \
--name Formatted=string,FamilyName=last-name,GivenName=first-name \
--emails Value=user-email,Type=work,Primary=true
```
**Create an IAM Identity Center group and add the user**
Run the following commands:
```
aws identitystore create-group \
--identity-store-id d-directory-id \
--display-name "OpenSearchUsers" \
--description "Users with OpenSearch access"
aws identitystore create-group-membership \
--identity-store-id d-directory-id \
--group-id group-id \
--member-id UserId=user-id
```
**Assign the user or group to the application**
Run the following command:
```
aws sso-admin create-application-assignment \
--application-arn "arn:aws:sso:::source-account-id:application/ssoins-instance-id/apl-application-id" \
--principal-id user-id-or-group-id \
--principal-type USER
```
**Configure backend role mapping on the target domain**
Map the IAM Identity Center group to an OpenSearch security role on the target domain:
```
curl -XPUT "https://domain-endpoint/_plugins/_security/api/rolesmapping/all_access" \
-u admin:master-password \
-H 'Content-Type: application/json' \
-d '{
"backend_roles": ["group-id"],
"hosts": [],
"users": []
}'
```
### Step 8: Verify and access
```
aws opensearch get-application \
--region region \
--id application-id
```
+ Navigate to the application endpoint URL.
+ Sign in with IAM Identity Center user credentials.
+ IAM Identity Center users' data requests are signed with the IAM Identity Center application role, not the cross-account role.
+ Backend role mappings on the domain control data access permissions.
## Managing applications
**Update an application with cross-account data sources**
Run the following command. Replace the *placeholder values* with your own information.
```
aws opensearch update-application \
--region region \
--id application-id \
--data-sources '[{
"dataSourceArn":"arn:aws:es:region:target-account-id:domain/domain-1",
"dataSourceDescription":"First cross-account domain",
"iamRoleForDataSourceArn":"arn:aws:iam::target-account-id:role/OpenSearchUIAccessRole"
},{
"dataSourceArn":"arn:aws:es:region:target-account-id:domain/domain-2",
"dataSourceDescription":"Second cross-account domain",
"iamRoleForDataSourceArn":"arn:aws:iam::target-account-id:role/OpenSearchUIAccessRole"
}]'
```
**Important**
The update operation replaces the entire data sources array. Include all data sources that you want to keep.
**List applications**
Run the following command:
```
aws opensearch list-applications \
--region region
```
**Delete an application**
Run the following command:
```
aws opensearch delete-application \
--region region \
--id application-id
```
**Revoke VPC endpoint access**
Run the following command:
```
aws opensearch revoke-vpc-endpoint-access \
--domain-name vpc-domain-name \
--service "application.opensearchservice.amazonaws.com" \
--region region
```
## Quick reference
The following tables summarize the key differences between domain types and authentication methods.
**Public domain compared to VPC domain**
| Aspect | Public domain | VPC domain |
| --- | --- | --- |
| VPC endpoint authorization | Not required | Required – must authorize application.opensearchservice.amazonaws.com |
| Network setup | None | VPC, subnet, security group with HTTPS (443) inbound |
| IAM access policy | Required | Required |
| Cross-account role | Required for cross-account | Required for cross-account |
**IAM user compared to IAM Identity Center user**
| Aspect | IAM user | IAM Identity Center user |
| --- | --- | --- |
| Data plane credentials | User's own IAM credentials | IAM Identity Center application role |
| Access control | Domain access policy | Domain access policy and backend role mappings |
| Additional setup | None | IAM Identity Center application role, user/group creation, application assignment, backend role mapping |
| OpenSearch UI application configuration | No IAM Identity Center options | --iam-identity-center-options required |
## Important notes
+ The `iamRoleForDataSourceArn` must be in the same account as the `dataSourceArn`.
+ The `iamRoleForDataSourceArn` is only required for cross-account data sources. Omit it for same-account data sources.
+ The cross-account role only needs the `es:DescribeDomain` permission. It is never used for data plane access.
+ For VPC domains, both the IAM policy and VPC endpoint authorization must be configured.
+ Supported engine versions: OpenSearch 1.3 and above.
## Troubleshooting
| Issue | Resolution |
| --- | --- |
| Application creation fails with "Unable to access domain" | Verify that the cross-account role has the es:DescribeDomain permission and that the trust policy allows the source account. |
| VPC domain association fails | Ensure that the VPC endpoint is authorized for application.opensearchservice.amazonaws.com. |
| Data plane access denied for IAM user | Check that the target domain access policy allows the IAM user or role principal. |
| Data plane access denied for IAM Identity Center user | Verify that the backend role mapping includes the IAM Identity Center group ID, and that the domain policy allows the IAM Identity Center application role. |
| Account mismatch error | Ensure that iamRoleForDataSourceArn is in the same account as the domain in dataSourceArn. |
# Cross-cluster search
Using [Cross-cluster search](cross-cluster-search.md) in Amazon OpenSearch Serverless, you can perform queries and aggregations across multiple connected domains.
Cross-cluster search in Amazon OpenSearch Serverless uses the concepts of a *source domain * and *destination domain*. A cross-cluster search request originates from a source domain. The destination domain can be in a different AWS account or AWS Region (or both) for the source domain to query from. Using cross-cluster search, you can configure a source domain to associate with your OpenSearch UI in the same account and then create connections to destination domains. As a result, you can use OpenSearch UI with data from the destination domains even if they are in a different account or Region.
You pay [standard AWS data transfer charges](https://aws.amazon.com/opensearch-service/pricing/) for data transferred in and out of Amazon OpenSearch Service. You are not charged for data transferred between nodes within your OpenSearch Service domain. For more information about data "in" and "out" charges, see [Data Transfer](https://aws.amazon.com/ec2/pricing/on-demand/#Data_Transfer) on the *Amazon EC2 On-Demand Pricing* page.
You can use cross-cluster search as the mechanism for your OpenSearch UI to be associated with clusters in a different account or different Region. The requests between domains are encrypted in transit by default as part of the node-to-node encryption.
**Note**
The open source OpenSearch tool also documents [cross-cluster search](https://opensearch.org/docs/latest/search-plugins/cross-cluster-search/). Note that setup for the open source tool differs significantly for open source clusters as compared to managed Amazon OpenSearch Serverless domains.
Most notably, in Amazon OpenSearch Serverless, you configure cross-cluster connections using the AWS Management Console instead of using `cURL` requests. The managed service uses AWS Identity and Access Management (IAM) for cross-cluster authentication in addition to fine-grained access control.
Therefore, we recommend using the content in this topic to configure cross-cluster search for your domains instead of the open source OpenSearch documentation.
**Functional differences when using cross-cluster search**
In comparison to regular domains, destination domains created using Cross-cluster search have the following functional differences and requirements:
+ You can't write to or run `PUT` commands to the remote cluster. Your access to the remote cluster is *read-only*.
+ Both the source and destination domain must be OpenSearch domains. You can't connect an Elasticsearch domain or self-managed OpenSearch/Elasticsearch clusters for OpenSearch UI.
+ A domain can have a maximum of 20 connections to other domains. This includes both outgoing and incoming connections.
+ The source domain must be on the same or a higher version of OpenSearch than the destination domain. If you want to set up bi-directional connections between two domains, the two domains should be in the same version. We recommend upgrading both domains to the latest version before making the connection. If you need to update domains after setting up the bi-directional connection, you must first delete the connection, and then recreate it afterwards.
+ You can't use custom dictionaries or SQL with the remote clusters.
+ You can't use CloudFormation to connect domains.
+ You can't use cross-cluster search on M3 or burstable (T2 and T3) instances.
+ Cross-cluster search does not work for Amazon OpenSearch Serverless collections.
**Cross-cluster search prerequisites for OpenSearch UI**
Before you set up cross-cluster search with two OpenSearch domains, make sure that your domains meet the following requirements:
+ Fine-grained access control is enabled for both domains
+ Node-to-node encryption is enabled for both domains
**Topics**
+ [
## Setting up access permissions for cross-Region and cross-account data access with cross-cluster search
](#cross-cluster-search-security)
+ [
## Creating a connection between domains
](#cross-cluster-search-create-connection)
+ [
## Testing your security setup for cross-Region and cross-account data access with cross-cluster search
](#cross-cluster-search-security-testing)
+ [
## Deleting a connection
](#cross-cluster-search-deleting-connection)
## Setting up access permissions for cross-Region and cross-account data access with cross-cluster search
When you send a cross-cluster search request to the source domain, the domain evaluates that request against its domain access policy. Cross-cluster search requires fine-grained access control. The following is an example with an open access policy on the source domain.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"*"
]
},
"Action": [
"es:ESHttp*"
],
"Resource": "arn:aws:es:us-east-1:111222333444:domain/src-domain/*"
}
]
}
```
------
**Note**
If you include remote indexes in the path, you must URL-encode the URI in the domain ARN.
For example, use the following ARN format:
`:arn:aws:es:us-east-1:111222333444:domain/my-domain/local_index,dst%3Aremote_index`
Do not use the following ARN format:
`arn:aws:es:us-east-1:111222333444:domain/my-domain/local_index,dst:remote_index.`
If you choose to use a restrictive access policy in addition to fine-grained access control, your policy must at minimum allow access to `es:ESHttpGet`. The following is an example:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111222333444:user/john-doe"
]
},
"Action": "es:ESHttpGet",
"Resource": "arn:aws:es:us-east-1:111122223333:domain/my-domain/*"
}
]
}
```
------
[Fine-grained access control](fgac.md) on the source domain evaluates the request to determine if it's signed with valid IAM or HTTP basic credentials. If it is, fine-grained access control next evaluates whether the user has permission to perform the search and access the data.
The following are the permission requirements for searches:
+ If the request searches only data on the destination domain (for example, `dest-alias:dest-index/_search)`, permissions are required only on the destination domain.
+ If the request searches data on both domains (for example, `source-index,dest-alias:dest-index/_search)`, permissions are required on both domains.
+ To use fine-grained access control, the permission `indices:admin/shards/search_shards` is required in addition to standard read or search permissions for the relevant indexes.
The source domain passes the request to the destination domain. The destination domain evaluates this request against its domain access policy. To support all features in OpenSearch UI, such as indexing documents and performing standard searches, full permissions must be set. The following is an example of our recommended policy on the destination domain:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"*"
]
},
"Action": [
"es:ESHttp*"
],
"Resource": "arn:aws:es:us-east-2:111222333444:domain/my-destination-domain/*"
},
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "es:ESCrossClusterGet",
"Resource": "arn:aws:es:us-east-2:111222333444:domain/"
}
]
}
```
------
If you want to perform only basic searches, the minimum policy requirement is for the `es:ESCrossClusterGet` permission to be applied for the destination domain without wildcard support. For example, in the preceding policy, you would specify the domain name as */my-destination-domain* and not */my-destination-domain/\$1*.
In this case, the destination domain performs the search and returns the results to the source domain. The source domain combines its own results (if any) with the results from the destination domain and returns them to you.
## Creating a connection between domains
A cross-cluster search connection is unidirectional from the source domain to the destination domain. This means that the destination domains (in a different account or Region) can't query the source domain, which is local to the OpenSearch UI. The source domain creates an *outbound* connection to the destination domain. The destination domain receives an *inbound* connection request from the source domain.
![\[This image illustrates that a cross-cluster search connection is unidirectional from the source domain to the destination domain.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/ui-oubound-inbound-connections.png)
**To create a connection between domains**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation, choose **Domains**.
1. Choose the name of a domain to serve as the source domain, and then choose the **Connections** tab.
1. In the **Outbound connections** area, choose **Request**.
1. For **Connection alias**, enter a name for your connection. The connection alias is used in OpenSearch UI for selecting the destination domains.
1. For **Connection mode**, choose **Direct** for cross-cluster searches or replication.
1. To specify that the connection should skip unavailable clusters during a search, select the **Skip unavailable clusters** box. Choosing this option ensures that your cross-cluster queries return partial results regardless of failures on one or more remote clusters.
1. For **Destination cluster**, choose between **Connect to a cluster in this AWS account** and **Connect to a cluster in another AWS account**.
1. For **Remote domain ARN**, enter the Amazon Resource Name (ARN) for the cluster. The domain ARN can be located in the **General information** area of the domain's detail page.
The domain must meet the following requirements:
+ The ARN must be in the format `arn:partition:es:regionaccount-id:type/domain-id`. For example:
`arn:aws:es:us-east-2:111222333444:domain/my-domain`
+ The domain must be configured to use OpenSearch version 1.0 (or later) or Elasticsearch version 6.7 (or later).
+ Fine-grained access control must be enabled on the domain.
+ The domain must be running OpenSearch.
1. Choose **Request**.
Cross-cluster search first validates the connection request to make sure the prerequisites are met. If the domains are incompatible, the connection request enters the `Validation failed` state.
If the connection request is validated successfully, it is sent to the destination domain, where it must be approved. Until this approval is given, the connection remains in a `Pending acceptance` state. When the connection request is accepted at the destination domain, the state changes to `Active` and the destination domain becomes available for queries.
The domain page shows you the overall domain health and instance health details of your destination domain. Only domain owners have the flexibility to create, view, remove, and monitor connections to or from their domains.
After the connection is established, any traffic that flows between the nodes of the connected domains is encrypted. When you connect a VPC domain to a non-VPC domain and the non-VPC domain is a public endpoint that can receive traffic from the internet, the cross-cluster traffic between the domains is still encrypted and secure.
## Testing your security setup for cross-Region and cross-account data access with cross-cluster search
After you've set up access permissions for cross-Region and cross-account data access with cross-cluster search, we recommend testing the setup using [https://www.postman.com/](https://www.postman.com/), a third-party platform for collaborative API development.
**To set your security setup using Postman**
1. On the destination domain, index a document. The following is a sample request:
```
POST https://dst-domain.us-east-1.es.amazonaws.com/books/_doc/1
{
"Dracula": "Bram Stoker"
}
```
1. To query this index from the source domain, include the connection alias of the destination domain within the query. You can find the connection alias on the Connections tab on your domain dashboard. The following are a sample request and truncated response:
```
GET https://src-domain.us-east-1.es.amazonaws.com/connection_alias:books/_search
{
...
"hits": [
{
"_index": "source-destination:books",
"_type": "_doc",
"_id": "1",
"_score": 1,
"_source": {
"Dracula": "Bram Stoker"
}
}
]
}
```
1. (Optional) You can create a configuration that includes multiple domains in a single search. For example, say that you set up the following:
A connection between `domain-a` to `domain-b`, with connection alias named `cluster_b`
A connection between `domain-a` to `domain-c`, with a connection alias named `cluster_c`
In this case, your searches include the content `domain-a`, `domain-b`, and `domain-c`. The following are a sample request and response:
Request
```
GET https://src-domain.us-east-1.es.amazonaws.com/local_index,cluster_b:b_index,cluster_c:c_index/_search
{
"query": {
"match": {
"user": "domino"
}
}
}
```
Response:
```
{
"took": 150,
"timed_out": false,
"_shards": {
"total": 3,
"successful": 3,
"failed": 0,
"skipped": 0
},
"_clusters": {
"total": 3,
"successful": 3,
"skipped": 0
},
"hits": {
"total": 3,
"max_score": 1,
"hits": [
{
"_index": "local_index",
"_type": "_doc",
"_id": "0",
"_score": 1,
"_source": {
"user": "domino",
"message": "This is message 1",
"likes": 0
}
},
{
"_index": "cluster_b:b_index",
"_type": "_doc",
"_id": "0",
"_score": 2,
"_source": {
"user": "domino",
"message": "This is message 2",
"likes": 0
}
},
{
"_index": "cluster_c:c_index",
"_type": "_doc",
"_id": "0",
"_score": 3,
"_source": {
"user": "domino",
"message": "This is message 3",
"likes": 0
}
}
]
}
}
```
If you did not choose to skip unavailable clusters in your connection setup, all destination clusters that you search must be available for your search request to run successfully. Otherwise, the whole request fails—even if one of the domains is not available, no search results are returned.
## Deleting a connection
Deleting a connection stops any cross-cluster search operations on the destination domain.
You can perform the following procedure on either the source or destination domain to remove the connection. After you remove the connection, it remains visible with a status of `Deleted` for 15 days.
You can't delete a domain with active cross-cluster connections. To delete a domain, first remove all incoming and outgoing connections from that domain. This ensures you take into account the cross-cluster domain users before deleting the domain.
**To delete a connection**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation, choose **Domains**.
1. Choose the name of a domain to delete, and then choose the **Connections** tab.
1. Select the name of a connection to delete.
1. Choose **Delete**, and then confirm the deletion.
# Managing access to the OpenSearch UI from a VPC endpoint
You can create a private connection between your VPC and OpenSearch UI using AWS PrivateLink. Using this connection, you can access OpenSearch UI applications as if they were in the same VPC. This way, you don't need to configure an internet gateway, NAT device, VPN connection, or AWS Direct Connect to establish the connection. Instances in your VPC don't need public IP addresses to access OpenSearch UI.
To establish this private connection, you first create an interface endpoint powered by AWS PrivateLink. An endpoint network interface is created automatically in each subnet that you specify for the interface endpoint. These are requester-managed network interfaces that serve as the entry point for traffic destined for OpenSearch UI applications.
## Creating a private connection between a VPC and OpenSearch UI
You can create a private connection for accessing OpenSearch UI from a VPC using the AWS Management Console or AWS CLI.
### Creating a private connection between a VPC and OpenSearch UI (console)
**To create a private connection between a VPC and OpenSearch UI using the console**
1. Sign in to the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. In the left navigation, under **Serverless**, choose **VPC endpoints**.
1. Choose **Create VPC endpoint**.
1. For **Name**, enter a name for the endpoint.
1. For **VPC**, select the VPC that you'll access OpenSearch UI applications from.
1. For **Subnets**, select one subnet that you'll access OpenSearch UI applications from.
**Note**
An endpoint's IP address and DNS type are based on subnet type:
Dual-stack: If all subnets have both IPv4 and IPv6 address ranges.
IPv6: If all subnets are IPv6 only subnets.
IPv4: If all subnets have IPv4 address ranges.
1. For **Security groups**, select one or more security group to associate with the endpoint network interfaces.
**Note**
In this step, you are limiting the ports, protocols, and sources for inbound traffic that you’re authorizing into your endpoint. Ensure that the security group rules allow the resources that will use the VPC endpoint to communicate with OpenSearch UI applications to also communicate with the endpoint network interface.
1. 8. Choose **Create endpoint**.
### Creating a private connection between a VPC and OpenSearch UI (AWS CLI)
**To create a private connection between a VPC and OpenSearch UI using the AWS CLI**
Run the following command. Replace the *placeholder values* with your own information.
```
aws opensearchserverless create-vpc-endpoint \
--region region \
--endpoint endpoint \
--name vpc_endpoint_name \
--vpc-id vpc_id \
--subnet-ids subnet_ids
```
## Updating the VPC endpoint policy to allow access to the OpenSearch UI application
After you create the private connection, update the VPC endpoint policy to allow access to the OpenSearch UI application in the VPC endpoint policy by specifying the application ID.
For information about updating a VPC endpoint policy, see [Update a VPC endpoint policy](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html#update-vpc-endpoint-policy) in the *AWS PrivateLink Guide*.
Ensure that the VPC endpoint policy includes the following statement. Replace the *placeholder value* with your own information.
```
{
"Statement": [{
"Action": ["opensearch:*"],
"Effect": "Allow",
"Principal": "*",
"Resource": "*",
"Condition": {
"StringEquals": {
"opensearch:ApplicationId": ["opensearch-ui-application-id"]
}
}
}]
}
```
## Revoking access to OpenSearch UI in a VPC endpoint policy
OpenSearch UI requires explicit permission in the VPC endpoint policy to allow users to access the application from the VPC. If you no longer want users to access OpenSearch UI from the VPC, you can remove the permission in the endpoint policy. After this, users encounter a `403 forbidden` error message when attempting to access OpenSearch UI.
For information about updating a VPC endpoint policy, see [Update a VPC endpoint policy](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html#update-vpc-endpoint-policy) in the *AWS PrivateLink Guide*.
The following is an example of VPC endpoint policy that denies access to the UI applications from the VPC:
```
{
"Statement": [{
"Action": ["opensearch:*"],
"Effect": "Allow",
"Principal": "*",
"Resource": "*",
"Condition": {
"StringEquals": {
"opensearch:ApplicationId": [""]
}
}
}]
}
```
# Migrating saved objects from OpenSearch Dashboards to OpenSearch UI
If you have existing dashboards, visualizations, index patterns, and other saved objects in OpenSearch Dashboards, you can migrate and reuse them in OpenSearch UI.
Benefits of migrating to OpenSearch UI:
+ **High availability** – OpenSearch UI is hosted in the AWS Cloud and remains available during domain upgrades and maintenance, while OpenSearch Dashboards is hosted within the domain and will be temporarily unavailable.
+ **Multiple Data Source** – OpenSearch UI can provide a consolidated single pane of glass across multiple data sources, including OpenSearch domains, serverless collections, and data connections with Amazon S3 and Amazon CloudWatch; while each OpenSearch Dashboards can only work with one domain or collection.
+ Additional features such as AI Assistant and Workspaces are available on OpenSearch UI. Learn more: [Using OpenSearch UI in Amazon OpenSearch Service](application.md).
**Topics**
+ [
## Migration overview
](#application-migrate-saved-objects-overview)
+ [
## Prerequisites
](#application-migrate-saved-objects-prerequisites)
+ [
## Step 1: Export saved objects from OpenSearch Dashboards
](#application-migrate-saved-objects-export)
+ [
## Step 2: Import saved objects into OpenSearch UI
](#application-migrate-saved-objects-import)
## Migration overview
The migration process consists of the following high-level steps:
1. **Export saved objects from OpenSearch Dashboards** – Use the OpenSearch Dashboards Saved Objects management UI or the export API to download your dashboards, visualizations, index patterns, and other objects as a newline-delimited JSON (NDJSON) file.
1. **Create an OpenSearch UI application and workspace** – If you have not already done so, create an OpenSearch UI application and a workspace to receive the imported objects.
1. **Register the data source in OpenSearch UI** – Associate your OpenSearch domain with the OpenSearch UI application and register it as a data source within the workspace. Index patterns in your imported objects reference this data source.
1. **Import saved objects into OpenSearch UI** – Use the OpenSearch UI Saved Objects management UI or the import API to upload the NDJSON file into the target workspace.
1. **Validate the imported objects** – Open your dashboards and visualizations in OpenSearch UI to verify that they display correctly and that data is flowing from the associated domain or collection.
## Prerequisites
Before the migration, verify the following prerequisites:
+ You have the necessary IAM permissions required to call the Amazon OpenSearch Service and OpenSearch APIs. For more information, see [Required permissions for creating Amazon OpenSearch Service applications](application-getting-started.md#application-prerequisite-permissions).
+ You can access the domain or collection and the OpenSearch Dashboards that you want to migrate.
+ You have create an OpenSearch UI application. For information about creating an application and workspace, see [Getting started with the OpenSearch user interface in Amazon OpenSearch Service](application-getting-started.md).
+ You have associated the same domain or collection to the OpenSearch UI application. For information about associating data sources, see [Managing data source associations and Virtual Private Cloud access permissions](application-data-sources-and-vpc.md).
**Note**
OpenSearch UI only supports OpenSearch version 1.3 and later. Verify that your OpenSearch domain is running version 1.3 or higher before attempting to migrate saved objects.
## Step 1: Export saved objects from OpenSearch Dashboards
Export your saved objects from OpenSearch Dashboards using the management UI or the export API. The export produces a newline-delimited JSON (NDJSON) file that contains all selected saved object types and their dependencies.
**Topics**
+ [
### Manually export on OpenSearch Dashboards
](#application-migrate-export-console)
+ [
### Exporting via API
](#application-migrate-export-api)
### Manually export on OpenSearch Dashboards
**To export saved objects using the OpenSearch Dashboards management UI**
1. Open your OpenSearch Dashboards instance.
1. In the left navigation panel, choose **Management**.
1. Under **Dashboards Management**, choose **Saved Objects**.
1. Select the saved objects you want to export. To export all objects of a specific type, filter by type using the search bar. To export all objects, select the check box in the table header.
1. Choose **Export**.
1. In the **Export saved objects** dialog box, ensure that **Include related objects** is selected. This option includes all objects that the selected saved objects depend on, such as index patterns referenced by visualizations. Clear this option only if you intend to manage dependencies manually.
1. Choose **Export** to download the `.ndjson` file to your local machine.
**Tip**
When you choose **Include related objects**, the exported NDJSON file contains all the saved objects needed to render the selected dashboards and visualizations, including their dependent index patterns, visualizations, and search objects. This simplifies the import step and avoids missing reference errors.
### Exporting via API
You can use the OpenSearch Dashboards Saved Objects export API to programmatically export saved objects. This is useful for automating migrations or integrating the export step into a CI/CD pipeline.
**Note**
If your OpenSearch domain has [fine-grained access control](fgac.md) enabled, you must provide authentication credentials with your export request. Use HTTP basic authentication by adding the `-u` flag with your username and password. For more information about authentication options, see [Fine-grained access control in Amazon OpenSearch Service](fgac.md).
The following example exports all dashboards with their related objects. Replace the *placeholder values* with your own information.
```
curl -X POST \
"https://dashboards-endpoint/_dashboards/api/saved_objects/_export" \
-u 'master-username:master-password' \
-H "Content-Type: application/json" \
-H "osd-xsrf: true" \
-d '{
"type": ["dashboard", "visualization", "index-pattern", "search"],
"includeReferencesDeep": true,
"excludeExportDetails": false
}' \
-o saved-objects-export.ndjson
```
If your domain does not have fine-grained access control enabled, you can omit the `-u` flag.
To export specific saved objects by ID, use the `objects` parameter instead of `type`:
```
curl -X POST \
"https://dashboards-endpoint/_dashboards/api/saved_objects/_export" \
-u 'master-username:master-password' \
-H "Content-Type: application/json" \
-H "osd-xsrf: true" \
-d '{
"objects": [
{"type": "dashboard", "id": "dashboard-id"},
{"type": "visualization", "id": "visualization-id"}
],
"includeReferencesDeep": true
}' \
-o saved-objects-export.ndjson
```
**Note**
To find saved object IDs, you can use the Saved Objects API to list all objects of a specific type. The following example lists all dashboards:
```
curl -X GET \
"https://dashboards-endpoint/_dashboards/api/saved_objects/_find?type=dashboard" \
-u 'master-username:master-password'
```
The response includes the ID for each saved object. You can also find the ID in the browser URL when viewing the object in OpenSearch Dashboards.
## Step 2: Import saved objects into OpenSearch UI
After exporting the saved objects, you can import the NDJSON file to OpenSearch UI manually or via API.
**Topics**
+ [
### Manually import on OpenSearch UI
](#application-migrate-import-console)
+ [
### Import via API
](#application-migrate-import-api)
### Manually import on OpenSearch UI
**To import saved objects using the OpenSearch UI management UI**
1. Open your OpenSearch UI application and navigate to the target workspace.
1. In the workspace, choose **Assets** from the top navigation or go to the workspace assets page.
1. Choose **Import** to open the **Import assets** dialog.
1. Choose **Select file** and select the `.ndjson` file you exported from OpenSearch Dashboards.
1. For **Conflict management**, choose one of the following:
+ **Create new assets with unique IDs** (default) – Generates new IDs for all imported objects, avoiding conflicts with existing assets.
+ **Check for existing assets** – Checks for conflicts with existing objects. When selected, choose one of the following sub-options:
+ **Automatically overwrite conflicts** – Existing assets with the same ID are automatically replaced.
+ **Request action on conflict** – You are prompted to resolve each conflict individually.
1. Choose **Import**.
1. Review the import summary.
### Import via API
To import saved objects using the API with AWS Signature Version 4 authentication, you must first get the data source ID, then use it in the import request. Replace the *placeholder values* with your own information.
Step 1: Get the data source ID for your workspace:
```
curl -X GET \
"https://opensearch-ui-endpoint/w/workspace-id/api/saved_objects/_find?type=data-source" \
--aws-sigv4 "aws:amz:region:opensearch" \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
-H "x-amz-security-token: $AWS_SESSION_TOKEN" \
-H "osd-xsrf: true"
```
**Note**
The response includes the data source ID. You can also find the data source ID in the browser URL when viewing the data source in OpenSearch UI.
Step 2: Import the saved objects using the data source ID from Step 1:
```
curl -X POST \
"https://opensearch-ui-endpoint/w/workspace-id/api/saved_objects/_import?overwrite=true&dataSourceId=data-source-id" \
--aws-sigv4 "aws:amz:region:opensearch" \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
-H "x-amz-security-token: $AWS_SESSION_TOKEN" \
-H "osd-xsrf: true" \
-F "file=@saved-objects-export.ndjson"
```
**Note**
These examples use curl's built-in `--aws-sigv4` option (available in curl 7.75 or later) to sign the requests. Set your AWS credentials as environment variables before running the commands: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` (if using temporary credentials).
# OpenSearch UI endpoints and quotas
To connect programmatically to an AWS service, you use an endpoint. Service quotas, also referred to as limits, are the maximum number of service resources or operations for your AWS account.
Amazon OpenSearch UI is the next generation OpenSearch user interface for OpenSearch Dashboards. It provides endpoints for accessing your OpenSearch dashboards. Use this topic to find the service endpoints and service quotas for OpenSearch UI.
For more information on other OpenSearch services, see [ Service Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/opensearch-service.html).
## OpenSearch UI endpoints
OpenSearch UI is available in the following Regions:
| Region name | Region | Endpoint | Protocol |
| --- | --- | --- | --- |
| Asia Pacific (Mumbai) | ap-south-1 | opensearch.ap-south-1.amazonaws.com es.ap-south-1.amazonaws.com | HTTPS HTTPS |
| Europe (Paris) | eu-west-3 | opensearch.eu-west-3.amazonaws.com es.eu-west-3.amazonaws.com | HTTPS HTTPS |
| US East (Ohio) | us-east-2 | opensearch.us-east-2.amazonaws.com es.us-east-2.amazonaws.com | HTTPS HTTPS |
| Europe (Ireland) | eu-west-1 | opensearch.eu-west-1.amazonaws.com es.eu-west-1.amazonaws.com | HTTPS HTTPS |
| Europe (Frankfurt) | eu-central-1 | opensearch.eu-central-1.amazonaws.com es.eu-central-1.amazonaws.com | HTTPS HTTPS |
| South America (São Paulo) | sa-east-1 | opensearch.sa-east-1.amazonaws.com es.sa-east-1.amazonaws.com | HTTPS HTTPS |
| US East (N. Virginia) | us-east-1 | opensearch.us-east-1.amazonaws.com es.us-east-1.amazonaws.com | HTTPS HTTPS |
| Europe (London) | eu-west-2 | opensearch.eu-west-2.amazonaws.com es.eu-west-2.amazonaws.com | HTTPS HTTPS |
| Asia Pacific (Tokyo) | ap-northeast-1 | opensearch.ap-northeast-1.amazonaws.com es.ap-northeast-1.amazonaws.com | HTTPS HTTPS |
| US West (Oregon) | us-west-2 | opensearch.us-west-2.amazonaws.com es.us-west-2.amazonaws.com | HTTPS HTTPS |
| Asia Pacific (Singapore) | ap-southeast-1 | opensearch.ap-southeast-1.amazonaws.com es.ap-southeast-1.amazonaws.com | HTTPS HTTPS |
| Asia Pacific (Sydney) | ap-southeast-2 | opensearch.ap-southeast-2.amazonaws.com es.ap-southeast-2.amazonaws.com | HTTPS HTTPS |
| Canada (Central) | ca-central-1 | opensearch.ca-central-1.amazonaws.com es.ca-central-1.amazonaws.com | HTTPS HTTPS |
| Europe (Stockholm) | eu-north-1 | opensearch.eu-north-1.amazonaws.com es.eu-north-1.amazonaws.com | HTTPS HTTPS |
| Asia Pacific (Hong Kong) | ap-east-1 | opensearch.ap-east-1.amazonaws.com es.ap-east-1.amazonaws.com | HTTPS HTTPS |
| Asia Pacific (Seoul) | ap-northeast-2 | opensearch.ap-northeast-2.amazonaws.com es.ap-northeast-2.amazonaws.com | HTTPS HTTPS |
| Asia Pacific (Osaka) | ap-northeast-3 | opensearch.ap-northeast-3.amazonaws.com es.ap-northeast-3.amazonaws.com | HTTPS HTTPS |
| Asia Pacific (Hyderabad) | ap-south-2 | opensearch.ap-south-2.amazonaws.com es.ap-south-2.amazonaws.com | HTTPS HTTPS |
| Europe (Spain) | eu-south-2 | opensearch.eu-south-2.amazonaws.com es.eu-south-2.amazonaws.com | HTTPS HTTPS |
| US West (N. California) | us-west-1 | opensearch.us-west-1.amazonaws.com es.us-west-1.amazonaws.com | HTTPS HTTPS |
| Europe (Zurich) | eu-central-2 | opensearch.eu-central-2.amazonaws.com es.eu-central-2.amazonaws.com | HTTPS HTTPS |
| Europe (Milan) | eu-south-1 | opensearch.eu-south-1.amazonaws.com es.eu-south-1.amazonaws.com | HTTPS HTTPS |
## OpenSearch UI service quotas
Your AWS account has the following quotas related to OpenSearch UI resources.
| Name | Default | Adjustable | Notes |
| --- | --- | --- | --- |
| OpenSearch UI applications per Account per Region | 30 | Yes | The maximum number of OpenSearch UI applications you can create per account per Region. You can increase the limit to 50 using service quota and get it automatically approved. To request a higher limit, submit a support ticket. |