# Overview of security in Amazon OpenSearch Serverless
Security in Amazon OpenSearch Serverless differs fundamentally from security in Amazon OpenSearch Service in the following ways:
| Feature | OpenSearch Service | OpenSearch Serverless |
| --- | --- | --- |
| Data access control | Data access is determined by IAM policies and fine-grained access control. | Data access is determined by data access policies. |
| Encryption at rest | Encryption at rest is optional for domains. | Encryption at rest is required for collections. |
| Security setup and administration | You must configure network, encryption, and data access individually for each domain. | You can use security policies to manage security settings for multiple collections at scale. |
The following diagram illustrates the security components that make up a functional collection. A collection must have an assigned encryption key, network access settings, and a matching data access policy that grants permission to its resources.
![\[Diagram showing encryption, network, data access, and authentication policies for a collection.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/serverless-security.png)
**Topics**
+ [Encryption policies](#serverless-security-encryption)
+ [Network policies](#serverless-security-network)
+ [Data access policies](#serverless-security-data-access)
+ [IAM and SAML authentication](#serverless-security-authentication)
+ [Infrastructure security](#serverless-infrastructure-security)
+ [Getting started with security in Amazon OpenSearch Serverless](serverless-tutorials.md)
+ [Identity and Access Management for Amazon OpenSearch Serverless](security-iam-serverless.md)
+ [Encryption in Amazon OpenSearch Serverless](serverless-encryption.md)
+ [Network access for Amazon OpenSearch Serverless](serverless-network.md)
+ [FIPS compliance in Amazon OpenSearch Serverless](fips-compliance-opensearch-serverless.md)
+ [Data access control for Amazon OpenSearch Serverless](serverless-data-access.md)
+ [Data plane access through AWS PrivateLink](serverless-vpc.md)
+ [Control plane access through AWS PrivateLink](serverless-vpc-cp.md)
+ [SAML authentication for Amazon OpenSearch Serverless](serverless-saml.md)
+ [Compliance validation for Amazon OpenSearch Serverless](serverless-compliance-validation.md)
## Encryption policies
[Encryption policies](serverless-encryption.md) define whether your collections are encrypted with an AWS owned key or a customer managed key. Encryption policies consist of two components: a **resource pattern** and an **encryption key**. The resource pattern defines which collection or collections the policy applies to. The encryption key determines how the associated collections will be secured.
To apply a policy to multiple collections, you include a wildcard (\$1) in the policy rule. For example, the following policy applies to all collections with names that begin with "logs".
![\[Input field for specifying a prefix term or collection name, with "logs*" entered.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/serverless-security-encryption.png)
Encryption policies streamline the process of creating and managing collections, especially when you do so programmatically. You can create a collection by specifying a name, and an encryption key is automatically assigned to it upon creation.
## Network policies
[Network policies](serverless-network.md) define whether your collections are accessible privately, or over the internet from public networks. Private collections can be accessed through OpenSearch Serverless–managed VPC endpoints, or by specific AWS services such as Amazon Bedrock using *AWS service private access*. Just like encryption policies, network policies can apply to multiple collections, which allows you to manage network access for many collections at scale.
Network policies consist of two components: an **access type** and a **resource type**. The access type can either be public or private. The resource type determines whether the access you choose applies to the collection endpoint, the OpenSearch Dashboards endpoint, or both.
![\[Access type and resource type options for configuring network policies in OpenSearch.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/serverless-security-network.png)
If you plan to configure VPC access within a network policy, you must first create one or more [OpenSearch Serverless-managed VPC endpoints](serverless-vpc.md). These endpoints let you access OpenSearch Serverless as if it were in your VPC, without the use of an internet gateway, NAT device, VPN connection, or Direct Connect connection.
Private access to AWS services can only apply to the collection's OpenSearch endpoint, not to the OpenSearch Dashboards endpoint. AWS services cannot be granted access to OpenSearch Dashboards.
## Data access policies
[Data access policies](serverless-data-access.md) define how your users access the data within your collections. Data access policies help you manage collections at scale by automatically assigning access permissions to collections and indexes that match a specific pattern. Multiple policies can apply to a single resource.
Data access policies consist of a set of rules, each with three components: a **resource type**, **granted resources**, and a set of **permissions**. The resource type can be a collection or index. The granted resources can be collection/index names or patterns with a wildcard (\$1). The list of permissions specifies which [OpenSearch API operations](serverless-genref.md#serverless-operations) the policy grants access to. In addition, the policy contains a list of **principals**, which specify the IAM roles, users, and SAML identities to grant access to.
![\[Selected principals and granted resources with permissions for collection and index access.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/serverless-data-access.png)
For more information about the format of a data access policy, see the [policy syntax](serverless-data-access.md#serverless-data-access-syntax).
Before you create a data access policy, you must have one or more IAM roles or users, or SAML identities, to provide access to in the policy. For details, see the next section.
**Note**
Switching from Public to Private Access for your collection, will remove the Indexes Tab in the OpenSearch Serverless Collection Console.
## IAM and SAML authentication
IAM principals and SAML identities are one of the building blocks of a data access policy. Within the `principal` statement of an access policy, you can include IAM roles, users, and SAML identities. These principals are then granted the permissions that you specify in the associated policy rules.
```
[
{
"Rules":[
{
"ResourceType":"index",
"Resource":[
"index/marketing/orders*"
],
"Permission":[
"aoss:*"
]
}
],
"Principal":[
"arn:aws:iam::123456789012:user/Dale",
"arn:aws:iam::123456789012:role/RegulatoryCompliance",
"saml/123456789012/myprovider/user/Annie"
]
}
]
```
You configure SAML authentication directly within OpenSearch Serverless. For more information, see [SAML authentication for Amazon OpenSearch Serverless](serverless-saml.md).
## Infrastructure security
Amazon OpenSearch Serverless is protected by AWS global network security. For information about AWS security services and how AWS protects infrastructure, see [AWS Cloud Security](https://aws.amazon.com/security/). To design your AWS environment using the best practices for infrastructure security, see [Infrastructure Protection](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/infrastructure-protection.html) in *Security Pillar AWS Well‐Architected Framework*.
You use AWS published API calls to access Amazon OpenSearch Serverless through the network. Clients must support Transport Layer Security (TLS). We require TLS 1.2 and recommend TLS 1.3. For a list of supported ciphers for TLS 1.3, see [TLS protocols and ciphers](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-tls-listener.html#tls-protocols-ciphers) in the Elastic Load Balancing documentation.
Additionally, you must sign requests using an access key ID and a secret access key that is associated with an IAM principal. Or you can use the [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) (AWS STS) to generate temporary security credentials to sign requests.
# Getting started with security in Amazon OpenSearch Serverless
The following tutorials help you get started using Amazon OpenSearch Serverless. Both tutorials accomplish the same basic steps, but one uses the console while the other uses the AWS CLI.
Note that the use cases in these tutorials are simplified. The network and security policies are fairly open. In production workloads, we recommend that you configure more robust security features such as SAML authentication, VPC access, and restrictive data access policies.
**Topics**
+ [Tutorial: Getting started with security in Amazon OpenSearch Serverless (console)](gsg-serverless.md)
+ [Tutorial: Getting started with security in Amazon OpenSearch Serverless (CLI)](gsg-serverless-cli.md)
# Tutorial: Getting started with security in Amazon OpenSearch Serverless (console)
This tutorial walks you through the basic steps to create and manage security policies using the Amazon OpenSearch Serverless console.
You will complete the following steps in this tutorial:
1. [Configure permissions](#gsgpermissions)
1. [Create an encryption policy](#gsg-encryption)
1. [Create a network policy](#gsg-network)
1. [Configure a data access policy](#gsg-data-access)
1. [Create a collection](#gsgcreate-collection)
1. [Upload and search data](#gsgindex-collection)
This tutorial walks you through setting up a collection using the AWS Management Console. For the same steps using the AWS CLI, see [Tutorial: Getting started with security in Amazon OpenSearch Serverless (CLI)](gsg-serverless-cli.md).
## Step 1: Configure permissions
**Note**
You can skip this step if you're already using a more broad identity-based policy, such as `Action":"aoss:*"` or `Action":"*"`. In production environments, however, we recommend that you follow the principal of least privilege and only assign the minimum permissions necessary to complete a task.
In order to complete this tutorial, you must have the correct IAM permissions. Your user or role must have an attached [identity-based policy](security-iam-serverless.md#security-iam-serverless-id-based-policies) with the following minimum permissions:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"aoss:ListCollections",
"aoss:BatchGetCollection",
"aoss:CreateCollection",
"aoss:CreateSecurityPolicy",
"aoss:GetSecurityPolicy",
"aoss:ListSecurityPolicies",
"aoss:CreateAccessPolicy",
"aoss:GetAccessPolicy",
"aoss:ListAccessPolicies"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
For a full list of OpenSearch Serverless permissions, see [Identity and Access Management for Amazon OpenSearch Serverless](security-iam-serverless.md).
## Step 2: Create an encryption policy
[Encryption policies](serverless-encryption.md) specify the AWS KMS key that OpenSearch Serverless will use to encrypt the collection. You can encrypt collections with an AWS managed key or a different key. For simplicity in this tutorial, we'll encrypt our collection with an AWS managed key.
**To create an encryption policy**
1. Open the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home ).
1. Expand **Serverless** in the left navigation pane and choose **Encryption policies**.
1. Choose **Create encryption policy**.
1. Name the policy **books-policy**. For the description, enter **Encryption policy for books collection**.
1. Under **Resources**, enter **books**, which is what you'll name your collection. If you wanted to be more broad, you could include an asterisk (`books*`) to make the policy apply to all collections beginning with the word "books".
1. For **Encryption**, keep **Use AWS owned key** selected.
1. Choose **Create**.
## Step 3: Create a network policy
[Network policies](serverless-network.md) determine whether your collection is accessible over the internet from public networks, or whether it must be accessed through OpenSearch Serverless–managed VPC endpoints. In this tutorial, we'll configure public access.
**To create a network policy**
1. Choose **Network policies** in the left navigation pane and choose **Create network policy**.
1. Name the policy **books-policy**. For the description, enter **Network policy for books collection**.
1. Under **Rule 1**, name the rule **Public access for books collection**.
1. For simplicity in this tutorial, we'll configure public access for the *books* collection. For the access type, select **Public**.
1. We're going to access the collection from OpenSearch Dashboards. In order to do this, you need to configure network access for Dashboards *and* the OpenSearch endpoint, otherwise Dashboards won't function.
For the resource type, enable both **Access to OpenSearch endpoints** and **Access to OpenSearch Dashboards**.
1. In both input boxes, enter **Collection Name = books**. This setting scopes the policy down so that it only applies to a single collection (`books`). Your rule should look like this:
![\[Search interface showing two input fields for collection or prefix term selection, both set to "books".\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/serverless-tutorial-network.png)
1. Choose **Create**.
## Step 4: Create a data access policy
Your collection data won't be accessible until you configure data access. [Data access policies](serverless-data-access.md) are separate from the IAM identity-based policy that you configured in step 1. They allow users to access the actual data within a collection.
In this tutorial, we'll provide a single user the permissions required to index data into the *books* collection.
**To create a data access policy**
1. Choose **Data access policies** in the left navigation pane and choose **Create access policy**.
1. Name the policy **books-policy**. For the description, enter **Data access policy for books collection**.
1. Select **JSON** for the policy definition method and paste the following policy in the JSON editor.
Replace the principal ARN with the ARN of the account that you'll use to log in to OpenSearch Dashboards and index data.
```
[
{
"Rules":[
{
"ResourceType":"index",
"Resource":[
"index/books/*"
],
"Permission":[
"aoss:CreateIndex",
"aoss:DescribeIndex",
"aoss:ReadDocument",
"aoss:WriteDocument",
"aoss:UpdateIndex",
"aoss:DeleteIndex"
]
}
],
"Principal":[
"arn:aws:iam::123456789012:user/my-user"
]
}
]
```
This policy provides a single user the minimum permissions required to create an index in the *books* collection, index some data, and search for it.
1. Choose **Create**.
## Step 5: Create a collection
Now that you configured encryption and network policies, you can create a matching collection and the security settings will be automatically applied to it.
**To create an OpenSearch Serverless collection**
1. Choose **Collections** in the left navigation pane and choose **Create collection**.
1. Name the collection **books**.
1. For collection type, choose **Search**.
1. Under **Encryption**, OpenSearch Serverless informs you that the collection name matches the `books-policy` encryption policy.
1. Under **Network access settings**, OpenSearch Serverless informs you that the collection name matches the `books-policy` network policy.
1. Choose **Next**.
1. Under **Data access policy options**, OpenSearch Serverless informs you that the collection name matches the `books-policy` data access policy.
1. Choose **Next**.
1. Review the collection configuration and choose **Submit**. Collections typically take less than a minute to initialize.
## Step 6: Upload and search data
You can upload data to an OpenSearch Serverless collection using Postman or curl. For brevity, these examples use **Dev Tools** within the OpenSearch Dashboards console.
**To index and search data in a collection**
1. Choose **Collections** in the left navigation pane and choose the **books** collection to open its details page.
1. Choose the OpenSearch Dashboards URL for the collection. The URL takes the format `https://collection-id.us-east-1.aoss.amazonaws.com/_dashboards`.
1. Sign in to OpenSearch Dashboards using the [AWS access and secret keys](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for the principal that you specified in your data access policy.
1. Within OpenSearch Dashboards, open the left navigation menu and choose **Dev Tools**.
1. To create a single index called *books-index*, run the following command:
```
PUT books-index
```
![\[OpenSearch Dashboards console showing PUT request for books-index with JSON response.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/serverless-createindex.png)
1. To index a single document into *books-index*, run the following command:
```
PUT books-index/_doc/1
{
"title": "The Shining",
"author": "Stephen King",
"year": 1977
}
```
1. To search data in OpenSearch Dashboards, you need to configure at least one index pattern. OpenSearch uses these patterns to identify which indexes you want to analyze. Open the Dashboards main menu, choose **Stack Management**, choose **Index Patterns**, and then choose **Create index pattern**. For this tutorial, enter *books-index*.
1. Choose **Next step** and then choose **Create index pattern**. After the pattern is created, you can view the various document fields such as `author` and `title`.
1. To begin searching your data, open the main menu again and choose **Discover**, or use the [search API](https://opensearch.org/docs/latest/opensearch/rest-api/search/).
# Tutorial: Getting started with security in Amazon OpenSearch Serverless (CLI)
This tutorial walks you through the steps described in the [console getting started tutorial](gsg-serverless.md) for security, but uses the AWS CLI rather than the OpenSearch Service console.
You'll complete the following steps in this tutorial:
1. Create an IAM permissions policy
1. Attatch the IAM policy to an IAM role
1. Create an encryption policy
1. Create a network policy
1. Create a collection
1. Configure a data access policy
1. Retrieve the collection endpoint
1. Upload data to your connection
1. Search data in your collection
The goal of this tutorial is to set up a single OpenSearch Serverless collection with fairly simple encryption, network, and data access settings. For example, we'll configure public network access, an AWS managed key for encryption, and a simplified data access policy that grants minimal permissions to a single user.
In a production scenario, consider implementing a more robust configuration, including SAML authentication, a custom encryption key, and VPC access.
**To get started with security policies in OpenSearch Serverless**
1.
**Note**
You can skip this step if you're already using a more broad identity-based policy, such as `Action":"aoss:*"` or `Action":"*"`. In production environments, however, we recommend that you follow the principal of least privilege and only assign the minimum permissions necessary to complete a task.
To start, create an AWS Identity and Access Management policy with the minimum required permissions to perform the steps in this tutorial. We'll name the policy `TutorialPolicy`:
```
aws iam create-policy \
--policy-name TutorialPolicy \
--policy-document "{\"Version\": \"2012-10-17\",\"Statement\": [{\"Action\": [\"aoss:ListCollections\",\"aoss:BatchGetCollection\",\"aoss:CreateCollection\",\"aoss:CreateSecurityPolicy\",\"aoss:GetSecurityPolicy\",\"aoss:ListSecurityPolicies\",\"aoss:CreateAccessPolicy\",\"aoss:GetAccessPolicy\",\"aoss:ListAccessPolicies\"],\"Effect\": \"Allow\",\"Resource\": \"*\"}]}"
```
**Sample response**
```
{
"Policy": {
"PolicyName": "TutorialPolicy",
"PolicyId": "ANPAW6WRAECKG6QJWUV7U",
"Arn": "arn:aws:iam::123456789012:policy/TutorialPolicy",
"Path": "/",
"DefaultVersionId": "v1",
"AttachmentCount": 0,
"PermissionsBoundaryUsageCount": 0,
"IsAttachable": true,
"CreateDate": "2022-10-16T20:57:18+00:00",
"UpdateDate": "2022-10-16T20:57:18+00:00"
}
}
```
1. Attach `TutorialPolicy` to the IAM role who will index and search data in the collection. We'll name the user `TutorialRole`:
```
aws iam attach-role-policy \
--role-name TutorialRole \
--policy-arn arn:aws:iam::123456789012:policy/TutorialPolicy
```
1. Before you create a collection, you need to create an [encryption policy](serverless-encryption.md) that assigns an AWS owned key to the *books* collection that you'll create in a later step.
Send the following request to create an encryption policy for the *books* collection:
```
aws opensearchserverless create-security-policy \
--name books-policy \
--type encryption --policy "{\"Rules\":[{\"ResourceType\":\"collection\",\"Resource\":[\"collection\/books\"]}],\"AWSOwnedKey\":true}"
```
**Sample response**
```
{
"securityPolicyDetail": {
"type": "encryption",
"name": "books-policy",
"policyVersion": "MTY2OTI0MDAwNTk5MF8x",
"policy": {
"Rules": [
{
"Resource": [
"collection/books"
],
"ResourceType": "collection"
}
],
"AWSOwnedKey": true
},
"createdDate": 1669240005990,
"lastModifiedDate": 1669240005990
}
}
```
1. Create a [network policy](serverless-network.md) that provides public access to the *books* collection:
```
aws opensearchserverless create-security-policy --name books-policy --type network \
--policy "[{\"Description\":\"Public access for books collection\",\"Rules\":[{\"ResourceType\":\"dashboard\",\"Resource\":[\"collection\/books\"]},{\"ResourceType\":\"collection\",\"Resource\":[\"collection\/books\"]}],\"AllowFromPublic\":true}]"
```
**Sample response**
```
{
"securityPolicyDetail": {
"type": "network",
"name": "books-policy",
"policyVersion": "MTY2OTI0MDI1Njk1NV8x",
"policy": [
{
"Rules": [
{
"Resource": [
"collection/books"
],
"ResourceType": "dashboard"
},
{
"Resource": [
"collection/books"
],
"ResourceType": "collection"
}
],
"AllowFromPublic": true,
"Description": "Public access for books collection"
}
],
"createdDate": 1669240256955,
"lastModifiedDate": 1669240256955
}
}
```
1. Create the *books* collection:
```
aws opensearchserverless create-collection --name books --type SEARCH
```
**Sample response**
```
{
"createCollectionDetail": {
"id": "8kw362bpwg4gx9b2f6e0",
"name": "books",
"status": "CREATING",
"type": "SEARCH",
"arn": "arn:aws:aoss:us-east-1:123456789012:collection/8kw362bpwg4gx9b2f6e0",
"kmsKeyArn": "auto",
"createdDate": 1669240325037,
"lastModifiedDate": 1669240325037
}
}
```
1. Create a [data access policy](serverless-data-access.md) that provides the minimum permissions to index and search data in the *books* collection. Replace the principal ARN with the ARN of `TutorialRole` from step 1:
```
aws opensearchserverless create-access-policy \
--name books-policy \
--type data \
--policy "[{\"Rules\":[{\"ResourceType\":\"index\",\"Resource\":[\"index\/books\/books-index\"],\"Permission\":[\"aoss:CreateIndex\",\"aoss:DescribeIndex\",\"aoss:ReadDocument\",\"aoss:WriteDocument\",\"aoss:UpdateIndex\",\"aoss:DeleteIndex\"]}],\"Principal\":[\"arn:aws:iam::123456789012:role\/TutorialRole\"]}]"
```
**Sample response**
```
{
"accessPolicyDetail": {
"type": "data",
"name": "books-policy",
"policyVersion": "MTY2OTI0MDM5NDY1M18x",
"policy": [
{
"Rules": [
{
"Resource": [
"index/books/books-index"
],
"Permission": [
"aoss:CreateIndex",
"aoss:DescribeIndex",
"aoss:ReadDocument",
"aoss:WriteDocument",
"aoss:UpdateDocument",
"aoss:DeleteDocument"
],
"ResourceType": "index"
}
],
"Principal": [
"arn:aws:iam::123456789012:role/TutorialRole"
]
}
],
"createdDate": 1669240394653,
"lastModifiedDate": 1669240394653
}
}
```
`TutorialRole` should now be able to index and search documents in the *books* collection.
1. To make calls to the OpenSearch API, you need the collection endpoint. Send the following request to retrieve the `collectionEndpoint` parameter:
```
aws opensearchserverless batch-get-collection --names books
```
**Sample response**
```
{
"collectionDetails": [
{
"id": "8kw362bpwg4gx9b2f6e0",
"name": "books",
"status": "ACTIVE",
"type": "SEARCH",
"description": "",
"arn": "arn:aws:aoss:us-east-1:123456789012:collection/8kw362bpwg4gx9b2f6e0",
"createdDate": 1665765327107,
"collectionEndpoint": "https://8kw362bpwg4gx9b2f6e0.us-east-1.aoss.amazonaws.com",
"dashboardEndpoint": "https://8kw362bpwg4gx9b2f6e0.us-east-1.aoss.amazonaws.com/_dashboards"
}
],
"collectionErrorDetails": []
}
```
**Note**
You won't be able to see the collection endpoint until the collection status changes to `ACTIVE`. You might have to make multiple calls to check the status until the collection is successfully created.
1. Use an HTTP tool such as [Postman](https://www.getpostman.com/) or curl to index data into the *books* collection. We'll create an index called *books-index* and add a single document.
Send the following request to the collection endpoint that you retrieved in the previous step, using the credentials for `TutorialRole`.
```
PUT https://8kw362bpwg4gx9b2f6e0.us-east-1.aoss.amazonaws.com/books-index/_doc/1
{
"title": "The Shining",
"author": "Stephen King",
"year": 1977
}
```
**Sample response**
```
{
"_index" : "books-index",
"_id" : "1",
"_version" : 1,
"result" : "created",
"_shards" : {
"total" : 0,
"successful" : 0,
"failed" : 0
},
"_seq_no" : 0,
"_primary_term" : 0
}
```
1. To begin searching data in your collection, use the [search API](https://opensearch.org/docs/latest/opensearch/rest-api/search/). The following query performs a basic search:
```
GET https://8kw362bpwg4gx9b2f6e0.us-east-1.aoss.amazonaws.com/books-index/_search
```
**Sample response**
```
{
"took": 405,
"timed_out": false,
"_shards": {
"total": 6,
"successful": 6,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 2,
"relation": "eq"
},
"max_score": 1.0,
"hits": [
{
"_index": "books-index:0::3xJq14MBUaOS0wL26UU9:0",
"_id": "F_bt4oMBLle5pYmm5q4T",
"_score": 1.0,
"_source": {
"title": "The Shining",
"author": "Stephen King",
"year": 1977
}
}
]
}
}
```
# Identity and Access Management for Amazon OpenSearch Serverless
AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be *authenticated* (signed in) and *authorized* (have permissions) to use OpenSearch Serverless resources. IAM is an AWS service that you can use with no additional charge.
**Topics**
+ [Identity-based policies for OpenSearch Serverless](#security-iam-serverless-id-based-policies)
+ [Policy actions for OpenSearch Serverless](#security-iam-serverless-id-based-policies-actions)
+ [Policy resources for OpenSearch Serverless](#security-iam-serverless-id-based-policies-resources)
+ [Policy condition keys for Amazon OpenSearch Serverless](#security_iam_serverless-conditionkeys)
+ [ABAC with OpenSearch Serverless](#security_iam_serverless-with-iam-tags)
+ [Using temporary credentials with OpenSearch Serverless](#security_iam_serverless-tempcreds)
+ [Service-linked roles for OpenSearch Serverless](#security_iam_serverless-slr)
+ [Other policy types](#security_iam_access-manage-other-policies)
+ [Identity-based policy examples for OpenSearch Serverless](#security_iam_serverless_id-based-policy-examples)
+ [IAM Identity Center support for Amazon OpenSearch Serverless](serverless-iam-identity-center.md)
## Identity-based policies for OpenSearch Serverless
**Supports identity-based policies:** Yes
Identity-based policies are JSON permissions policy documents that you can attach to an identity, such as an IAM user, group of users, or role. These policies control what actions users and roles can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.
With IAM identity-based policies, you can specify allowed or denied actions and resources as well as the conditions under which actions are allowed or denied. To learn about all of the elements that you can use in a JSON policy, see [IAM JSON policy elements reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the *IAM User Guide*.
### Identity-based policy examples for OpenSearch Serverless
To view examples of OpenSearch Serverless identity-based policies, see [Identity-based policy examples for OpenSearch Serverless](#security_iam_serverless_id-based-policy-examples).
## Policy actions for OpenSearch Serverless
**Supports policy actions:** Yes
The `Action` element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Policy actions usually have the same name as the associated AWS API operation. There are some exceptions, such as *permission-only actions* that don't have a matching API operation. There are also some operations that require multiple actions in a policy. These additional actions are called *dependent actions*.
Include actions in a policy to grant permissions to perform the associated operation.
Policy actions in OpenSearch Serverless use the following prefix before the action:
```
aoss
```
To specify multiple actions in a single statement, separate them with commas.
```
"Action": [
"aoss:action1",
"aoss:action2"
]
```
You can specify multiple actions using wildcard characters (\$1). For example, to specify all actions that begin with the word `Describe`, include the following action:
```
"Action": "aoss:List*"
```
To view examples of OpenSearch Serverless identity-based policies, see [Identity-based policy examples for OpenSearch Serverless](#security_iam_id-based-policy-examples).
## Policy resources for OpenSearch Serverless
**Supports policy resources:** Yes
Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.
The `Resource` JSON policy element specifies the object or objects to which the action applies. As a best practice, specify a resource using its [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html). For actions that don't support resource-level permissions, use a wildcard (\$1) to indicate that the statement applies to all resources.
```
"Resource": "*"
```
## Policy condition keys for Amazon OpenSearch Serverless
**Supports service-specific policy condition keys:** Yes
Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.
The `Condition` element specifies when statements execute based on defined criteria. You can create conditional expressions that use [condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html), such as equals or less than, to match the condition in the policy with values in the request. To see all AWS global condition keys, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*.
In addition to attribute-based access control (ABAC), OpenSearch Serverless supports the following condition keys:
+ `aoss:collection`
+ `aoss:CollectionId`
+ `aoss:index`
You can use these condition keys even when providing permissions for access policies and security policies. For example:
```
[
{
"Effect":"Allow",
"Action":[
"aoss:CreateAccessPolicy",
"aoss:CreateSecurityPolicy"
],
"Resource":"*",
"Condition":{
"StringLike":{
"aoss:collection":"log"
}
}
}
]
```
In this example, the condition applies to policies that contain *rules* that match a collection name or pattern. The conditions have the following behavior:
+ `StringEquals` - Applies to policies with rules that contain the *exact* resource string "log" (i.e. `collection/log`).
+ `StringLike` - Applies to policies with rules that contain a resource string that *includes* the string "log" (i.e. `collection/log` but also `collection/logs-application` or `collection/applogs123`).
**Note**
*Collection* condition keys don't apply at the index level. For example, in the policy above, the condition wouldn't apply to an access or security policy containing the resource string `index/logs-application/*`.
To see a list of OpenSearch Serverless condition keys, see [Condition keys for Amazon OpenSearch Serverless](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonopensearchserverless.html#amazonopensearchserverless-policy-keys) in the *Service Authorization Reference*. To learn with which actions and resources you can use a condition key, see [Actions defined by Amazon OpenSearch Serverless](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonopensearchserverless.html#amazonopensearchserverless-actions-as-permissions).
## ABAC with OpenSearch Serverless
**Supports ABAC (tags in policies):** Yes
Attribute-based access control (ABAC) is an authorization strategy that defines permissions based on attributes called tags. You can attach tags to IAM entities and AWS resources, then design ABAC policies to allow operations when the principal's tag matches the tag on the resource.
To control access based on tags, you provide tag information in the [condition element](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) of a policy using the `aws:ResourceTag/key-name`, `aws:RequestTag/key-name`, or `aws:TagKeys` condition keys.
If a service supports all three condition keys for every resource type, then the value is **Yes** for the service. If a service supports all three condition keys for only some resource types, then the value is **Partial**.
For more information about ABAC, see [Define permissions with ABAC authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html) in the *IAM User Guide*. To view a tutorial with steps for setting up ABAC, see [Use attribute-based access control (ABAC)](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html) in the *IAM User Guide*.
For more information about tagging OpenSearch Serverless resources, see [Tagging Amazon OpenSearch Serverless collections](tag-collection.md).
## Using temporary credentials with OpenSearch Serverless
**Supports temporary credentials:** Yes
Temporary credentials provide short-term access to AWS resources and are automatically created when you use federation or switch roles. AWS recommends that you dynamically generate temporary credentials instead of using long-term access keys. For more information, see [Temporary security credentials in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) and [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the *IAM User Guide*.
## Service-linked roles for OpenSearch Serverless
**Supports service-linked roles:** Yes
A service-linked role is a type of service role that is linked to an AWS service. The service can assume the role to perform an action on your behalf. Service-linked roles appear in your AWS account and are owned by the service. An IAM administrator can view, but not edit the permissions for service-linked roles.
For details about creating and managing OpenSearch Serverless service-linked roles, see [Using service-linked roles to create OpenSearch Serverless collections](serverless-service-linked-roles.md).
## Other policy types
AWS supports additional, less-common policy types. These policy types can set the maximum permissions granted to you by the more common policy types.
+ **Service control policies (SCPs)** – SCPs are JSON policies that specify the maximum permissions for an organization or organizational unit (OU) in AWS Organizations. AWS Organizations is a service for grouping and centrally managing multiple AWS accounts that your business owns. If you enable all features in an organization, then you can apply service control policies (SCPs) to any or all of your accounts. The SCP limits permissions for entities in member accounts, including each AWS account root user. For more information about Organizations and SCPs, see [Service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*.
+ **Resource control policies (RCPs)** – RCPs are JSON policies that you can use to set the maximum available permissions for resources in your accounts without updating the IAM policies attached to each resource that you own. The RCP limits permissions for resources in member accounts and can impact the effective permissions for identities, including the AWS account root user, regardless of whether they belong to your organization. For more information about Organizations and RCPs, including a list of AWS services that support RCPs, see [Resource control policies (RCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html) in the *AWS Organizations User Guide*.
## Identity-based policy examples for OpenSearch Serverless
By default, users and roles don't have permission to create or modify OpenSearch Serverless resources. To grant users permission to perform actions on the resources that they need, an IAM administrator can create IAM policies.
To learn how to create an IAM identity-based policy by using these example JSON policy documents, see [Create IAM policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) in the *IAM User Guide*.
For details about actions and resource types defined by Amazon OpenSearch Serverless, including the format of the ARNs for each of the resource types, see [Actions, resources, and condition keys for Amazon OpenSearch Serverless](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonopensearchserverless.html) in the *Service Authorization Reference*.
**Topics**
+ [Policy best practices](#security_iam_serverless-policy-best-practices)
+ [Using OpenSearch Serverless in the console](#security_iam_serverless_id-based-policy-examples-console)
+ [Administering OpenSearch Serverless collections](#security_iam_id-based-policy-examples-collection-admin)
+ [Viewing OpenSearch Serverless collections](#security_iam_id-based-policy-examples-view-collections)
+ [Using OpenSearch API operations](#security_iam_id-based-policy-examples-data-plane)
+ [ABAC for OpenSearch API operations](#security_iam_id-based-policy-examples-data-plane-abac)
### Policy best practices
Identity-based policies are very powerful. They determine whether someone can create, access, or delete OpenSearch Serverless resources in your account. These actions can incur costs for your AWS account. When you create or edit identity-based policies, follow these guidelines and recommendations:
Identity-based policies determine whether someone can create, access, or delete OpenSearch Serverless resources in your account. These actions can incur costs for your AWS account. When you create or edit identity-based policies, follow these guidelines and recommendations:
+ **Get started with AWS managed policies and move toward least-privilege permissions** – To get started granting permissions to your users and workloads, use the *AWS managed policies* that grant permissions for many common use cases. They are available in your AWS account. We recommend that you reduce permissions further by defining AWS customer managed policies that are specific to your use cases. For more information, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) or [AWS managed policies for job functions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html) in the *IAM User Guide*.
+ **Apply least-privilege permissions** – When you set permissions with IAM policies, grant only the permissions required to perform a task. You do this by defining the actions that can be taken on specific resources under specific conditions, also known as *least-privilege permissions*. For more information about using IAM to apply permissions, see [ Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*.
+ **Use conditions in IAM policies to further restrict access** – You can add a condition to your policies to limit access to actions and resources. For example, you can write a policy condition to specify that all requests must be sent using SSL. You can also use conditions to grant access to service actions if they are used through a specific AWS service, such as CloudFormation. For more information, see [ IAM JSON policy elements: Condition](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) in the *IAM User Guide*.
+ **Use IAM Access Analyzer to validate your IAM policies to ensure secure and functional permissions** – IAM Access Analyzer validates new and existing policies so that the policies adhere to the IAM policy language (JSON) and IAM best practices. IAM Access Analyzer provides more than 100 policy checks and actionable recommendations to help you author secure and functional policies. For more information, see [Validate policies with IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-policy-validation.html) in the *IAM User Guide*.
+ **Require multi-factor authentication (MFA)** – If you have a scenario that requires IAM users or a root user in your AWS account, turn on MFA for additional security. To require MFA when API operations are called, add MFA conditions to your policies. For more information, see [ Secure API access with MFA](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_configure-api-require.html) in the *IAM User Guide*.
For more information about best practices in IAM, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
### Using OpenSearch Serverless in the console
To access OpenSearch Serverless within the OpenSearch Service console, you must have a minimum set of permissions. These permissions must allow you to list and view details about the OpenSearch Serverless resources in your AWS account. If you create an identity-based policy that is more restrictive than the minimum required permissions, the console won't function as intended for entities (such as IAM roles) with that policy.
You don't need to allow minimum console permissions for users that are making calls only to the AWS CLI or the AWS API. Instead, allow access to only the actions that match the API operation that you're trying to perform.
The following policy allows a user to access OpenSearch Serverless within the OpenSearch Service console:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Resource": "*",
"Effect": "Allow",
"Action": [
"aoss:ListCollections",
"aoss:BatchGetCollection",
"aoss:ListAccessPolicies",
"aoss:ListSecurityConfigs",
"aoss:ListSecurityPolicies",
"aoss:ListTagsForResource",
"aoss:ListVpcEndpoints",
"aoss:GetAccessPolicy",
"aoss:GetAccountSettings",
"aoss:GetSecurityConfig",
"aoss:GetSecurityPolicy"
]
}
]
}
```
------
### Administering OpenSearch Serverless collections
This policy is an example of a "collection admin" policy that allows a user to manage and administer Amazon OpenSearch Serverless collections. The user can create, view, and delete collections.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Resource": "arn:aws:aoss:us-east-1:111122223333:collection/*",
"Action": [
"aoss:CreateCollection",
"aoss:DeleteCollection",
"aoss:UpdateCollection"
],
"Effect": "Allow"
},
{
"Resource": "*",
"Action": [
"aoss:BatchGetCollection",
"aoss:ListCollections",
"aoss:CreateAccessPolicy",
"aoss:CreateSecurityPolicy"
],
"Effect": "Allow"
}
]
}
```
------
### Viewing OpenSearch Serverless collections
This example policy allows a user to view details for all Amazon OpenSearch Serverless collections in their account. The user can't modify the collections or any associated security policies.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Resource": "*",
"Action": [
"aoss:ListAccessPolicies",
"aoss:ListCollections",
"aoss:ListSecurityPolicies",
"aoss:ListTagsForResource",
"aoss:BatchGetCollection"
],
"Effect": "Allow"
}
]
}
```
------
### Using OpenSearch API operations
Data plane API operations consist of the functions you use in OpenSearch Serverless to derive realtime value from the service. Control plane API operations consist of the functions you use to set up the environment.
To access Amazon OpenSearch Serverless data plane APIs and OpenSearch Dashboards from the browser, you need to add two IAM permissions for collection resources. These permissions are `aoss:APIAccessAll` and `aoss:DashboardsAccessAll`.
**Note**
Starting May 10, 2023, OpenSearch Serverless requires these two new IAM permissions for collection resources. The `aoss:APIAccessAll` permission allows data plane access, and the `aoss:DashboardsAccessAll` permission allows OpenSearch Dashboards from the browser. Failure to add the two new IAM permissions results in a 403 error.
This example policy allows a user to access data plane APIs for a specified collection in their account, and to access OpenSearch Dashboards for all collections in their account.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "aoss:APIAccessAll",
"Resource": "arn:aws:aoss:us-east-1:111122223333:collection/collection-id"
},
{
"Effect": "Allow",
"Action": "aoss:DashboardsAccessAll",
"Resource": "arn:aws:aoss:us-east-1:111122223333:dashboards/default"
}
]
}
```
------
Both `aoss:APIAccessAll` and `aoss:DashboardsAccessAll` give full IAM permission to the collection resources, while the Dashboards permission also provides OpenSearch Dashboards access. Each permission works independently, so an explicit deny on `aoss:APIAccessAll` doesn't block `aoss:DashboardsAccessAll` access to the resources, including Dev Tools. The same is true for a deny on `aoss:DashboardsAccessAll`. OpenSearch Serverless supports the following global condition keys:
+ `aws:CalledVia`
+ `aws:CalledViaAWSService`
+ `aws:CalledViaFirst`
+ `aws:CalledViaLast`
+ `aws:CurrentTime`
+ `aws:EpochTime`
+ `aws:PrincipalAccount`
+ `aws:PrincipalArn`
+ `aws:PrincipallsAWSService`
+ `aws:PrincipalOrgID`
+ `aws:PrincipalOrgPaths`
+ `aws:PrincipalType`
+ `aws:PrincipalServiceName`
+ `aws:PrincipalServiceNamesList`
+ `aws:ResourceAccount`
+ `aws:ResourceOrgID`
+ `aws:ResourceOrgPaths`
+ `aws:RequestedRegion`
+ `aws:ResourceTag`
+ `aws:SourceIp`
+ `aws:SourceVpce`
+ `aws:SourceVpc`
+ `aws:userid`
+ `aws:username`
+ `aws:VpcSourceIp`
The following is an example of using `aws:SourceIp` in the condition block in your principal's IAM policy for data plane calls:
```
"Condition": {
"IpAddress": {
"aws:SourceIp": "203.0.113.0"
}
}
```
The following is an example of using `aws:SourceVpc` in the condition block in your principal's IAM policy for data plane calls:
```
"Condition": {
"StringEquals": {
"aws:SourceVpc": "vpc-0fdd2445d8EXAMPLE"
}
}
```
Additonally, support is offered for the following OpenSearch Serverless specific keys:
+ `aoss:CollectionId`
+ `aoss:collection`
The following is an example of using `aoss:collection` in the condition block in your principal's IAM policy for data plane calls:
```
"Condition": {
"StringLike": {
"aoss:collection": "log-*"
}
}
```
### ABAC for OpenSearch API operations
Identity-based policies let you use tags to control access to Amazon OpenSearch Serverless data plane APIs. The following policy is an example to allow attached principals to access data plane APIs if the collection has the `team:devops` tag:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "aoss:APIAccessAll",
"Resource": "arn:aws:aoss:us-east-1:111122223333:collection/collection-id",
"Condition": {
"StringEquals": {
"aws:ResourceTag/team": "devops"
}
}
}
]
}
```
------
The following policy is an example to deny attached principals to access data plane APIs and Dashboards access if the collection has the `environment:production` tag:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"aoss:APIAccessAll",
"aoss:DashboardsAccessAll"
],
"Resource": "arn:aws:aoss:us-east-1:111122223333:collection/collection-id"
}
]
}
```
------
Amazon OpenSearch Serverless do not support `RequestTag` and `TagKeys` global condition keys for data plane APIs.
# IAM Identity Center support for Amazon OpenSearch Serverless
## IAM Identity Center support for Amazon OpenSearch Serverless
You can use IAM Identity Center principals (users and groups) to access Amazon OpenSearch Serverless data through Amazon OpenSearch Applications. In order to enable IAM Identity Center support for Amazon OpenSearch Serverless, you will need to enable use of IAM Identity Center. To learn more on how to do this, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)
**Note**
To access Amazon OpenSearch Serverless collections using IAM Identity Center users or groups, you must use the OpenSearch UI (Applications) feature. Direct access to OpenSearch Serverless Dashboards using IAM Identity Center credentials is not supported. For more information, see [Getting started with the OpenSearch user interface](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/application.html).
After the IAM Identity Center instance is created, the customer account administrator needs to create an IAM Identity Center application for the Amazon OpenSearch Serverless service. This can be done by calling the [CreateSecurityConfig:](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_CreateSecurityConfig.html). The customer account administrator can specify what attributes will be used for authorizing the request. The default attributes used are `UserId` and `GroupId.`
The IAM Identity Center integration for Amazon OpenSearch Serverless uses the following AWS IAM Identity Center (IAM) permissions:
+ `aoss:CreateSecurityConfig` – Create an IAM Identity Center provider
+ `aoss:ListSecurityConfig` – List all IAM Identity Center providers in the current account.
+ `aoss:GetSecurityConfig` – View IAM Identity Center provider information.
+ `aoss:UpdateSecurityConfig` – Modify a given IAM Identity Center configuration
+ `aoss:DeleteSecurityConfig` – Delete an IAM Identity Centerprovider.
The following identity-based access policy can be used to manage all IAM Identity Center configurations:
------
#### [ JSON ]
****
```
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"aoss:CreateSecurityConfig",
"aoss:DeleteSecurityConfig",
"aoss:GetSecurityConfig",
"aoss:UpdateSecurityConfig",
"aoss:ListSecurityConfigs"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
**Note**
The `Resource` element must be a wildcard.
## Creating an IAM Identity Center provider (console)
You can create an IAM Identity Center provider to enable authentication with OpenSearch Application. To enable IAM Identity Center authentication for OpenSearch Dashboards, perform the following steps:
1. Sign in to the [Amazon OpenSearch Service console](https://console.aws.amazon.com/aos/home.).
1. On the left navigation panel, expand ** Serverless** and choose **Authentication**.
1. Choose** IAM Identity Center authentication**.
1. Select **Edit**
1. Check the box next to Authenticate with IAM Identity Center.
1. Select the **user and group** attribute key from the dropdown menu. User attributes will be used to authorize users based on `UserName`, `UserId`, and `Email`. Group attributes will be used to authenticate users based on `GroupName` and `GroupId`.
1. Select the **IAM Identity Center** instance.
1. Select **Save**
## Creating IAM Identity Center provider (AWS CLI)
To create an IAM Identity Center provider using the AWS Command Line Interface (AWS CLI) use the following command:
```
aws opensearchserverless create-security-config \
--region us-east-2 \
--name "iamidentitycenter-config" \
--description "description" \
--type "iamidentitycenter" \
--iam-identity-center-options '{
"instanceArn": "arn:aws:sso:::instance/ssoins-99199c99e99ee999",
"userAttribute": "UserName",
"groupAttribute": "GroupId"
}'
```
After an IAM Identity Center is enabled, customers can only modify **user and group** attributes.
```
aws opensearchserverless update-security-config \
--region us-east-1 \
--id \
--config-version \
--iam-identity-center-options-updates '{
"userAttribute": "UserId",
"groupAttribute": "GroupId"
}'
```
In order to view the IAM Identity Center provider using the AWS Command Line Interface, use the following command:
```
aws opensearchserverless list-security-configs --type iamidentitycenter
```
## Deleting an IAM Identity Center provider
IAM Identity Center offers two instances of providers, one for your organization account and one for your member account. If you need to change your IAM Identity Center instance, you need to delete your security configuration through the `DeleteSecurityConfig` API and create a new security configuration using the new IAM Identity Center instance. The following command can be used to delete an IAM Identity Center provider:
```
aws opensearchserverless delete-security-config \
--region us-east-1 \
--id
```
## Granting IAM Identity Center access to collection data
After your IAM Identity Center provider is enabled, you can update the collection data access policy to include IAM Identity Center principals. IAM Identity Center principals need to be updated in the following format:
```
[
{
"Rules":[
...
],
"Principal":[
"iamidentitycenter//user/",
"iamidentitycenter//group/"
]
}
]
```
**Note**
Amazon OpenSearch Serverless supports only one IAM Identity Center instance for all customer collections and can support up to 100 groups for a single user. If you try to use more than the number of allowed instances, you will experience inconsistency with your data access policy authorization processing and receive a `403`error message.
You can grant access to collections, indexes, or both. If you want different users to have different permssions, you will need to create multiple rules. For a list of available permissions, see [Identity and Access Management in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html). For information about how to format an access policy, see [Granting SAML identities access to collection data ](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-saml.html#serverless-saml-policies).
# Encryption in Amazon OpenSearch Serverless
## Encryption at rest
Each Amazon OpenSearch Serverless collection that you create is protected with encryption of data at rest, a security feature that helps prevent unauthorized access to your data. Encryption at rest uses AWS Key Management Service (AWS KMS) to store and manage your encryption keys. It uses the Advanced Encryption Standard algorithm with 256-bit keys (AES-256) to perform the encryption.
**Topics**
+ [Encryption policies](#serverless-encryption-policies)
+ [Considerations](#serverless-encryption-considerations)
+ [Permissions required](#serverless-encryption-permissions)
+ [Key policy for a customer managed key](#serverless-customer-cmk-policy)
+ [How OpenSearch Serverless uses grants in AWS KMS](#serverless-encryption-grants)
+ [Creating encryption policies (console)](#serverless-encryption-console)
+ [Creating encryption policies (AWS CLI)](#serverless-encryption-cli)
+ [Viewing encryption policies](#serverless-encryption-list)
+ [Updating encryption policies](#serverless-encryption-update)
+ [Deleting encryption policies](#serverless-encryption-delete)
### Encryption policies
With encryption policies, you can manage many collections at scale by automatically assigning an encryption key to newly created collections that match a specific name or pattern.
When you create an encryption policy, you can either specify a *prefix*, which is a wildcard-based matching rule such as `MyCollection*`, or enter a single collection name. Then, when you create a collection that matches that name or prefix pattern, the policy and corresponding KMS key are automatically assigned to it.
When creating a collection, you can specify an AWS KMS key in two ways: through security policies or directly in the `CreateCollection` request. If you provide a AWS KMS key as part of the `CreateCollection` request, it takes precedence over any matching security policies. With this approach, you have the flexibility to override policy-based encryption settings for specific collections when needed.
![\[Encryption policy creation process with rules and collection matching to KMS key.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/serverless-encryption.png)
Encryption policies contain the following elements:
+ `Rules` – one or more collection matching rules, each with the following sub-elements:
+ `ResourceType` – Currently the only option is "collection". Encryption policies apply to collection resources only.
+ `Resource` – One or more collection names or patterns that the policy will apply to, in the format `collection/`.
+ `AWSOwnedKey` – Whether to use an AWS owned key.
+ `KmsARN` – If you set `AWSOwnedKey` to false, specify the Amazon Resource Name (ARN) of the KMS key to encrypt the associated collections with. If you include this parameter, OpenSearch Serverless ignores the `AWSOwnedKey` parameter.
The following sample policy will assign a customer managed key to any future collection named `autopartsinventory`, as well as collections that begin with the term "sales":
```
{
"Rules":[
{
"ResourceType":"collection",
"Resource":[
"collection/autopartsinventory",
"collection/sales*"
]
}
],
"AWSOwnedKey":false,
"KmsARN":"arn:aws:kms:us-east-1:123456789012:key/93fd6da4-a317-4c17-bfe9-382b5d988b36"
}
```
Even if a policy matches a collection name, you can choose to override this automatic assignment during collection creation if the resource pattern contains a wildcard (\$1). If you choose to override automatic key assignment, OpenSearch Serverless creates an encryption policy for you named **auto-<*collection-name*>** and attaches it to the collection. The policy initially only applies to a single collection, but you can modify it to include additional collections.
If you modify policy rules to no longer match a collection, the associated KMS key won't be unassigned from that collection. The collection always remains encrypted with its initial encryption key. If you want to change the encryption key for a collection, you must recreate the collection.
If rules from multiple policies match a collection, the more specific rule is used. For example, if one policy contains a rule for `collection/log*`, and another for `collection/logSpecial`, the encryption key for the second policy is used because it's more specific.
You can't use a name or a prefix in a policy if it already exists in another policy. OpenSearch Serverless displays an error if you try to configure identical resource patterns in different encryption policies.
### Considerations
Consider the following when you configure encryption for your collections:
+ Encryption at rest is *required* for all serverless collections.
+ You have the option to use a customer managed key or an AWS owned key. If you choose a customer managed key, we recommend that you enable [automatic key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html).
+ You can't change the encryption key for a collection after the collection is created. Carefully choose which AWS KMS to use the first time you set up a collection.
+ A collection can only match a single encryption policy.
+ Collections with unique KMS keys can't share OpenSearch Compute Units (OCUs) with other collections. Each collection with a unique key requires its own 4 OCUs.
+ If you update the KMS key in an encryption policy, the change doesn't affect existing matching collections with KMS keys already assigned.
+ OpenSearch Serverless doesn't explicitly check user permissions on customer managed keys. If a user has permissions to access a collection through a data access policy, they will be able to ingest and query the data that is encrypted with the associated key.
### Permissions required
Encryption at rest for OpenSearch Serverless uses the following AWS Identity and Access Management (IAM) permissions. You can specify IAM conditions to restrict users to specific collections.
+ `aoss:CreateSecurityPolicy` – Create an encryption policy.
+ `aoss:ListSecurityPolicies` – List all encryption policies and collections that they are attached to.
+ `aoss:GetSecurityPolicy` – See details of a specific encryption policy.
+ `aoss:UpdateSecurityPolicy` – Modify an encryption policy.
+ `aoss:DeleteSecurityPolicy` – Delete an encryption policy.
The following sample identity-based access policy provides the minimum permissions necessary for a user to manage encryption policies with the resource pattern `collection/application-logs`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"aoss:CreateSecurityPolicy",
"aoss:UpdateSecurityPolicy",
"aoss:DeleteSecurityPolicy",
"aoss:GetSecurityPolicy"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"aoss:collection":"application-logs"
}
}
},
{
"Effect":"Allow",
"Action":[
"aoss:ListSecurityPolicies"
],
"Resource":"*"
}
]
}
```
------
### Key policy for a customer managed key
If you select a [customer managed key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) to protect a collection, OpenSearch Serverless gets permission to use the KMS key on behalf of the principal who makes the selection. That principal, a user or role, must have the permissions on the KMS key that OpenSearch Serverless requires. You can provide these permissions in a [key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) or an [IAM policy](https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html).
OpenSearch Serverless makes `GenerateDataKey` and `Decrypt` KMS API calls during maintenance operations such as autoscaling and software updates. You might observe these calls outside your typical traffic patterns. These calls are part of normal service operations and don't indicate active user traffic.
OpenSearch Serverless throws a `KMSKeyInaccessibleException` when it cannot access the KMS key that encrypts your data at rest. This occurs when you disable or delete the KMS key, or revoke the grants that allow OpenSearch Serverless to use the key.
At a minimum, OpenSearch Serverless requires the following permissions on a customer managed key:
+ [kms:DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html)
+ [kms:CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)
For example:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "kms:DescribeKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:user/Dale"
},
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": "aoss.us-east-1.amazonaws.com"
}
}
},
{
"Action": "kms:CreateGrant",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:user/Dale"
},
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": "aoss.us-east-1.amazonaws.com"
},
"ForAllValues:StringEquals": {
"kms:GrantOperations": [
"Decrypt",
"GenerateDataKey"
]
},
"Bool": {
"kms:GrantIsForAWSResource": "true"
}
}
}
]
}
```
------
OpenSearch Serverless create a grant with the [kms:GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) and [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) permissions.
For more information, see [Using key policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) in the *AWS Key Management Service Developer Guide*.
### How OpenSearch Serverless uses grants in AWS KMS
OpenSearch Serverless requires a [grant](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in order to use a customer managed key.
When you create an encryption policy in your account with a new key, OpenSearch Serverless creates a grant on your behalf by sending a [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request to AWS KMS. Grants in AWS KMS are used to give OpenSearch Serverless access to a KMS key in a customer account.
OpenSearch Serverless requires the grant to use your customer managed key for the following internal operations:
+ Send [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) requests to AWS KMS to verify that the symmetric customer managed key ID provided is valid.
+ Send [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) requests to KMS key to create data keys with which to encrypt objects.
+ Send [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) requests to AWS KMS to decrypt the encrypted data keys so that they can be used to encrypt your data.
You can revoke access to the grant, or remove the service's access to the customer managed key at any time. If you do, OpenSearch Serverless won't be able to access any of the data encrypted by the customer managed key, which affects all the operations that are dependent on that data, leading to `AccessDeniedException` errors and failures in the asynchronous workflows.
OpenSearch Serverless retires grants in an asynchronous workflow when a given customer managed key isn't associated with any security policies or collections.
### Creating encryption policies (console)
In an encryption policy, you specify an KMS key and a series of collection patterns that the policy will apply to. Any new collections that match one of the patterns defined in the policy will be assigned the corresponding KMS key when you create the collection. We recommend that you create encryption policies *before* you start creating collections.
**To create an OpenSearch Serverless encryption policy**
1. Open the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home).
1. On the left navigation panel, expand **Serverless** and choose **Encryption policies**.
1. Choose **Create encryption policy**.
1. Provide a name and description for the policy.
1. Under **Resources**, enter one or more resource patterns for this encryption policy. Any newly created collections in the current AWS account and Region that match one of the patterns are automatically assigned to this policy. For example, if you enter `ApplicationLogs` (with no wildcard), and later create a collection with that name, the policy and corresponding KMS key are assigned to that collection.
You can also provide a prefix such as `Logs*`, which assigns the policy to any new collections with names beginning with `Logs`. By using wildcards, you can manage encryption settings for multiple collections at scale.
1. Under **Encryption**, choose an KMS key to use.
1. Choose **Create**.
#### Next step: Create collections
After you configure one or more encryption policies, you can start creating collections that match the rules defined in those policies. For instructions, see [Creating collections](serverless-create.md).
In the **Encryptions** step of collection creation, OpenSearch Serverless informs you that the name that you entered matches the pattern defined in an encryption policy, and automatically assigns the corresponding KMS key to the collection. If the resource pattern contains a wildcard (\$1), you can choose to override the match and select your own key.
### Creating encryption policies (AWS CLI)
To create an encryption policy using the OpenSearch Serverless API operations, you specify resource patterns and an encryption key in JSON format. The [CreateSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_CreateSecurityPolicy.html) request accepts both inline policies and .json files.
Encryption policies take the following format. This sample `my-policy.json` file matches any future collection named `autopartsinventory`, as well as any collections with names beginning with `sales`.
```
{
"Rules":[
{
"ResourceType":"collection",
"Resource":[
"collection/autopartsinventory",
"collection/sales*"
]
}
],
"AWSOwnedKey":false,
"KmsARN":"arn:aws:kms:us-east-1:123456789012:key/93fd6da4-a317-4c17-bfe9-382b5d988b36"
}
```
To use a service-owned key, set `AWSOwnedKey` to `true`:
```
{
"Rules":[
{
"ResourceType":"collection",
"Resource":[
"collection/autopartsinventory",
"collection/sales*"
]
}
],
"AWSOwnedKey":true
}
```
The following request creates the encryption policy:
```
aws opensearchserverless create-security-policy \
--name sales-inventory \
--type encryption \
--policy file://my-policy.json
```
Then, use the [CreateCollection](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_CreateCollection.html) API operation to create one or more collections that match one of the resource patterns.
### Viewing encryption policies
Before you create a collection, you might want to preview the existing encryption policies in your account to see which one has a resource pattern that matches your collection's name. The following [ListSecurityPolicies](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_ListSecurityPolicies.html) request lists all encryption policies in your account:
```
aws opensearchserverless list-security-policies --type encryption
```
The request returns information about all configured encryption policies. Use the contents of the `policy` element to view the pattern rules that are defined in the policy:
```
{
"securityPolicyDetails": [
{
"createdDate": 1663693217826,
"description": "Sample encryption policy",
"lastModifiedDate": 1663693217826,
"name": "my-policy",
"policy": "{\"Rules\":[{\"ResourceType\":\"collection\",\"Resource\":[\"collection/autopartsinventory\",\"collection/sales*\"]}],\"AWSOwnedKey\":true}",
"policyVersion": "MTY2MzY5MzIxNzgyNl8x",
"type": "encryption"
}
]
}
```
To view detailed information about a specific policy, including the KMS key, use the [GetSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_GetSecurityPolicy.html) command.
### Updating encryption policies
If you update the KMS key in an encryption policy, the change only applies to the newly created collections that match the configured name or pattern. It doesn't affect existing collections that have KMS keys already assigned.
The same applies to policy matching rules. If you add, modify, or delete a rule, the change only applies to newly created collections. Existing collections don't lose their assigned KMS key if you modify a policy's rules so that it no longer matches a collection's name.
To update an encryption policy in the OpenSearch Serverless console, choose **Encryption policies**, select the policy to modify, and choose **Edit**. Make your changes and choose **Save**.
To update an encryption policy using the OpenSearch Serverless API, use the [UpdateSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_UpdateSecurityPolicy.html) operation. The following request updates an encryption policy with a new policy JSON document:
```
aws opensearchserverless update-security-policy \
--name sales-inventory \
--type encryption \
--policy-version 2 \
--policy file://my-new-policy.json
```
### Deleting encryption policies
When you delete an encryption policy, any collections that are currently using the KMS key defined in the policy are not affected. To delete a policy in the OpenSearch Serverless console, select the policy and choose **Delete**.
You can also use the [DeleteSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_DeleteSecurityPolicy.html) operation:
```
aws opensearchserverless delete-security-policy --name my-policy --type encryption
```
## Encryption in transit
Within OpenSearch Serverless, all paths in a collection are encrypted in transit using Transport Layer Security 1.2 (TLS) with an industry-standard AES-256 cipher. Access to all APIs and Dashboards for Opensearch is also through TLS 1.2 . TLS is a set of industry-standard cryptographic protocols used for encrypting information that is exchanged over the network.
# Network access for Amazon OpenSearch Serverless
The network settings for an Amazon OpenSearch Serverless collection determine whether the collection is accessible over the internet from public networks, or whether it must be accessed privately.
Private access can apply to one or both of the following:
+ OpenSearch Serverless-managed VPC endpoints
+ Supported AWS services such as Amazon Bedrock
You can configure network access separately for a collection's *OpenSearch* endpoint and its corresponding *OpenSearch Dashboards* endpoint.
Network access is the isolation mechanism for allowing access from different source networks. For example, if a collection's OpenSearch Dashboards endpoint is publicly accessible but the OpenSearch API endpoint isn't, a user can access the collection data only through Dashboards when connecting from a public network. If they try to call the OpenSearch APIs directly from a public network, they'll be blocked. Network settings can be used for such permutations of source to resource type. Amazon OpenSearch Serverless supports both IPv4 and IPv6 connectivity.
**Topics**
+ [Network policies](#serverless-network-policies)
+ [Considerations](#serverless-network-considerations)
+ [Permissions required to configure network policies](#serverless-network-permissions)
+ [Policy precedence](#serverless-network-precedence)
+ [Creating network policies (console)](#serverless-network-console)
+ [Creating network policies (AWS CLI)](#serverless-network-cli)
+ [Viewing network policies](#serverless-network-list)
+ [Updating network policies](#serverless-network-update)
+ [Deleting network policies](#serverless-network-delete)
## Network policies
Network policies let you manage many collections at scale by automatically assigning network access settings to collections that match the rules defined in the policy.
In a network policy, you specify a series of *rules*. These rule define access permissions to collection endpoints and OpenSearch Dashboards endpoints. Each rule consists of an access type (public or private) and a resource type (collection and/or OpenSearch Dashboards endpoint). For each resource type (`collection` and `dashboard`), you specify a series of rules that define which collection(s) the policy will apply to.
In this sample policy, the first rule specifies VPC endpoint access to both the collection endpoint and the Dashboards endpoint for all collections beginning with the term `marketing*`. It also specifies Amazon Bedrock access.
**Note**
Private access to AWS services such as Amazon Bedrock *only* applies to the collection's OpenSearch endpoint, not to the OpenSearch Dashboards endpoint. Even if the `ResourceType` is `dashboard`, AWS services cannot be granted access to OpenSearch Dashboards.
The second rule specifies public access to the `finance` collection, but only for the collection endpoint (no Dashboards access).
```
[
{
"Description":"Marketing access",
"Rules":[
{
"ResourceType":"collection",
"Resource":[
"collection/marketing*"
]
},
{
"ResourceType":"dashboard",
"Resource":[
"collection/marketing*"
]
}
],
"AllowFromPublic":false,
"SourceVPCEs":[
"vpce-050f79086ee71ac05"
],
"SourceServices":[
"bedrock.amazonaws.com"
],
},
{
"Description":"Sales access",
"Rules":[
{
"ResourceType":"collection",
"Resource":[
"collection/finance"
]
}
],
"AllowFromPublic":true
}
]
```
This policy provides public access only to OpenSearch Dashboards for collections beginning with "finance". Any attempts to directly access the OpenSearch API will fail.
```
[
{
"Description": "Dashboards access",
"Rules": [
{
"ResourceType": "dashboard",
"Resource": [
"collection/finance*"
]
}
],
"AllowFromPublic": true
}
]
```
Network policies can apply to existing collections as well as future collections. For example, you can create a collection and then create a network policy with a rule that matches the collection name. You don't need to create network policies before you create collections.
## Considerations
Consider the following when you configure network access for your collections:
+ If you plan to configure VPC endpoint access for a collection, you must first create at least one [OpenSearch Serverless-managed VPC endpoint](serverless-vpc.md).
+ Private access to AWS services only applies to the collection's OpenSearch endpoint, not to the OpenSearch Dashboards endpoint. Even if the `ResourceType` is `dashboard`, AWS services cannot be granted access to OpenSearch Dashboards.
+ If a collection is accessible from public networks, it's also accessible from all OpenSearch Serverless-managed VPC endpoints and all AWS services.
+ Multiple network policies can apply to a single collection. For more information, see [Policy precedence](#serverless-network-precedence).
## Permissions required to configure network policies
Network access for OpenSearch Serverless uses the following AWS Identity and Access Management (IAM) permissions. You can specify IAM conditions to restrict users to network policies associated with specific collections.
+ `aoss:CreateSecurityPolicy` – Create a network access policy.
+ `aoss:ListSecurityPolicies` – List all network policies in the current account.
+ `aoss:GetSecurityPolicy` – View a network access policy specification.
+ `aoss:UpdateSecurityPolicy` – Modify a given network access policy, and change the VPC ID or public access designation.
+ `aoss:DeleteSecurityPolicy` – Delete a network access policy (after it's detached from all collections).
The following identity-based access policy allows a user to view all network policies, and update policies with the resource pattern `collection/application-logs`:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"aoss:UpdateSecurityPolicy"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aoss:collection": "application-logs"
}
}
},
{
"Effect": "Allow",
"Action": [
"aoss:ListSecurityPolicies",
"aoss:GetSecurityPolicy"
],
"Resource": "*"
}
]
}
```
------
**Note**
In addition, OpenSearch Serverless requires the `aoss:APIAccessAll` and `aoss:DashboardsAccessAll` permissions for collection resources. For more information, see [Using OpenSearch API operations](security-iam-serverless.md#security_iam_id-based-policy-examples-data-plane).
## Policy precedence
There can be situations where network policy rules overlap, within or across policies. When this happens, a rule that specifies public access overrides a rule that specifies private access for any collections that are common to *both* rules.
For example, in the following policy, both rules assign network access to the `finance` collection, but one rule specifies VPC access while the other specifies public access. In this situation, public access overrides VPC access *only for the finance collection* (because it exists in both rules), so the finance collection will be accessible from public networks. The sales collection will have VPC access from the specified endpoint.
```
[
{
"Description":"Rule 1",
"Rules":[
{
"ResourceType":"collection",
"Resource":[
"collection/sales",
"collection/finance"
]
}
],
"AllowFromPublic":false,
"SourceVPCEs":[
"vpce-050f79086ee71ac05"
]
},
{
"Description":"Rule 2",
"Rules":[
{
"ResourceType":"collection",
"Resource":[
"collection/finance"
]
}
],
"AllowFromPublic":true
}
]
```
If multiple VPC endpoints from different rules apply to a collection, the rules are additive and the collection will be accessible from all specified endpoints. If you set `AllowFromPublic` to `true` but also provide one or more `SourceVPCEs` or `SourceServices`, OpenSearch Serverless ignores the VPC endpoints and service identifiers, and the associated collections will have public access.
## Creating network policies (console)
Network policies can apply to existing collections as well as future collections. We recommend that you create network policies before you start creating collections.
**To create an OpenSearch Serverless network policy**
1. Open the Amazon OpenSearch Service console at [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home ).
1. On the left navigation panel, expand **Serverless** and choose **Network policies**.
1. Choose **Create network policy**.
1. Provide a name and description for the policy.
1. Provide one or more *rules*. These rules define access permissions for your OpenSearch Serverless collections and their OpenSearch Dashboards endpoints.
Each rule contains the following elements:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-network.html)
For each resource type that you select, you can choose existing collections to apply the policy settings to, and/or create one or more resource patterns. Resource patterns consist of a prefix and a wildcard (\$1), and define which collections the policy settings will apply to.
For example, if you include a pattern called `Marketing*`, any new or existing collections whose names start with "Marketing" will have the network settings in this policy automatically applied to them. A single wildcard (`*`) applies the policy to all current and future collections.
In addition, you can specify the name of a *future* collection without a wildcard, such as `Finance`. OpenSearch Serverless will apply the policy settings to any newly created collection with that exact name.
1. When you're satisfied with your policy configuration, choose **Create**.
## Creating network policies (AWS CLI)
To create a network policy using the OpenSearch Serverless API operations, you specify rules in JSON format. The [CreateSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_CreateSecurityPolicy.html) request accepts both inline policies and .json files. All collections and patterns must take the form `collection/`.
**Note**
The resource type `dashboards` only allows permission to OpenSearch Dashboards, but in order for OpenSearch Dashboards to function, you must also allow collection access from the same sources. See the second policy below for an example.
To specify private access, include one or both of the following elements:
+ `SourceVPCEs` – Specify one or more OpenSearch Serverless–managed VPC endpoints.
+ `SourceServices` – Specify the identifier of one or more supported AWS services. Currently, the following service identifiers are supported:
+ `bedrock.amazonaws.com` – Amazon Bedrock
The following sample network policy provides private access, to a VPC endpoint and Amazon Bedrock, to collection endpoints only for collections beginning with the prefix `log*`. Authenticated users can't sign in to OpenSearch Dashboards; they can only access the collection endpoint programmatically.
```
[
{
"Description":"Private access for log collections",
"Rules":[
{
"ResourceType":"collection",
"Resource":[
"collection/log*"
]
}
],
"AllowFromPublic":false,
"SourceVPCEs":[
"vpce-050f79086ee71ac05"
],
"SourceServices":[
"bedrock.amazonaws.com"
],
}
]
```
The following policy provides public access to the OpenSearch endpoint *and* OpenSearch Dashboards for a single collection named `finance`. If the collection doesn't exist, the network settings will be applied to the collection if and when it's created.
```
[
{
"Description":"Public access for finance collection",
"Rules":[
{
"ResourceType":"dashboard",
"Resource":[
"collection/finance"
]
},
{
"ResourceType":"collection",
"Resource":[
"collection/finance"
]
}
],
"AllowFromPublic":true
}
]
```
The following request creates the above network policy:
```
aws opensearchserverless create-security-policy \
--name sales-inventory \
--type network \
--policy "[{\"Description\":\"Public access for finance collection\",\"Rules\":[{\"ResourceType\":\"dashboard\",\"Resource\":[\"collection\/finance\"]},{\"ResourceType\":\"collection\",\"Resource\":[\"collection\/finance\"]}],\"AllowFromPublic\":true}]"
```
To provide the policy in a JSON file, use the format `--policy file://my-policy.json`
## Viewing network policies
Before you create a collection, you might want to preview the existing network policies in your account to see which one has a resource pattern that matches your collection's name. The following [ListSecurityPolicies](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_ListSecurityPolicies.html) request lists all network policies in your account:
```
aws opensearchserverless list-security-policies --type network
```
The request returns information about all configured network policies. To view the pattern rules defined in the one specific policy, find the policy information in the contents of the `securityPolicySummaries` element in the response. Note the `name` and `type` of this policy and use these properties in a [GetSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_GetSecurityPolicy.html) request to receive a response with the following policy details:
```
{
"securityPolicyDetail": [
{
"type": "network",
"name": "my-policy",
"policyVersion": "MTY2MzY5MTY1MDA3Ml8x",
"policy": "[{\"Description\":\"My network policy rule\",\"Rules\":[{\"ResourceType\":\"dashboard\",\"Resource\":[\"collection/*\"]}],\"AllowFromPublic\":true}]",
"createdDate": 1663691650072,
"lastModifiedDate": 1663691650072
}
]
}
```
To view detailed information about a specific policy, use the [GetSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_GetSecurityPolicy.html) command.
## Updating network policies
When you modify the VPC endpoints or public access designation for a network, all associated collections are impacted. To update a network policy in the OpenSearch Serverless console, expand **Network policies**, select the policy to modify, and choose **Edit**. Make your changes and choose **Save**.
To update a network policy using the OpenSearch Serverless API, use the [UpdateSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_UpdateSecurityPolicy.html) command. You must include a policy version in the request. You can retrieve the policy version by using the `ListSecurityPolicies` or `GetSecurityPolicy` commands. Including the most recent policy version ensures that you don't inadvertently override a change made by someone else.
The following request updates a network policy with a new policy JSON document:
```
aws opensearchserverless update-security-policy \
--name sales-inventory \
--type network \
--policy-version MTY2MzY5MTY1MDA3Ml8x \
--policy file://my-new-policy.json
```
## Deleting network policies
Before you can delete a network policy, you must detach it from all collections. To delete a policy in the OpenSearch Serverless console, select the policy and choose **Delete**.
You can also use the [DeleteSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_DeleteSecurityPolicy.html) command:
```
aws opensearchserverless delete-security-policy --name my-policy --type network
```
# FIPS compliance in Amazon OpenSearch Serverless
Amazon OpenSearch Serverless supports Federal Information Processing Standards (FIPS) 140-2, which is a U.S. and Canadian government standard that specifies security requirements for cryptographic modules that protect sensitive information. When you connect to FIPS-enabled endpoints with OpenSearch Serverless, cryptographic operations occur using FIPS-validated cryptographic libraries.
OpenSearch Serverless FIPS endpoints are available in AWS Regions where FIPS is supported. These endpoints use TLS 1.2 or later and FIPS-validated cryptographic algorithms for all communications. For more information, see [FIPS compliance](https://docs.aws.amazon.com/verified-access/latest/ug/fips-compliance.html) in the *AWS Verified access User Guide*.
**Topics**
+ [Using FIPS endpoints with OpenSearch Serverless](#using-fips-endpoints-opensearch-serverless)
+ [Use FIPS endpoints with AWS SDKs](#using-fips-endpoints-aws-sdks)
+ [Configure security groups for VPC endpoints](#configuring-security-groups-vpc-endpoints)
+ [Use the FIPS VPC endpoint](#using-fips-vpc-endpoint)
+ [Verify FIPS compliance](#verifying-fips-compliance)
+ [Resolve FIPS endpoint connectivity issues in private hosted zones](serverless-fips-endpoint-issues.md)
## Using FIPS endpoints with OpenSearch Serverless
In AWS Regions where FIPS is supported, OpenSearch Serverless collections are accessible through both standard and FIPS-compliant endpoints. For more information, see [FIPS compliance](https://docs.aws.amazon.com/verified-access/latest/ug/fips-compliance.html) in the *AWS Verified access User Guide*.
In the following examples, replace *collection\$1id* and *AWS Region* with your collection ID and its AWS Region.
+ **Standard endpoint** – **https://*collection\$1id*.*AWS Region*.aoss.amazonaws.com**.
+ **FIPS-compliant endpoint** – **https://*collection\$1id*.*AWS Region*.aoss-fips.amazonaws.com**.
Similarly, OpenSearch Dashboards are accessible through both standard and FIPS-compliant endpoints:
+ **Standard Dashboards endpoint** – **https://*collection\$1id*.*AWS Region*.aoss.amazonaws.com/\$1dashboards**.
+ **FIPS-compliant Dashboards endpoint** – **https://*collection\$1id*.*AWS Region*.aoss-fips.amazonaws.com/\$1dashboards**.
**Note**
In FIPS-enabled Regions, both standard and FIPS-compliant endpoints provide FIPS-compliant cryptography. The FIPS-specific endpoints help you meet compliance requirements that specifically mandate the use of endpoints with **FIPS** in the name.
## Use FIPS endpoints with AWS SDKs
When using AWS SDKs, you can specify the FIPS endpoint when creating the client. In the following example, replace *collection\$1id* and *AWS Region* with your collection ID and its AWS Region.
```
# Python SDK example
from opensearchpy import OpenSearch, RequestsHttpConnection, AWSV4SignerAuth
import boto3
host = '"https://collection_id.AWS Region.aoss-fips.amazonaws.com"
region = 'us-west-2'
service = 'aoss'
credentials = boto3.Session().get_credentials()
auth = AWSV4SignerAuth(credentials, region, service)
client = OpenSearch(
hosts = [{'host': host, 'port': 443}],
http_auth = auth,
use_ssl = True,
verify_certs = True,
connection_class = RequestsHttpConnection,
pool_maxsize = 20
)
```
## Configure security groups for VPC endpoints
To ensure proper communication with your FIPS-compliant Amazon VPC (VPC) endpoint, create or modify a security group to allow inbound HTTPS traffic (TCP port 443) from the resources in your VPC that need to access OpenSearch Serverless. Then associate this security group with your VPC endpoint during creation or by modifying the endpoint after creation. For more information, see [Create a security group](https://docs.aws.amazon.com/vpc/latest/userguide/creating-security-groups.html) in the *Amazon VPC User Guide*.
## Use the FIPS VPC endpoint
After creating the FIPS-compliant VPC endpoint, you can use it to access OpenSearch Serverless from resources within your VPC. To use the endpoint for API operations, configure your SDK to use the Regional FIPS endpoint as described in the [Using FIPS endpoints with OpenSearch Serverless](#using-fips-endpoints-opensearch-serverless) section. For OpenSearch Dashboards access, use the collection-specific Dashboards URL, which will automatically route through the FIPS-compliant VPC endpoint when accessed from within your VPC. For more information, see [Using OpenSearch Dashboards with Amazon OpenSearch Service](dashboards.md).
## Verify FIPS compliance
To verify that your connections to OpenSearch Serverless are using FIPS-compliant cryptography, use AWS CloudTrail to monitor API calls made to OpenSearch Serverless. Check that the `eventSource` field in CloudTrail logs displays `aoss-fips.amazonaws.com` for API calls.
For OpenSearch Dashboards access, you can use browser developer tools to inspect the TLS connection details and verify that FIPS-compliant cipher suites are being used.
# Resolve FIPS endpoint connectivity issues in private hosted zones
FIPS endpoints work with Amazon OpenSearch Serverless collections that have public access. For newly created VPC collections that use newly created VPC endpoints, FIPS endpoints function as expected. For other VPC collections, you might need to perform manual setup to ensure FIPS endpoints operate correctly.
**To configure FIPS private hosted zones in Amazon Route 53**
1. Open the Route 53 console at [https://console.aws.amazon.com/route53/](https://console.aws.amazon.com/route53/).
1. Review your hosted zones:
1. Locate the hosted zones for the AWS Regions your collections are in.
1. Verify the hosted zone naming patterns:
+ Non-FIPS format: `region.aoss.amazonaws.com`.
+ FIPS format: `region.aoss-fips.amazonaws.com`.
1. Confirm the **Type** for all of your hosted zones is set to **Private hosted zone**.
1. If the FIPS private hosted zone is missing:
1. Select the corresponding non-FIPS private hosted zone.
1. Copy the **Associated VPCs** information. For example: `vpc-1234567890abcdef0 | us-east-2`.
1. Find the wildcard domain record. For example: `*.us-east-2.aoss.amazonaws.com`.
1. Copy the **Value/Route traffic to** information. For example:`uoc1c1qsw7poexampleewjeno1pte3rw.3ym756xh7yj.aoss.searchservices.aws`.
1. Create the FIPS private hosted zone:
1. Create a new private hosted zone with the FIPS format. For example: `us-east-2.aoss-fips.amazonaws.com`.
1. For **Associated VPCs**, enter the VPC information you copied from the non-FIPS private hosted zone.
1. Add a new record with the following settings:
1. Record name: \$1
1. Record type: CNAME
1. Value: Enter the **Value/Route traffic to** information you copied earlier.
## Common Issues
If you experience connectivity issues with your FIPS-compliant VPC endpoints, use the following information to help resolve the problem.
+ DNS resolution failures - You cannot resolve the FIPS endpoint domain name within your VPC
+ Connection timeouts - Your requests to the FIPS endpoint time out
+ Access denied errors - Authentication or authorization fails when using FIPS endpoints
+ Missing private hosted zone records for VPC-only collections
**To troubleshoot FIPS endpoint connectivity**
1. Verify your Private Hosted Zone configuration:
1. Confirm that a Private Hosted Zone exists for the FIPS endpoint domain (`*.region.aoss-fips.amazonaws.com`.
1. Verify that the private hosted zone is associated with the correct VPC.
For more information, see [Private hosted zones](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted- zones-private.html) in the *Amazon Route 53 Developer Guide*, and [Manage DNS names](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html) in the *AWS PrivateLink Guide*.
1. Test DNS resolution:
1. Connect to an EC2 instance in your VPC.
1. Run the following command:
```
nslookup collection-id.region.aoss-fips.amazonaws.com
```
1. Confirm that the response includes the private IP address of your VPC endpoint.
For more information, see [Endpoint policies](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints- access.html#endpoint-dns-verification), and [DNS attributes](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc- dns-troubleshooting) in the *Amazon VPC User Guide*.
1. Check your security group settings:
1. Verify that the security group attached to the VPC endpoint permits HTTPS traffic (port 443) from your resources.
1. Confirm that security groups for your resources permit outbound traffic to the VPC endpoint.
For more information, see [Endpoint policies](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html#vpc-endpoint-security-groups) in the *AWS PrivateLink Guide*, and [Security groups](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-security-groups.html#SecurityGroupRules) in the *Amazon VPC User Guide *.
1. Review your network ACL configuration:
1. Verify that network ACLs permit traffic between your resources and the VPC endpoint.
For more information, see [Network ACLs](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network- acls.html#nacl-troubleshooting) in the *Amazon VPC User Guide*.
1. Review your endpoint policy:
1. Check that the VPC endpoint policy permits the required actions on your OpenSearch Serverless resources.
For more information, see [VPC endpoint permissions required](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-vpc.html#serverless-vpc-permissions), and [Endpoints policies](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints- access.html#vpc-endpoint-policies) in the *AWS PrivateLink Guide*.
**Tip**
If you use custom DNS resolvers in your VPC, configure them to forward requests for `*.amazonaws.com` domains to the AWS servers.
# Data access control for Amazon OpenSearch Serverless
With data access control in Amazon OpenSearch Serverless, you can allow users to access collections and indexes, regardless of their access mechanism or network source. You can provide access to IAM roles and [SAML identities](serverless-saml.md).
You manage access permissions through *data access policies*, which apply to collections and index resources. Data access policies help you manage collections at scale by automatically assigning access permissions to collections and indexes that match a specific pattern. Multiple data access policies can apply to a single resource. Note that you must have a data access policy for your collection in order to access your OpenSearch Dashboards URL.
**Topics**
+ [Data access policies versus IAM policies](#serverless-data-access-vs-iam)
+ [IAM permissions required to configure data access policies](#serverless-data-access-permissions)
+ [Policy syntax](#serverless-data-access-syntax)
+ [Supported policy permissions](#serverless-data-supported-permissions)
+ [Sample datasets on OpenSearch Dashboards](#serverless-data-sample-index)
+ [Creating data access policies (console)](#serverless-data-access-console)
+ [Creating data access policies (AWS CLI)](#serverless-data-access-cli)
+ [Viewing data access policies](#serverless-data-access-list)
+ [Updating data access policies](#serverless-data-access-update)
+ [Deleting data access policies](#serverless-data-access-delete)
+ [Cross-account data access](#serverless-data-access-cross)
## Data access policies versus IAM policies
Data access policies are logically separate from AWS Identity and Access Management (IAM) policies. IAM permissions control access to the [serverless API operations](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/Welcome.html), such as `CreateCollection` and `ListAccessPolicies`. Data access policies control access to the [OpenSearch operations](#serverless-data-supported-permissions) that OpenSearch Serverless supports, such as `PUT ` or `GET _cat/indices`.
The IAM permissions that control access to data access policy API operations, such as `aoss:CreateAccessPolicy` and `aoss:GetAccessPolicy` (described in the next section), don't affect the permission specified in a data access policy.
For example, suppose an IAM policy denies a user from creating data access policies for `collection-a`, but allows them to create data access policies for all collections (`*`):
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"aoss:CreateAccessPolicy"
],
"Resource": "*",
"Condition": {
"StringLike": {
"aoss:collection": "collection-a"
}
}
},
{
"Effect": "Allow",
"Action": [
"aoss:CreateAccessPolicy"
],
"Resource": "*"
}
]
}
```
------
If the user creates a data access policy that allows certain permission to *all* collections (`collection/*` or `index/*/*`) the policy will apply to all collections, including collection A.
**Important**
Being granted permissions within a data access policy is not sufficient to access data in your OpenSearch Serverless collection. An associated principal must *also* be granted access to the IAM permissions `aoss:APIAccessAll` and `aoss:DashboardsAccessAll`. Both permissions grant full access to collection resources, while the Dashboards permission also provides access to OpenSearch Dashboards. If a principal doesn't have both of these IAM permissions, they will receive 403 errors when attempting to send requests to the collection. For more information, see [Using OpenSearch API operations](security-iam-serverless.md#security_iam_id-based-policy-examples-data-plane).
## IAM permissions required to configure data access policies
Data access control for OpenSearch Serverless uses the following IAM permissions. You can specify IAM conditions to restrict users to specific access policy names.
+ `aoss:CreateAccessPolicy` – Create an access policy.
+ `aoss:ListAccessPolicies` – List all access policies.
+ `aoss:GetAccessPolicy` – See details about a specific access policy.
+ `aoss:UpdateAccessPolicy` – Modify an access policy.
+ `aoss:DeleteAccessPolicy` – Delete an access policy.
The following identity-based access policy allows a user to view all access policies, and update policies that contain the resource pattern `collection/logs`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"aoss:ListAccessPolicies",
"aoss:GetAccessPolicy"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"aoss:UpdateAccessPolicy"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEquals": {
"aoss:collection": [
"logs"
]
}
}
}
]
}
```
------
**Note**
In addition, OpenSearch Serverless requires the `aoss:APIAccessAll` and `aoss:DashboardsAccessAll` permissions for collection resources. For more information, see [Using OpenSearch API operations](security-iam-serverless.md#security_iam_id-based-policy-examples-data-plane).
## Policy syntax
A data access policy includes a set of rules, each with the following elements:
| Element | Description |
| --- | --- |
| ResourceType | The type of resource (collection or index) that the permissions apply to. Alias and template permissions are at the collection level, while permissions for creating, modifying, and searching data are at the index level. For more information, see [Supported policy permissions](#serverless-data-supported-permissions). |
| Resource | A list of resource names and/or patterns. Patterns are prefixes followed by a wildcard (\$1), which allow the associated permissions to apply to multiple resources.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html) |
| Permission | A list of permissions to grant for the specified resources. For a complete list of permissions and the API operations they allow, see [Supported OpenSearch API operations and permissions](serverless-genref.md#serverless-operations). |
| Principal | A list of one or more principals to grant access to. Principals can be IAM role ARNs or SAML identities. These principals must be within the current AWS account. Data access policies don't directly support cross-account access, but you can include a role in your policy that a user from a different AWS account can assume in the collection-owning account. For more information, see [Cross-account data access](#serverless-data-access-cross). |
The following example policy grants alias and template permissions to the collection called `autopartsinventory`, as well as any collections that begin with the prefix `sales*`. It also grants read and write permissions to all indexes within the `autopartsinventory` collection, and any indexes in the `salesorders` collection that begin with the prefix `orders*`.
```
[
{
"Description": "Rule 1",
"Rules":[
{
"ResourceType":"collection",
"Resource":[
"collection/autopartsinventory",
"collection/sales*"
],
"Permission":[
"aoss:CreateCollectionItems",
"aoss:UpdateCollectionItems",
"aoss:DescribeCollectionItems"
]
},
{
"ResourceType":"index",
"Resource":[
"index/autopartsinventory/*",
"index/salesorders/orders*"
],
"Permission":[
"aoss:*"
]
}
],
"Principal":[
"arn:aws:iam::123456789012:user/Dale",
"arn:aws:iam::123456789012:role/RegulatoryCompliance",
"saml/123456789012/myprovider/user/Annie",
"saml/123456789012/anotherprovider/group/Accounting"
]
}
]
```
You can't explicitly deny access within a policy. Therefore, all policy permissions are additive. For example, if one policy grants a user `aoss:ReadDocument`, and another policy grants `aoss:WriteDocument`, the user will have *both* permissions. If a third policy grants the same user `aoss:*`, then the user can perform *all* actions on the associated index; more restrictive permissions don't override less restrictive ones.
## Supported policy permissions
The following permissions are supported in data access policies. For the OpenSearch API operations that each permission allows, see [Supported OpenSearch API operations and permissions](serverless-genref.md#serverless-operations).
**Collection permissions**
+ `aoss:CreateCollectionItems`
+ `aoss:DeleteCollectionItems`
+ `aoss:UpdateCollectionItems`
+ `aoss:DescribeCollectionItems`
+ `aoss:*`
**Index permissions**
+ `aoss:ReadDocument`
+ `aoss:WriteDocument`
+ `aoss:CreateIndex`
+ `aoss:DeleteIndex`
+ `aoss:UpdateIndex`
+ `aoss:DescribeIndex`
+ `aoss:*`
## Sample datasets on OpenSearch Dashboards
OpenSearch Dashboards provides [sample datasets](https://opensearch.org/docs/latest/dashboards/quickstart-dashboards/#adding-sample-data) that come with visualizations, dashboards, and other tools to help you explore Dashboards before you add your own data. To create indexes from this sample data, you need a data access policy that provides permissions to the dataset that you want to work with. The following policy uses a wildcard (`*`) to provide permissions to all three sample datasets.
```
[
{
"Rules": [
{
"Resource": [
"index//opensearch_dashboards_sample_data_*"
],
"Permission": [
"aoss:CreateIndex",
"aoss:DescribeIndex",
"aoss:ReadDocument"
],
"ResourceType": "index"
}
],
"Principal": [
"arn:aws:iam:::user/"
]
}
]
```
## Creating data access policies (console)
You can create a data access policy using the visual editor, or in JSON format. Any new collections that match one of the patterns defined in the policy will be assigned the corresponding permissions when you create the collection.
**To create an OpenSearch Serverless data access policy**
1. Open 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, expand **Serverless** and under **Security**, choose **Data access policies**.
1. Choose **Create access policy**.
1. Provide a name and description for the policy.
1. Provide a name for the first rule in your policy. For example, "Logs collection access".
1. Choose **Add principals** and select one or more IAM roles or [SAML users and groups](serverless-saml.md) to provide data access to.
**Note**
In order to select principals from the dropdown menus, you must have the `iam:ListUsers` and `iam:ListRoles` permissions (for IAM principals) and `aoss:ListSecurityConfigs` permission (for SAML identities).
1. Choose **Grant** and select the alias, template, and index permissions to grant the associated principals. For a full list of permissions and the access they allow, see [Supported OpenSearch API operations and permissions](serverless-genref.md#serverless-operations).
1. (Optional) Configure additional rules for the policy.
1. Choose **Create**. There might be about a minute of lag time between when you create the policy and when the permissions are enforced. If it takes more than 5 minutes, contact [Support](https://console.aws.amazon.com/support/home).
**Important**
If your policy only includes index permissions (and no collection permissions), you might still see a message for matching collections stating `Collection cannot be accessed yet. Configure data access policies so that users can access the data within this collection`. You can ignore this warning. Allowed principals can still perform their assigned index-related operations on the collection.
## Creating data access policies (AWS CLI)
To create a data access policy using the OpenSearch Serverless API, use the `CreateAccessPolicy` command. The command accepts both inline policies and .json files. Inline policies must be encoded as a [JSON escaped string](https://www.freeformatter.com/json-escape.html).
The following request creates a data access policy:
```
aws opensearchserverless create-access-policy \
--name marketing \
--type data \
--policy "[{\"Rules\":[{\"ResourceType\":\"collection\",\"Resource\":[\"collection/autopartsinventory\",\"collection/sales*\"],\"Permission\":[\"aoss:UpdateCollectionItems\"]},{\"ResourceType\":\"index\",\"Resource\":[\"index/autopartsinventory/*\",\"index/salesorders/orders*\"],\"Permission\":[\"aoss:ReadDocument\",\"aoss:DescribeIndex\"]}],\"Principal\":[\"arn:aws:iam::123456789012:user/Shaheen\"]}]"
```
To provide the policy within a .json file, use the format `--policy file://my-policy.json`.
The principals included in the policy can now use the [OpenSearch operations](#serverless-data-supported-permissions) that they were granted access to.
## Viewing data access policies
Before you create a collection, you might want to preview the existing data access policies in your account to see which one has a resource pattern that matches your collection's name. The following [ListAccessPolicies](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_ListAccessPolicies.html) request lists all data access policies in your account:
```
aws opensearchserverless list-access-policies --type data
```
The request returns information about all configured data access policies. To view the pattern rules defined in the one specific policy, find the policy information in the contents of the `accessPolicySummaries` element in the response. Note the `name` and `type` of this policy and use these properties in a [GetAccessPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_GetAccessPolicy.html) request to receive a response with the following policy details:
```
{
"accessPolicyDetails": [
{
"type": "data",
"name": "my-policy",
"policyVersion": "MTY2NDA1NDE4MDg1OF8x",
"description": "My policy",
"policy": "[{\"Rules\":[{\"ResourceType\":\"collection\",\"Resource\":[\"collection/autopartsinventory\",\"collection/sales*\"],\"Permission\":[\"aoss:UpdateCollectionItems\"]},{\"ResourceType\":\"index\",\"Resource\":[\"index/autopartsinventory/*\",\"index/salesorders/orders*\"],\"Permission\":[\"aoss:ReadDocument\",\"aoss:DescribeIndex\"]}],\"Principal\":[\"arn:aws:iam::123456789012:user/Shaheen\"]}]",
"createdDate": 1664054180858,
"lastModifiedDate": 1664054180858
}
]
}
```
You can include resource filters to limit the results to policies that contain specific collections or indexes:
```
aws opensearchserverless list-access-policies --type data --resource "index/autopartsinventory/*"
```
To view details about a specific policy, use the [GetAccessPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_GetAccessPolicy.html) command.
## Updating data access policies
When you update a data access policy, all associated collections are impacted. To update a data access policy in the OpenSearch Serverless console, choose **Data access control**, select the policy to modify, and choose **Edit**. Make your changes and choose **Save**.
To update a data access policy using the OpenSearch Serverless API, send an `UpdateAccessPolicy` request. You must include a policy version, which you can retrieve using the `ListAccessPolicies` or `GetAccessPolicy` commands. Including the most recent policy version ensures that you don't inadvertently override a change made by someone else.
The following [UpdateAccessPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_UpdateAccessPolicy.html) request updates a data access policy with a new policy JSON document:
```
aws opensearchserverless update-access-policy \
--name sales-inventory \
--type data \
--policy-version MTY2NDA1NDE4MDg1OF8x \
--policy file://my-new-policy.json
```
There might be a few minutes of lag time between when you update the policy and when the new permissions are enforced.
## Deleting data access policies
When you delete a data access policy, all associated collections lose the access that is defined in the policy. Make sure that your IAM and SAML users have the appropriate access to the collection before you delete a policy. To delete a policy in the OpenSearch Serverless console, select the policy and choose **Delete**.
You can also use the [DeleteAccessPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_DeleteAccessPolicy.html) command:
```
aws opensearchserverless delete-access-policy --name my-policy --type data
```
## Cross-account data access
While you can't create a data access policy with cross-account identity or cross-account collections, you can still set up cross-account access with the assume role option. For example, if `account-a` owns a collection that `account-b` needs access to, the user from `account-b` can assume a role in `account-a`. The role must have the IAM permissions `aoss:APIAccessAll` and `aoss:DashboardsAccessAll`, and be included in the data access policy on `account-a`.
# Data plane access through AWS PrivateLink
Amazon OpenSearch Serverless supports two types of AWS PrivateLink connections for control plane and data plane operations. Control plane operations include the creation and deletion of collections and the management of access policies. Data plane operations are for indexing and querying data within a collection. This page covers data plane VPC endpoints. For information about control plane AWS PrivateLink endpoints, see [Control plane access through AWS PrivateLink](serverless-vpc-cp.md).
You can use AWS PrivateLink to create a private connection between your VPC and Amazon OpenSearch Serverless. You can access OpenSearch Serverless as if it were in your VPC, without the use of an internet gateway, NAT device, VPN connection, or Direct Connect connection. Instances in your VPC don't need public IP addresses to access OpenSearch Serverless. For more information on VPC network access, see [Network connectivity patterns for Amazon OpenSearch Serverless](https://aws.amazon.com/blogs/big-data/network-connectivity-patterns-for-amazon-opensearch-serverless/).
You establish this private connection by creating an *interface endpoint*, powered by AWS PrivateLink. We create an endpoint network interface 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 Serverless.
For more information, see [Access AWS services through AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-access-aws-services.html) in the *AWS PrivateLink Guide*.
**Topics**
+ [DNS resolution of collection endpoints](#vpc-endpoint-dnc)
+ [VPCs and network access policies](#vpc-endpoint-network)
+ [VPCs and endpoint policies](#vpc-endpoint-policy)
+ [Considerations](#vpc-endpoint-considerations)
+ [Permissions required](#serverless-vpc-permissions)
+ [Create an interface endpoint for OpenSearch Serverless](#serverless-vpc-create)
+ [Shared VPC setup for Amazon OpenSearch Serverless](#shared-vpc-setup)
## DNS resolution of collection endpoints
When you create a data plane VPC endpoint through the OpenSearch Serverless console, the service creates a new Amazon Route 53 [private hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html) and attaches it to the VPC. This private hosted zone consists of a record to resolve the wildcard DNS record for OpenSearch Serverless collections (`*.us-east-1.aoss.amazonaws.com`) to the interface addresses used for the endpoint. You only need one OpenSearch Serverless VPC endpoint in a VPC to access any and all collections and Dashboards in each AWS Region. Every VPC with an endpoint for OpenSearch Serverless has its own private hosted zone attached.
The OpenSearch Serverless interface endpoint also creates a public Route 53 wildcard DNS record for all collections in the Region. The DNS name resolves to the OpenSearch Serverless public IP addresses. Clients in VPCs that don't have an OpenSearch Serverless VPC endpoint or clients in public networks can use the public Route 53 resolver and access the collections and Dashboards with those IP addresses. The IP address type (IPv4, IPv6, or Dualstack) of VPC endpoint is determined based on the subnets provided when you [create an interface endpoint for OpenSearch Serverless](#serverless-vpc-create).
**Note**
OpenSearch Serverless creates an additonal Amazon Route 53 private hosted zone (``.opensearch.amazonaws.com``) for an OpenSearch Service domain resolution. You can update your existing IPv4 VPC endpoint to Dualstack by using the [update-vpc-endpoint](https://docs.aws.amazon.com/cli/latest/reference/opensearchserverless/update-vpc-endpoint.html) command in the AWS CLI.
The DNS resolver address for a given VPC is the second IP address of the VPC CIDR. Any client in the VPC needs to use that resolver to get the VPC endpoint address for any collection. The resolver uses private hosted zone created by OpenSearch Serverless. It's sufficient to use that resolver for all collections in any account. It's also possible to use the VPC resolver for some collection endpoints and the public resolver for others, although it's not typically necessary.
## VPCs and network access policies
To grant network permission to OpenSearch APIs and Dashboards for your collections, you can use OpenSearch Serverless [network access policies](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-network.html). You can control this network access either from your VPC endpoint(s) or the public internet. Since your network policy only controls traffic permissions, you must also set up a [data access policy](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html) that specifies permission to operate on the data in a collection and its indices. Think of an OpenSearch Serverless VPC endpoint as an access point to the service, a network access policy as the network-level access point to collections and Dashboards, and a data access policy as the access point for fine-grained access control for any operation on data in the collection.
Since you can specify multiple VPC endpoint IDs in a network policy, we recommend that you create a VPC endpoint for every VPC that needs to access a collection. These VPCs can belong to different AWS accounts than the account that owns the OpenSearch Serverless collection and network policy. We don't recommend that you create a VPC-to-VPC peering or other proxying solution between two accounts so that one account's VPC can use another account's VPC endpoint. This is less secure and cost effective than each VPC having its own endpoint. The first VPC will not be easily visible to the other VPC's admin, who has set up access to that VPC's endpoint in the network policy.
## VPCs and endpoint policies
Amazon OpenSearch Serverless supports endpoint policies for VPCs. An endpoint policy is an IAM resource-based policy that you attach to a VPC endpoint to control which AWS principals can use the endpoint to access your AWS service. For more information, see [Control access to VPC endpoints using endpoint policies](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html).
To use an endpoint policy, you must first create an interface endpoint. You can create an interface endpoint using either the OpenSearch Serverless console or the OpenSearch Serverless API. After you create your interface endpoint, you will need to add the endpoint policy to the endpoint. For more information, see [Create an interface endpoint for OpenSearch Serverless](#serverless-vpc-create).
**Note**
You can't define an endpoint policy directly in the OpenSearch Service console.
An endpoint policy does not override or replace other identity-based policies, resource-based policies, network policies, or data access policies you may have configured. For more information on updating endpoint policies, see [Control access to VPC endpoints using endpoint policies](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html).
By default, an endpoint policy grants full access to your VPC endpoint.
```
{
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "*",
"Resource": "*"
}
]
}
```
Although the default VPC endpoint policy grants full endpoint access, you can configure a VPC endpoint policy to allow access to specific roles and users. To do this, see the following example:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"123456789012",
"987654321098"
]
},
"Action": "*",
"Resource": "*"
}
]
}
```
------
You can specify an OpenSearch Serverless collection to be included as a conditional element in your VPC endpoint policy. To do this, see the following example:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aoss:collection": [
"coll-abc"
]
}
}
}
]
}
```
------
Support for `aoss:CollectionId` is supported.
```
Condition": {
"StringEquals": {
"aoss:CollectionId": "collection-id"
}
}
```
You can use SAML identities in your VPC endpoint policy to determine VPC endpoint access. You must use a wildcard `(*)` in the principal section of your VPC endpoint policy. To do this, see the following example:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "*",
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"saml:cn": [
"saml/111122223333/idp123/group/football",
"saml/111122223333/idp123/group/soccer",
"saml/111122223333/idp123/group/cricket"
]
}
}
}
]
}
```
------
Additionally, you can configure your endpoint policy to include a specific SAML principal policy. To do this, see the following:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalTag/Department": [
"Engineering"]
}
}
}
]
}
```
------
For more information on using SAML authentication with Amazon OpenSearch Serverless, see [SAML authentication for Amazon OpenSearch Serverless](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-saml.html).
You can also include IAM and SAML users in the same VPC endpoint policy. To do this, see the following example:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "*",
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"saml:cn": [
"saml/111122223333/idp123/group/football",
"saml/111122223333/idp123/group/soccer",
"saml/111122223333/idp123/group/cricket"
]
}
}
},
{
"Effect": "Allow",
"Principal": {
"AWS": [
"111122223333"
]
},
"Action": "*",
"Resource": "*"
}
]
}
```
------
You can also access an Amazon OpenSearch Serverless collection from Amazon EC2 via interface VPC endpoints. For more information see, [Access an OpenSearch Serverless collection from Amazon EC2 (via interface VPC endpoints)](https://aws.amazon.com/blogs/big-data/network-connectivity-patterns-for-amazon-opensearch-serverless/).
## Considerations
Before you set up an interface endpoint for OpenSearch Serverless, consider the following:
+ OpenSearch Serverless supports making calls to all supported [OpenSearch API operations](serverless-genref.md#serverless-operations) (not configuration API operations) through the interface endpoint.
+ After you create an interface endpoint for OpenSearch Serverless, you still need to include it in [network access policies](serverless-network.md) in order for it to access serverless collections.
+ By default, full access to OpenSearch Serverless is allowed through the interface endpoint. You can associate a security group with the endpoint network interfaces to control traffic to OpenSearch Serverless through the interface endpoint.
+ A single AWS account can have a maximum of 50 OpenSearch Serverless VPC endpoints.
+ If you enable public internet access to your collection's API or Dashboards in a network policy, your collection is accessible by any VPC and by the public internet.
+ If you're on-premises and outside of the VPC, you can't use a DNS resolver for the OpenSearch Serverless VPC endpoint resolution directly. If you need VPN access, the VPC needs a DNS proxy resolver for external clients to use. Route 53 provides an inbound endpoint option that you can use to resolve DNS queries to your VPC from your on-premises network or another VPC.
+ The private hosted zone that OpenSearch Serverless creates and attaches to the VPC is managed by the service, but it shows up in your Amazon Route 53 resources and is billed to your account.
+ For other considerations, see [Considerations](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#considerations-interface-endpoints) in the *AWS PrivateLink Guide*.
## Permissions required
VPC access for OpenSearch Serverless uses the following AWS Identity and Access Management (IAM) permissions. You can specify IAM conditions to restrict users to specific collections.
+ `aoss:CreateVpcEndpoint` – Create a VPC endpoint.
+ `aoss:ListVpcEndpoints` – List all VPC endpoints.
+ `aoss:BatchGetVpcEndpoint` – See details about a subset of VPC endpoints.
+ `aoss:UpdateVpcEndpoint` – Modify a VPC endpoint.
+ `aoss:DeleteVpcEndpoint` – Delete a VPC endpoint.
In addition, you need the following Amazon EC2 and Route 53 permissions in order to create a VPC endpoint.
+ `ec2:CreateTags`
+ `ec2:CreateVpcEndpoint`
+ `ec2:DeleteVpcEndPoints`
+ `ec2:DescribeSecurityGroups`
+ `ec2:DescribeSubnets`
+ `ec2:DescribeVpcEndpoints`
+ `ec2:DescribeVpcs`
+ `ec2:ModifyVpcEndPoint`
+ `route53:AssociateVPCWithHostedZone`
+ `route53:ChangeResourceRecordSets`
+ `route53:CreateHostedZone`
+ `route53:DeleteHostedZone`
+ `route53:GetChange`
+ `route53:GetHostedZone`
+ `route53:ListHostedZonesByName`
+ `route53:ListHostedZonesByVPC`
+ `route53:ListResourceRecordSets`
## Create an interface endpoint for OpenSearch Serverless
You can create an interface endpoint for OpenSearch Serverless using either the console or the OpenSearch Serverless API.
**To create an interface endpoint for an OpenSearch Serverless collection**
1. Open 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, expand **Serverless** and choose **VPC endpoints**.
1. Choose **Create VPC endpoint**.
1. Provide a name for the endpoint.
1. For **VPC**, select the VPC that you'll access OpenSearch Serverless from.
1. For **Subnets**, select one subnet that you'll access OpenSearch Serverless from.
+ Endpoint's IP address and DNS type is based on subnet type
+ Dualstack: 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 the security groups to associate with the endpoint network interfaces. This is a critical step where you limit the ports, protocols, and sources for inbound traffic that you're authorizing into your endpoint. Make sure that the security group rules allow the resources that will use the VPC endpoint to communicate with OpenSearch Serverless to communicate with the endpoint network interface.
1. Choose **Create endpoint**.
To create a VPC endpoint using the OpenSearch Serverless API, use the `CreateVpcEndpoint` command.
**Note**
After you create an endpoint, note its ID (for example, `vpce-abc123def4EXAMPLE`. In order to provide the endpoint access to your collections, you must include this ID in one or more network access policies.
After you create an interface endpoint, you must provide it access to collections through network access policies. For more information, see [Network access for Amazon OpenSearch Serverless](serverless-network.md).
## Shared VPC setup for Amazon OpenSearch Serverless
You can use Amazon Virtual Private Cloud (VPC) to share VPC subnets with other AWS accounts in your organization, as well as share networking infrastructure such as a VPN between resources in multiple AWS accounts.
Currently, Amazon OpenSearch Serverless doesn't support creating an AWS PrivateLink connection into a shared VPC unless you are an owner of that VPC. AWS PrivateLink also doesn't support sharing connections between AWS accounts.
However, based on the flexible and modular architecture of OpenSearch Serverless, you can still set up a shared VPC. This is because the OpenSearch Serverless networking infrastructure is separate from that of the individual collection (OpenSearch Service) infrastructure. You can therefore create an AWS PrivateLink VPCe endpoint for one account where a VPC located, and then use a VPCe ID in the network policy of other accounts to restrict traffic to come only from that shared VPC.
The following procedures refer to an *owner account* and a *consumer account*.
An owner account acts as a common networking account where you set up a VPC and share it with other accounts. Consumer accounts are those accounts that create and maintain their OpenSearch Serverless collections in the VPC shared with them by the owner account.
**Prerequisites**
Ensure the following requirements are met before setting up the shared VPC:
+ The intended owner account must have already set up a VPC, subnets, route table, and other required resources in Amazon Virtual Private Cloud. For more information, see the *[Amazon VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide/)*.
+ The intended owner account and consumer accounts must belong to the same organization in AWS Organizations. For more information, see the *[AWS Organizations User Guide](https://docs.aws.amazon.com/organizations/latest/userguide/)*.
**To set up a shared VPC in an owner account/common networking account.**
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. Follow the steps in [Create an interface endpoint for OpenSearch Serverless](#serverless-vpc-create). As you do, make the following selections:
+ Select a VPC and subnets that are shared with the consumer accounts in your organization.
1. After you create the endpoint, make a note of the VPCe ID that is generated and provide it to the administrators who are to perform the setup task in consumer accounts.
VPCe IDs are in the format `vpce-abc123def4EXAMPLE`.
**To set up a shared VPC in a consumer account**
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. Use the information in [Managing Amazon OpenSearch Serverless collections](serverless-manage.md) to create a collection, if you don't have one already.
1. Use the information in [Creating network policies (console)](serverless-network.md#serverless-network-console) to create a network policy. As you do, make the following selections.
**Note**
You can also update an existing network policy for this purpose.
1. For **Access type**, select **VPC (recommended)**.
1. For **VPC endpoints for access**, choose the VPCe ID provided to you by the owner account, in the format `vpce-abc123def4EXAMPLE`.
1. In the **Resource type** area, do the following:
+ Select the **Enable access to OpenSearch endpoint** box, and then select the collection name or collection pattern to use to enable access from that shared VPC.
+ Select the **Enable access to OpenSearch Dashboard** box, and then select the collection name or collection pattern to use to enable access from that shared VPC.
1. For a new policy, choose **Create**. For an existing policy, choose **Update**.
# Control plane access through AWS PrivateLink
Amazon OpenSearch Serverless supports two types of AWS PrivateLink connections for control plane and data plane operations. Control plane operations include the creation and deletion of collections and the management of access policies. Data plane operations are for indexing and querying data within a collection. This page covers the control plane AWS PrivateLink endpoint. For information about data plane VPC endpoints, see [Data plane access through AWS PrivateLink](serverless-vpc.md).
## Creating a control plane AWS PrivateLink endpoint
You can improve the security posture of your VPC by configuring OpenSearch Serverless to use an interface VPC endpoint. Interface endpoints are powered by AWS PrivateLink. This technology enables you to privately access OpenSearch Serverless APIs without an internet gateway, NAT device, VPN connection, or AWS Direct Connect connection.
For more information about AWS PrivateLink and VPC endpoints, see [VPC endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html#concepts-vpc-endpoints) in the Amazon VPC User Guide.
### Considerations
+ VPC endpoints are supported within the same Region only.
+ VPC endpoints only support Amazon-provided DNS through Amazon Route 53.
+ VPC endpoints support endpoint policies to control access to OpenSearch Serverless Collections, Policies and VpcEndpoints.
+ OpenSearch Serverless supports interface endpoints only. Gateway endpoints are not supported.
### Creating the VPC endpoint
To create the control plane VPC endpoint for Amazon OpenSearch Serverless, use the [Access an AWS service using an interface VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint) procedure in the *Amazon VPC Developer Guide*. Create the following endpoint:
+ `com.amazonaws.region.aoss`
**To create a control plane VPC endpoint using the console**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the navigation pane, choose **Endpoints**.
1. Choose **Create Endpoint**.
1. For **Service category**, choose **AWS services**.
1. For **Services**, choose `com.amazonaws.region.aoss`. For example, `com.amazonaws.us-east-1.aoss`.
1. For **VPC**, choose the VPC in which to create the endpoint.
1. For **Subnets**, choose the subnets (Availability Zones) in which to create the endpoint network interfaces.
1. For **Security groups**, choose the security groups to associate with the endpoint network interfaces. Ensure HTTPS (port 443) is allowed.
1. For **Policy**, choose **Full access** to allow all operations, or choose **Custom** to attach a custom policy.
1. Choose **Create endpoint**.
### Creating an endpoint policy
You can attach an endpoint policy to your VPC endpoint that controls access to Amazon OpenSearch Serverless. The policy specifies the following information:
+ The principal that can perform actions.
+ The actions that can be performed.
+ The resources on which actions can be performed.
For more information, see [Controlling access to services with VPC endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html) in the *Amazon VPC User Guide*.
**Example VPC endpoint policy for OpenSearch Serverless**
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": [
"aoss:ListCollections",
"aoss:BatchGetCollection"
],
"Resource": "*"
}
]
}
```
**Example Restrictive policy allowing only list operations**
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "aoss:ListCollections",
"Resource": "*"
}
]
}
```
# SAML authentication for Amazon OpenSearch Serverless
With SAML authentication for Amazon OpenSearch Serverless, you can use your existing identity provider to offer single sign-on (SSO) for the OpenSearch Dashboards endpoints of serverless collections.
SAML authentication lets you use third-party identity providers to sign in to OpenSearch Dashboards to index and search data. OpenSearch Serverless supports providers that use the SAML 2.0 standard, such as IAM Identity Center, Okta, Keycloak, Active Directory Federation Services (AD FS), and Auth0. You can configure IAM Identity Center to synchronize users and groups from other identity sources like Okta, OneLogin, and Microsoft Entra ID. For a list of identity sources supported by IAM Identity Center and steps to configure them, see [Getting started tutorials](https://docs.aws.amazon.com/singlesignon/latest/userguide/tutorials.html) in the *IAM Identity Center User Guide*.
**Note**
SAML authentication is only for accessing OpenSearch Dashboards through a web browser. Authenticated users can only make requests to the OpenSearch API operations through **Dev Tools** in OpenSearch Dashboards. Your SAML credentials do *not* let you make direct HTTP requests to the OpenSearch API operations.
To set up SAML authentication, you first configure a SAML identity provider (IdP). You then include one or more users from that IdP in a [data access policy](serverless-data-access.md). This policy grants it certain permissions to collections and/or indexes. A user can then sign in to OpenSearch Dashboards and perform the actions that are allowed in the data access policy.
![\[SAML authentication flow with data access policy, OpenSearch interface, and JSON configuration.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/serverless-saml-flow.png)
**Topics**
+ [Considerations](#serverless-saml-considerations)
+ [Permissions required](#serverless-saml-permissions)
+ [Creating SAML providers (console)](#serverless-saml-creating)
+ [Accessing OpenSearch Dashboards](#serverless-saml-dashboards)
+ [Granting SAML identities access to collection data](#serverless-saml-policies)
+ [Creating SAML providers (AWS CLI)](#serverless-saml-creating-api)
+ [Viewing SAML providers](#serverless-saml-viewing)
+ [Updating SAML providers](#serverless-saml-updating)
+ [Deleting SAML providers](#serverless-saml-deleting)
## Considerations
Consider the following when configuring SAML authentication:
+ Signed and encrypted requests are not supported.
+ Encrypted assertions are not supported.
+ IdP-initiated authentication and sign-out are not supported.
+ Service Control Policies (SCP) will not be applicable or evaluated in the case of non-IAM identities (like SAML in Amazon OpenSearch Serverless & SAML and basic internal user authorization for Amazon OpenSearch Service).
## Permissions required
SAML authentication for OpenSearch Serverless uses the following AWS Identity and Access Management (IAM) permissions:
+ `aoss:CreateSecurityConfig` – Create a SAML provider.
+ `aoss:ListSecurityConfig` – List all SAML providers in the current account.
+ `aoss:GetSecurityConfig` – View SAML provider information.
+ `aoss:UpdateSecurityConfig` – Modify a given SAML provider configuration, including the XML metadata.
+ `aoss:DeleteSecurityConfig` – Delete a SAML provider.
The following identity-based access policy allows a user to manage all IdP configurations:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"aoss:CreateSecurityConfig",
"aoss:DeleteSecurityConfig",
"aoss:GetSecurityConfig",
"aoss:UpdateSecurityConfig",
"aoss:ListSecurityConfigs"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
Note that the `Resource` element must be a wildcard.
## Creating SAML providers (console)
These steps explain how to create SAML providers. This enables SAML authentication with service provider (SP)-initiated authentication for OpenSearch Dashboards. IdP-initiated authentication is not supported.
**To enable SAML authentication for OpenSearch Dashboards**
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. On the left navigation panel, expand **Serverless** and choose **SAML authentication**.
1. Choose **Add SAML provider**.
1. Provide a name and description for the provider.
**Note**
The name that you specify is publicly accessible and will appear in a dropdown menu when users sign in to OpenSearch Dashboards. Make sure that the name is easily recognizable and doesn't reveal sensitive information about your identity provider.
1. Under **Configure your IdP**, copy the assertion consumer service (ACS) URL.
1. Use the ACS URL that you just copied to configure your identity provider. Terminology and steps vary by provider. Consult your provider's documentation.
In Okta, for example, you create a "SAML 2.0 web application" and specify the ACS URL as the **Single Sign On URL**, **Recipient URL**, and **Destination URL**. For Auth0, you specify it in **Allowed Callback URLs**.
1. Provide the audience restriction if your IdP has a field for it. The audience restriction is a value within the SAML assertion that specifies who the assertion is intended for. With OpenSearch Serverless, you can do the following. Make sure to replace the *content* in the following code example with your own AWS account ID:
1. Use the default audience restriction `:opensearch:111122223333`.
1. (Optional) configure a custom audience restriction using the AWS CLI. For more information, see [Creating SAML providers (AWS CLI)](#serverless-saml-creating-api).
The name of the audience restriction field varies by provider. For Okta it's **Audience URI (SP Entity ID)**. For IAM Identity Center it's **Application SAML audience**.
1. If you're using IAM Identity Center, you also need to specify the following [attribute mapping](https://docs.aws.amazon.com/singlesignon/latest/userguide/attributemappingsconcept.html): `Subject=${user:name}`, with a format of `unspecified`.
1. After you configure your identity provider, it generates an IdP metadata file. This XML file contains information about the provider, such as a TLS certificate, single sign-on endpoints, and the identity provider's entity ID.
Copy the text in the IdP metadata file and paste it under **Provide metadata from your IdP** field. Alternately, choose **Import from XML file** and upload the file. The metadata file should look something like this:
```
tls-certificate
s
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
```
1. Keep the **Custom user ID attribute** field empty to use the `NameID` element of the SAML assertion for the username. If your assertion doesn't use this standard element and instead includes the username as a custom attribute, specify that attribute here. Attributes are case-sensitive. Only a single user attribute is supported.
The following example shows an override attribute for `NameID` in the SAML assertion:
```
annie
```
1. (Optional) Specify a custom attribute in the **Group attribute** field, such as `role` or `group`. Only a single group attribute is supported. There's no default group attribute. If you don't specify one, your data access policies can only contain user principals.
The following example shows a group attribute in the SAML assertion:
```
finance
```
1. By default, OpenSearch Dashboards signs users out after 24 hours. You can configure this value to any number between 1 and 12 hours (15 and 720 minutes) by specifying the **OpenSearch Dashboards timeout**. If you try to set the timeout equal to or less than 15 minutes, your session will be reset to one hour.
1. Choose **Create SAML provider**.
## Accessing OpenSearch Dashboards
After you configure a SAML provider, all users and groups associated with that provider can navigate to the OpenSearch Dashboards endpoint. The Dashboards URL has the format `collection-endpoint/_dashboards/` *for all collections*.
If you have SAML enabled, selecting the link in the AWS Management Console directs you to the IdP selection page, where you can sign in using your SAML credentials. First, use the dropdown to select an identity provider:
![\[OpenSearch login page with dropdown menu for selecting SAML Identity Provider options.\]](http://docs.aws.amazon.com/opensearch-service/latest/developerguide/images/idpList.png)
Then sign in using your IdP credentials.
If you don't have SAML enabled, selecting the link in the AWS Management Console directs you to log in as an IAM user or role, with no option for SAML.
## Granting SAML identities access to collection data
After you create a SAML provider, you still need to grant the underlying users and groups access to the data within your collections. You grant access through [data access policies](serverless-data-access.md). Until you provide users access, they won't be able to read, write, or delete any data within your collections.
To grant access, create a data access policy and specify your SAML user and/or group IDs in the `Principal` statement:
```
[
{
"Rules":[
...
],
"Principal":[
"saml/987654321098/myprovider/user/Shaheen",
"saml/987654321098/myprovider/group/finance"
]
}
]
```
You can grant access to collections, indexes, or both. If you want different users to have different permissions, create multiple rules. For a list of available permissions, see [Supported policy permissions](serverless-data-access.md#serverless-data-supported-permissions). For information about how to format an access policy, see [Policy syntax](serverless-data-access.md).
## Creating SAML providers (AWS CLI)
To create a SAML provider using the OpenSearch Serverless API, send a [CreateSecurityConfig](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_CreateSecurityConfig.html) request:
```
aws opensearchserverless create-security-config \
--name myprovider \
--type saml \
--saml-options file://saml-auth0.json
```
Specify `saml-options`, including the metadata XML, as a key-value map within a .json file. The metadata XML must be encoded as a [JSON escaped string](https://www.freeformatter.com/json-escape.html).
```
{
"sessionTimeout": 70,
"groupAttribute": "department",
"userAttribute": "userid",
"openSearchServerlessEntityId": "aws:opensearch:111122223333:app1",
"metadata": "EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" ... ... ... IDPSSODescriptor\r\n\/EntityDescriptor"
}
```
**Note**
(Optional) configure a custom audience restriction using the AWS CLI. For more information, see [Creating SAML providers (AWS CLI)](#serverless-saml-creating-api).
## Viewing SAML providers
The following [ListSecurityConfigs](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_ListSecurityConfigs.html) request lists all SAML providers in your account:
```
aws opensearchserverless list-security-configs --type saml
```
The request returns information about all existing SAML providers, including the full IdP metadata that your identity provider generates:
```
{
"securityConfigDetails": [
{
"configVersion": "MTY2NDA1MjY4NDQ5M18x",
"createdDate": 1664054180858,
"description": "Example SAML provider",
"id": "saml/111122223333/myprovider",
"lastModifiedDate": 1664054180858,
"samlOptions": {
"groupAttribute": "department",
"metadata": "EntityDescriptorxmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" ...... ...IDPSSODescriptor\r\n/EntityDescriptor",
"sessionTimeout": 120,
"openSearchServerlessEntityId": "aws:opensearch:111122223333:app1",
"userAttribute": "userid"
}
}
]
}
```
To view details about a specific provider, including the `configVersion` for future updates, send a `GetSecurityConfig` request.
## Updating SAML providers
To update a SAML provider using the OpenSearch Serverless console, choose **SAML authentication**, select your identity provider, and choose **Edit**. You can modify all fields, including the metadata and custom attributes.
To update a provider through the OpenSearch Serverless API, send an [UpdateSecurityConfig](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_UpdateSecurityConfig.html) request and include the identifier of the policy to be updated. You must also include a configuration version, which you can retrieve using the `ListSecurityConfigs` or `GetSecurityConfig` commands. Including the most recent version ensures that you don't inadvertently override a change made by someone else.
The following request updates the SAML options for a provider:
```
aws opensearchserverless update-security-config \
--id saml/123456789012/myprovider \
--type saml \
--saml-options file://saml-auth0.json \
--config-version MTY2NDA1MjY4NDQ5M18x
```
Specify your SAML configuration options as a key-value map within a .json file.
**Important**
**Updates to SAML options are *not* incremental**. If you don't specify a value for a parameter in the `SAMLOptions` object when you make an update, the existing values will be overridden with empty values. For example, if the current configuration contains a value for `userAttribute`, and then you make an update and don't include this value, the value is removed from the configuration. Make sure you know what the existing values are before you make an update by calling the `GetSecurityConfig` operation.
## Deleting SAML providers
When you delete a SAML provider, any references to associated users and groups in your data access policies are no longer functional. To avoid confusion, we suggest that you remove all references to the endpoint in your access policies before you delete the endpoint.
To delete a SAML provider using the OpenSearch Serverless console, choose **Authentication**, select the provider, and choose **Delete**.
To delete a provider through the OpenSearch Serverless API, send a [DeleteSecurityConfig](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_DeleteSecurityConfig.html) request:
```
aws opensearchserverless delete-security-config --id saml/123456789012/myprovider
```
# Compliance validation for Amazon OpenSearch Serverless
Third-party auditors assess the security and compliance of Amazon OpenSearch Serverless as part of multiple AWS compliance programs. These programs include SOC, PCI, and HIPAA.
To learn whether an AWS service is within the scope of specific compliance programs, see [AWS services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/) and choose the compliance program that you are interested in. For general information, see [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/).
You can download third-party audit reports using AWS Artifact. For more information, see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html).
Your compliance responsibility when using AWS services is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations. For more information about your compliance responsibility when using AWS services, see [AWS Security Documentation](https://docs.aws.amazon.com/security/).