Tutorial: Getting started with security in Amazon OpenSearch Serverless (CLI) - Amazon OpenSearch Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Tutorial: Getting started with security in Amazon OpenSearch Serverless (CLI)

This tutorial walks you through the steps described in the console getting started tutorial for security, but uses the Amazon CLI rather than the OpenSearch Service console.

You'll complete the following steps in this tutorial:

  1. Create an IAM permissions policy

  2. Attatch the IAM policy to an IAM role

  3. Create an encryption policy

  4. Create a network policy

  5. Create a collection

  6. Configure a data access policy

  7. Retrieve the collection endpoint

  8. Upload data to your connection

  9. 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 Amazon 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 Amazon 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" } }
  2. 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
  3. Before you create a collection, you need to create an encryption policy that assigns an Amazon 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 } }
  4. Create a network policy 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 } }
  5. 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 } }
  6. Create a data access policy 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.

  7. 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": [] }

    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.

  8. Use an HTTP tool such as Postman 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 }
  9. To begin searching data in your collection, use the search API. 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 } } ] } }