Common elements in an auth policy Resource format for auth policies Condition keys that can be used in auth policies Anonymous (unauthenticated) principals Example auth policies How authorization works

Control access to VPC Lattice services using auth policies

VPC Lattice auth policies are IAM policy documents that you attach to service networks or services to control whether a specified principal has access to a group of services or specific service. You can attach one auth policy to each service network or service that you want to control access to.

Auth policies are different from IAM identity-based policies. IAM identity-based policies are attached to IAM users, groups, or roles and define what actions those identities can do on which resources. Auth policies are attached to services and service networks. For authorization to succeed, both auth policies and identity-based policies need to have explicit allow statements. For more information, see How authorization works.

You can use the AWS CLI and console to view, add, update, or remove auth policies on services and service networks. When using the AWS CLI, remember that your commands run in the AWS Region configured for your profile. If you want to run the commands in a different Region, either change the default Region for your profile, or use the --region parameter with the command.

Common elements in an auth policy
Resource format for auth policies
Condition keys that can be used in auth policies
Anonymous (unauthenticated) principals
Example auth policies
How authorization works

To get started with auth policies, follow the procedure to create an auth policy that applies to a service network. For more restrictive permissions that you don't want applied to other services, you can optionally set auth policies on individual services.

The following AWS CLI tasks show you how to manage access to a service network using auth policies. For instructions that use the console, see Service networks in VPC Lattice.

Tasks

Add an auth policy to a service network
Change a service network's auth type
Remove an auth policy from a service network

Add an auth policy to a service network

Follow the steps in this section to use the AWS CLI to:

Enable access control on a service network using IAM.
Add an auth policy to the service network. If you do not add an auth policy, all traffic will get an access denied error.

To enable access control and add an auth policy to a new service network

To enable access control on a service network so that it can use an auth policy, use the create-service-network command with the --auth-type option and a value of AWS_IAM.
```
aws vpc-lattice create-service-network --name Name --auth-type AWS_IAM [--tags TagSpecification]
```
If successful, the command returns output similar to the following.
```
{
   "arn": "arn",
   "authType": "AWS_IAM",
   "id": "sn-0123456789abcdef0",
   "name": "Name"
}
```
Use the put-auth-policy command, specifying the ID of the service network where you want to add the auth policy and the auth policy you want to add.

For example, use the following command to create an auth policy for the service network with the ID sn-0123456789abcdef0.
```
aws vpc-lattice put-auth-policy --resource-identifier sn-0123456789abcdef0 --policy file://policy.json
```
Use JSON to create a policy definition. For more information, see Common elements in an auth policy.

If successful, the command returns output similar to the following.
```
{
   "policy": "policy",
   "state": "Active"
}
```

To enable access control and add an auth policy to an existing service network

To enable access control on a service network so that it can use an auth policy, use the update-service-network command with the --auth-type option and a value of AWS_IAM.
```
aws vpc-lattice update-service-network --service-network-identifier sn-0123456789abcdef0 --auth-type AWS_IAM
```
If successful, the command returns output similar to the following.
```
{
   "arn": "arn",
   "authType": "AWS_IAM",
   "id": "sn-0123456789abcdef0",
   "name": "Name"
}
```
Use the put-auth-policy command, specifying the ID of the service network where you want to add the auth policy and the auth policy you want to add.
```
aws vpc-lattice put-auth-policy --resource-identifier sn-0123456789abcdef0 --policy file://policy.json
```
Use JSON to create a policy definition. For more information, see Common elements in an auth policy.

If successful, the command returns output similar to the following.
```
{
   "policy": "policy",
   "state": "Active"
}
```

Change a service network's auth type

To disable the auth policy for a service network

Use the update-service-network command with the --auth-type option and a value of NONE.


aws vpc-lattice update-service-network --service-network-identifier sn-0123456789abcdef0 --auth-type NONE

If you need to enable the auth policy again later, run this command with AWS_IAM specified for the --auth-type option.

Remove an auth policy from a service network

To remove an auth policy from a service network

Use the delete-auth-policy command.


aws vpc-lattice delete-auth-policy --resource-identifier sn-0123456789abcdef0

The request fails if you remove an auth policy before changing the auth type of a service network to NONE.

The following AWS CLI tasks show you how to manage access to a service using auth policies. For instructions that use the console, see Services in VPC Lattice.

Add an auth policy to a service

Follow these steps to use the AWS CLI to:

Enable access control on a service using IAM.
Add an auth policy to the service. If you do not add an auth policy, all traffic will get an access denied error.

To enable access control and add an auth policy to a new service

To enable access control on a service so that it can use an auth policy, use the create-service command with the --auth-type option and a value of AWS_IAM.
```
aws vpc-lattice create-service --name Name --auth-type AWS_IAM [--tags TagSpecification]
```
If successful, the command returns output similar to the following.
```
{
   "arn": "arn",
   "authType": "AWS_IAM",
   "dnsEntry": { 
      ...
   },
   "id": "svc-0123456789abcdef0",
   "name": "Name",
   "status": "CREATE_IN_PROGRESS"
}
```
Use the put-auth-policy command, specifying the ID of the service where you want to add the auth policy and the auth policy you want to add.

For example, use the following command to create an auth policy for the service with the ID svc-0123456789abcdef0.
```
aws vpc-lattice put-auth-policy --resource-identifier svc-0123456789abcdef0 --policy file://policy.json
```
Use JSON to create a policy definition. For more information, see Common elements in an auth policy.

If successful, the command returns output similar to the following.
```
{
   "policy": "policy",
   "state": "Active"
}
```

To enable access control and add an auth policy to an existing service

To enable access control on a service so that it can use an auth policy, use the update-service command with the --auth-type option and a value of AWS_IAM.
```
aws vpc-lattice update-service --service-identifier svc-0123456789abcdef0 --auth-type AWS_IAM
```
If successful, the command returns output similar to the following.
```
{
   "arn": "arn",
   "authType": "AWS_IAM",
   "id": "svc-0123456789abcdef0",
   "name": "Name"
}
```
Use the put-auth-policy command, specifying the ID of the service where you want to add the auth policy and the auth policy you want to add.
```
aws vpc-lattice put-auth-policy --resource-identifier svc-0123456789abcdef0 --policy file://policy.json
```
Use JSON to create a policy definition. For more information, see Common elements in an auth policy.

If successful, the command returns output similar to the following.
```
{
   "policy": "policy",
   "state": "Active"
}
```

Change a service's auth type

To disable the auth policy for a service

Use the update-service command with the --auth-type option and a value of NONE.


aws vpc-lattice update-service --service-identifier svc-0123456789abcdef0 --auth-type NONE

If you need to enable the auth policy again later, run this command with AWS_IAM specified for the --auth-type option.

Remove an auth policy from a service

To remove an auth policy from a service

Use the delete-auth-policy command.


aws vpc-lattice delete-auth-policy --resource-identifier svc-0123456789abcdef0

The request fails if you remove an auth policy before changing the auth type of the service to NONE.

If you enable auth policies that require authenticated requests to a service, any requests to that service must contain a valid request signature that is computed using Signature Version 4 (SigV4). For more information, see SIGv4 authenticated requests for Amazon VPC Lattice.

Common elements in an auth policy

VPC Lattice auth policies are specified using the same syntax as IAM policies. For more information, see Identity-based policies and resource-based policies in the IAM User Guide.

An auth policy contains the following elements:

Principal – The person or application who is allowed access to the actions and resources in the statement. In an auth policy, the principal is the IAM entity who is the recipient of this permission. The principal is authenticated as an IAM entity to make requests to a specific resource, or group of resources as in the case of services in a service network.

You must specify a principal in a resource-based policy. Principals can include accounts, users, roles, federated users, or AWS services. For more information, see AWS JSON policy elements: Principal in the IAM User Guide.
Effect – The effect when the specified principal requests the specific action. This can be either Allow or Deny. By default, when you enable access control on a service or service network using IAM, principals have no permissions to make requests to the service or service network.
Actions – The specific API action for which you are granting or denying permission. VPC Lattice supports actions that use the vpc-lattice-svcs prefix. For more information, see Actions defined by Amazon VPC Lattice Services in the Service Authorization Reference.
Resources – The services that are affected by the action.
Condition – Conditions are optional. You can use them to control when your policy is in effect. For more information, see Condition keys for Amazon VPC Lattice Services in the Service Authorization Reference.

As you create and manage auth policies, you might want to use the IAM Policy Generator.

Requirement

The policy in JSON must not contain newlines or blank lines.

Resource format for auth policies

You can restrict access to specific resources by creating an auth policy that uses a matching schema with a <serviceARN>/<path> pattern and code the Resource element as shown in the following examples.

Resource examples for auth policies
Protocol	Examples
HTTP	`"Resource": "arn:aws:vpc-lattice:us-west-2:1234567890:service/svc-0123456789abcdef0/rates"` `"Resource": "/rates"` `"Resource": "/*"`
gRPC	`"Resource": "arn:aws:vpc-lattice:us-west-2:1234567890:service/svc-0123456789abcdef0/api.parking/GetRates"` `"Resource": "arn:aws:vpc-lattice:us-west-2:1234567890:service/svc-0123456789abcdef0/api.parking/"` `"Resource": "arn:aws:vpc-lattice:us-west-2:1234567890:service/svc-0123456789abcdef0/"`

Use the following Amazon Resource Name (ARN) resource format for <serviceARN>:


arn:aws:vpc-lattice:region:account-id:service/service-id

For example:


"Resource": "arn:aws:vpc-lattice:us-west-2:123456789012:service/svc-0123456789abcdef0"

Condition keys that can be used in auth policies

Access can be further controlled by condition keys in the Condition element of auth policies. These condition keys are present for evaluation depending on the protocol and whether the request is signed with Signature Version 4 (SigV4) or anonymous. Condition keys are case sensitive.

AWS provides global condition keys that you can use to control access, such as aws:PrincipalOrgID and aws:SourceIp. To see a list of the AWS global condition keys, see AWS global condition context keys in the IAM User Guide.

The following tale lists the VPC Lattice condition keys. For more information, see Condition keys for Amazon VPC Lattice Services in the Service Authorization Reference.

Condition keys for auth policies
Condition keys	Description	Example	Available for anonymous (unauthenticated) caller?	Available for gRPC?
`vpc-lattice-svcs:Port`	Filters access by the service port the request is made to	80	Yes	Yes
`vpc-lattice-svcs:RequestMethod`	Filters access by the method of the request	GET	Yes	Always POST
`vpc-lattice-svcs:RequestHeader/header-name: value`	Filters access by a header name-value pair in the request headers	content-type: application/json	Yes	Yes
`vpc-lattice-svcs:RequestQueryString/key-name: value`	Filters access by the query string key-value pairs in the request URL	quux: [corge, grault]	Yes	No
`vpc-lattice-svcs:ServiceNetworkArn`	Filters access by the ARN of the service network of the service that is receiving the request	arn:aws:vpc-lattice:us-west-2:123456789012:servicenetwork/sn-0123456789abcdef0	Yes	Yes
`vpc-lattice-svcs:ServiceArn`	Filters access by the ARN of the service that is receiving the request	arn:aws:vpc-lattice:us-west-2:123456789012:service/svc-0123456789abcdef0	Yes	Yes
`vpc-lattice-svcs:SourceVpc`	Filters access by the VPC the request is made from	vpc-1a2b3c4d	Yes	Yes
`vpc-lattice-svcs:SourceVpcOwnerAccount`	Filters access by the owning account of the VPC the request is made from	123456789012	Yes	Yes

Anonymous (unauthenticated) principals

Anonymous principals are callers that don't sign their AWS requests with Signature Version 4 (SigV4), and are within a VPC that is connected to the service network. Anonymous principals can make unauthenticated requests to services in the service network if an auth policy allows it.

Example auth policies

The following are example auth policies that require requests to be made by authenticated principals.

All examples use the us-west-2 Region and contain fictitious account IDs.

Example 1: Restrict access to services by a specific AWS organization

The following auth policy example grants permissions to any authenticated request to access any services in the service network to which the policy applies. However, the request must originate from principals that belong to the AWS organization specified in the condition.


{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Principal": "*",
         "Action": "vpc-lattice-svcs:Invoke",
         "Resource": "*",
         "Condition": {
            "StringEquals": {
               "aws:PrincipalOrgID": [ 
                  "o-123456example"
               ]
            }
         }
      }
   ]
}

Example 2: Restrict access to a service by a specific IAM role

The following auth policy example grants permissions to any authenticated request that uses the IAM role rates-client to make HTTP GET requests on the service specified in the Resource element. The resource in the Resource element is the same as the service that the policy is attached to.


{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect": "Allow",
         "Principal": {
            "AWS": [
               "arn:aws:iam::123456789012:role/rates-client"
            ]
         },
         "Action": "vpc-lattice-svcs:Invoke",
         "Resource": [
            "arn:aws:vpc-lattice:us-west-2:123456789012:service/svc-0123456789abcdef0/*"
         ],
         "Condition": {
            "StringEquals": {
               "vpc-lattice-svcs:RequestMethod": "GET"
            }
         }
      }
   ]
}

Example 3: Restrict access to services by authenticated principals in a specific VPC

The following auth policy example only allows authenticated requests from principals in the VPC whose VPC ID is vpc-1a2b3c4d.


{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Principal": "*",
         "Action": "vpc-lattice-svcs:Invoke",
         "Resource": "*",
         "Condition": {
            "StringNotEquals": {
               "aws:PrincipalType": "Anonymous"
            },
            "StringEquals": {
               "vpc-lattice-svcs:SourceVpc": "vpc-1a2b3c4d"
            }
         }
      }
   ]
}

How authorization works

When a VPC Lattice service receives a request, the AWS enforcement code evaluates all relevant permissions policies together to determine whether to authorize or deny the request. It evaluates all the IAM identity-based policies and auth policies that are applicable in the request context during authorization. By default, all requests are implicitly denied when the auth type is AWS_IAM. An explicit allow from all relevant policies overrides the default.

Authorization includes:

Collecting all the relevant IAM identity-based policies and auth policies.
Evaluating the resulting set of policies:
- Verifying that the requester (such as an IAM user or role) has permissions to perform the operation from the account to which the requester belongs. If there is no explicit allow statement, AWS does not authorize the request.
- Verifying that the request is allowed by the auth policy for the service network. If an auth policy is enabled, but there is no explicit allow statement, AWS does not authorize the request. If there is an explicit allow statement, or the auth type is NONE, the code continues.
- Verifying that the request is allowed by the auth policy for the service. If an auth policy is enabled, but there is no explicit allow statement, AWS does not authorize the request. If there is an explicit allow statement,or the auth type is NONE, then the enforcement code returns a final decision of Allow.
- An explicit deny in any policy overrides any allows.

The diagram shows the authorization workflow. When a request is made, the relevant policies allow or deny the request access to a given service.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Manage access to services

Security groups

Control access to VPC Lattice services using auth policies

Contents

Tasks

Add an auth policy to a service network

To enable access control and add an auth policy to a new service network

To enable access control and add an auth policy to an existing service network

Change a service network's auth type

To disable the auth policy for a service network

Remove an auth policy from a service network

To remove an auth policy from a service network

Tasks

Add an auth policy to a service

To enable access control and add an auth policy to a new service

To enable access control and add an auth policy to an existing service

Change a service's auth type

To disable the auth policy for a service

Remove an auth policy from a service

To remove an auth policy from a service

Common elements in an auth policy

Requirement

Resource format for auth policies

Condition keys that can be used in auth policies

Anonymous (unauthenticated) principals

Example auth policies

Example 1: Restrict access to services by a specific AWS organization

Example 2: Restrict access to a service by a specific IAM role

Example 3: Restrict access to services by authenticated principals in a specific VPC

How authorization works