Configuring Access for Amazon CloudSearch

You use AWS Identity and Access Management (IAM) access policies to control access to the Amazon CloudSearch configuration service and each search domain's document, search, and suggest services. An IAM access policy is a JSON document that explicitly lists permissions that define what actions people or processes are allowed to perform. For an introduction to IAM access policies, see Overview of AWS IAM Policies.

You control access to the Amazon CloudSearch configuration service APIs and the domain services APIs independently. For example, you might choose to restrict who can modify the configuration of your production domain, but allow team members to create and manage their own domains for development and testing. Similarly, you might configure your development and test domains to accept anonymous requests to the upload, search, and suggest services, but lock down your production domain so that it accepts only authenticated requests from your application.

When AWS receives a request, it authenticates that the request is from a known AWS user, and then checks relevant policies to determine whether the user is authorized to perform the requested actions using the requested resources. If a user has not been explicitly granted permission to perform an action, the request is denied. During policy evaluation, if AWS encounters an explicit deny, the deny effect takes precedence over any explicit allow effects that are in force.

Writing Access Policies for Amazon CloudSearch

Amazon CloudSearch supports both user-based policies and resource-based policies:

In general, we recommend managing access to Amazon CloudSearch APIs by configuring user-based policies. This enables you to manage all of your permissions in one place and any changes you need to make take effect almost immediately. However, to allow public access to a domain's search service or restrict access based on IP addresses, you must configure a resource-based policy for the domain. (We recommend replacing your old IP based access policies with user-based policies at your earliest convenience.) You can also use resource-based policies to easily allow other accounts to access a domain. Keep in mind that processing changes to a domain's resource-based policies takes significantly longer than applying changes to user-based policies.

The IAM console can help you write both user-based and resource-based policies for Amazon CloudSearch. For more information, see Managing IAM Policies.

Contents of an Access Policy for Amazon CloudSearch

You specify the following information in your access policies for Amazon CloudSearch:

For examples of access policies for Amazon CloudSearch, see Amazon CloudSearch Policy Examples.

Amazon CloudSearch ARNs

A policy's Amazon Resource Name (ARN) uniquely specifies the domain that the policy applies to. The ARN is a standard format that AWS uses to identify resources. The 12-digit number in the ARN is your AWS account ID. Amazon CloudSearch ARNs are of the form arn:aws:cloudsearch:REGION:ACCOUNT-ID:domain/DOMAIN-NAME.

The following list describes the variable elements in the ARN:

For example, the following ARN identifies the movies domain in the us-east-1 region owned by account 111122223333:

arn:aws:cloudsearch:us-east-1:111122223333:domain/movies

The following example shows how the ARN is used to specify the resource in a user-based policy.

{
  "Version":"2012-10-17",           
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["cloudsearch:search"],
      "Resource": "arn:aws:cloudsearch:us-east-1:111122223333:domain/movies"
    }
  ]
}

A domain's ARN is displayed on the domain dashboard in the Amazon CloudSearch console and is also available by calling DescribeDomains.

Amazon CloudSearch Actions

The actions you specify control which Amazon CloudSearch APIs the statement applies to. All Amazon CloudSearch actions are prefixed with cloudsearch:, such as cloudsearch:search. The following list shows the supported actions:

Amazon CloudSearch Policy Examples

This section presents a few examples of Amazon CloudSearch access policies.

Granting Read-only Access to the Amazon CloudSearch Configuration Service

You can grant read-only access to the configuration service by allowing only the following actions. This might be useful if you want to allow users to view the configuration of a production domain without being able to make changes.

The following user-based policy grants read-only access to the configuration service for a movies domain owned by the account 555555555555. The policy uses wildcards for the actions, since it grants access to all actions that begin with Describe or List. Note that this will also grant access to any describe or list actions that might be added to the API in the future.

{
  "Version":"2012-10-17",           
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["cloudsearch:Describe*", 
                 "cloudsearch:List*"],
      "Resource": "arn:aws:cloudsearch:us-east-1:555555555555:domain/movies"
    }
  ]
}

Granting Access to All Amazon CloudSearch Configuration Service Actions

You can grant access to all Amazon CloudSearch configuration service actions by including an Allow statement that grants access to all configuration service actions, but not the domain services actions. This enables you to grant administrative access without authorizing a user to upload or retrieve data from a domain. One way to do this is to use a wildcard to grant access to all Amazon CloudSearch actions, and then include a deny statement that blocks access to the domain services actions. The following user-based policy grants access to the configuration service for all domains owned by the 111122223333 account in the us-west-2 region.

{
  "Version":"2012-10-17",           
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["cloudsearch:*"],
      "Resource": "arn:aws:cloudsearch:us-west-2:111122223333:domain/*"
    },
    {
      "Effect": "Deny",
      "Action": ["cloudsearch:document", 
                 "cloudsearch:search", 
                 "cloudsearch:suggest"],
      "Resource": "arn:aws:cloudsearch:us-west-2:111122223333:domain/*"
    }
  ]  
}

Granting Unrestricted Access to All Amazon CloudSearch Services

You can grant unrestricted access to all Amazon CloudSearch services, including all configuration service actions and all domain services with a user-based policy. To do this, you specify wildcards for the actions, region, and domain name. The following policy enables the user to access all Amazon CloudSearch actions for any domain in any region that's owned by the 111122223333 account.

{
  "Version":"2012-10-17",           
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["cloudsearch:*"],
      "Resource": "arn:aws:cloudsearch:*:111122223333:domain/*"
    }
  ]
}

Granting Permission to Upload Documents to an Amazon CloudSearch Domain

You can grant a user permission to upload documents to a search domain by specifying the cloudsearch:document action. For example, the following user-based policy enables the user to upload documents to the movies domain in us-east-1 owned by the 111122223333 account.

{
  "Version":"2012-10-17",           
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["cloudsearch:document"],
      "Resource": "arn:aws:cloudsearch:us-east-1:111122223333:domain/movies"
    }
  ]
}

Granting Amazon CloudSearch Access to Another AWS Account

You have two options to configure cross-account access for a CloudSearch domain:

This topic provides an example of the second option, adding a resource-based policy to the CloudSearch domain. Assume that account #1 is owned by account id 111111111111 and account #2 is owned by account id 999999999999. Account #1 wants to grant access to account #2 to use the search service for the movies domain, which requires two steps:

Granting Access to an Amazon CloudSearch Domain from Selected IP Addresses

Resource-based access policies set through the Amazon CloudSearch configuration service support anonymous access, which enables you to submit unsigned requests to a search domain's services. To allow anonymous access from selected IP addresses, use a wildcard for the Principal value and specify the allowed IP addresses as a Condition element in the policy.

If you are creating a resource-based policy that grants access to requests coming from an Amazon EC2 instance, you need to specify the instance's public IP address.

IP addresses are specified in the standard Classless Inter-Domain Routing (CIDR) format. For example 10.24.34.0/24 specifies the range 10.24.34.0 - 10.24.34.255, while 10.24.34.0/32 specifies the single IP address 10.24.34.0. For more information about CIDR notation, see RFC 4632.

For example, the following policy grants access to the search action for the movies domain owned by AWS account 111122223333 from the IP address 192.0.2.0/32.

{
  "Version":"2012-10-17",
  "Statement":[
    {
      "Sid":"search_only",
      "Effect":"Allow",
      "Principal":"*",
      "Action":["cloudsearch:search"],
      "Condition":{"IpAddress":{"aws:SourceIp":"192.0.2.0/32"}}
    }
  ]
}

Granting Public Access to an Amazon CloudSearch Domain's Search Service

If you need to allow public access to your domain's search endpoint, you can configure a resource-based policy with no conditions. This enables unsigned requests to be sent from any IP address.

For example, the following policy grants public access to the search action for the movies domain owned by AWS account 111122223333.

{
  "Version":"2012-10-17",
  "Statement":[
    {
      "Sid":"public_search",
      "Effect":"Allow",
      "Principal":"*",
      "Action":["cloudsearch:search"]
    }
  ]
}

Configuring Access for Amazon CloudSearch Using the AWS Management Console

Your domain remains in a Processing state while Amazon CloudSearch updates the access policy.

Configuring Access for Amazon CloudSearch with the AWS CLI

You can configure both user-based policies and resource-based policies for Amazon CloudSearch with the AWS CLI. For information about installing and setting up the AWS CLI, see the AWS Command Line Interface User Guide.

Updating resource-based access policies takes some time to complete. You can check the state of the policy with the aws cloudsearch describe-service-access-policies command. Once the policy has been applied, the state of the policy changes to Active.

You can retrieve your domain's policies using the aws cloudsearch describe-service-access-policies command.

Configuring Access to a Domain's Endpoints Using the AWS SDKs

The AWS SDKs (except the Android and iOS SDKs) support all of the Amazon CloudSearch actions defined in the Amazon CloudSearch Configuration API, including UpdateServiceAccessPolicies. For more information about installing and using the AWS SDKs, see AWS Software Development Kits.