Configuring Access for Amazon CloudSearch (original) (raw)

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, seeOverview 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.

Important

To enable authentication, Amazon CloudSearch requests must be signed with an access key. The only exception is if you allow anonymous access to a domain's upload, search, or suggest services. For more information, see Signing Requests.

Topics

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 formarn: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.

Important

When specifying an ARN for a domain created with the 2011-02-01 API, you must use the former Amazon CloudSearch service name, cs. For example, arn:aws:cs:us-east-1:111122223333:domain/movies. If you need to define policies that configure access for both 2011 and 2013 domains, make sure to specify the correct ARN format for each domain. For more information, see Configuration Service Access Policies Not Working.

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 ascloudsearch:search. The following list shows the supported actions:

Amazon CloudSearch Policy Examples

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

Topics

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 anAllow 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 id111111111111 and account #2 is owned by account id999999999999. Account #1 wants to grant access to account #2 to use the search service for the movies domain, which requires two steps:

  1. Account #1 attaches a resource-based policy to the domain using the Amazon CloudSearch console that grants access to account #2.
{  
  "Version":"2012-10-17",  
  "Statement":[  
    {  
      "Sid":"search_only",  
      "Effect":"Allow",  
      "Action":["cloudsearch:search"],  
      "Principal":{"AWS":["arn:aws:iam::999999999999:root"]}  
    }  
  ]  
}
  1. Account #2 attaches a user-based managed policy to an IAM role owned by that account using the IAM console.
{  
  "Version":"2012-10-17",  
  "Statement": [  
    {  
      "Effect": "Allow",  
      "Action": ["cloudsearch:search"],  
      "Resource": "arn:aws:cloudsearch:us-east-1:111111111111:domain/movies"  
    }  
  ]  
}
Important

To configure resource-based policies for Amazon CloudSearch, you must have permission to use the cloudsearch:UpdateServiceAccessPolicies action.

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 aCondition element in the policy.

Important

Allowing anonymous access from selected IP addresses is inherently less secure than requiring user credentials to access your search domains. We recommend against allowing anonymous access even if it is permitted only from select IP addresses. If you currently allow anonymous access, you should upgrade your applications to submit signed requests and control access by configuring user-based or resource-based policies.

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 themovies 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.

Important

Allowing public access to a search domain means you have no control over the volume of requests submitted to the domain. Malicious users could flood the domain with requests, impacting legitimate users as well as your operating costs.

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

To configure user-based policies
  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
  2. Configure Amazon CloudSearch permissions by attaching a policy to a user, group, or role. For more information, see Managing Policies (AWS Management Console). For more information about user-based policies for Amazon CloudSearch see Writing Access Policies for Amazon CloudSearch.
To configure resource-based policies
  1. Sign in to the AWS Management Console and open the Amazon CloudSearch console at https://console.aws.amazon.com/cloudsearch/home.
  2. Choose the name of the domain you want to configure.
  3. On the Domain configuration tab, chooseEdit next to Access policy.
  4. When you're done making changes to the domain access policy, chooseSubmit.

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.

To configure user-based policies
To configure resource-based policies
aws cloudsearch update-service-access-policies --domain-name movies  
--access-policies "{\"Version\":\"2012-10-17\",\"Statement\":[{  
  \"Sid\":\"search_only\",  
  \"Effect\":\"Allow\",  
  \"Principal\": \"*\",  
  \"Action\":\"cloudsearch:search\",  
  \"Condition\":{\"IpAddress\":{\"aws:SourceIp\":\"192.0.2.0/32\"}}}  
]}"  
{  
  "AccessPolicies": {  
    "Status": {  
      "PendingDeletion": false,  
      "State": "Processing",  
      "CreationDate": "2014-04-30T22:07:30Z",  
      "UpdateVersion": 9,  
      "UpdateDate": "2014-04-30T22:07:30Z"  
    },  
    "Options":  
      "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"\",  
        \"Effect\":\"Allow\",\"Principal\":\"*\",  
        \"Action\":\"cloudsearch:search\",  
        \"Condition\":{\"IpAddress\":{\"aws:SourceIp\":  
        \"192.0.2.0/32\"}}}]}"  
    }  
}

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](./API%5FUpdateServiceAccessPolicies.html). For more information about installing and using the AWS SDKs, see AWS Software Development Kits.