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

Authorization with Amazon Verified Permissions

Amazon Verified Permissions is an authorization service for the applications that you build. When you add an Amazon Cognito user pool as an identity source, your app can pass user pool access or identity (ID) tokens to Verified Permissions for an allow or deny decision. Verified Permissions considers your user's properties and request context based on policies that you write in Cedar Policy Language. The request context can include an identifier for the document, image, or other resource they requested, and the action that your user wants to take on the resource.

Your app can provide your user's identity or access tokens to Verified Permissions in IsAuthorizedWithToken or BatchIsAuthorizedWithToken API requests. These API operations accept your users as a Principal and make authorization decisions for the Action on the Resource that they want to access. Additional custom Context can contribute to a detailed access decision.

When your app presents a token in an IsAuthorizedWithToken API request, Verified Permissions performs the following validations.

Revoked tokens and deleted users

Verified Permissions only validates the information it knows from your identity source and from the expiration time of your user's token. Verified Permissions doesn't check for token revocation or user existence. If you revoked your user's token or deleted your user's profile from your user pool, Verified Permissions still considers the token valid until it expires.

Policy evaluation

Configure your user pool as an identity source for your policy store. Configure your app to submit your users' tokens in requests to Verified Permissions. For each request, Verified Permissions compares the claims in the token to a policy. A Verified Permissions policy is like an IAM policy in Amazon. It declares a principal, resource, and action. Verified Permissions responds to your request with Allow if it matches an allowed action and doesn't match an explicit Deny action; otherwise, it responds with Deny. For more information, see Amazon Verified Permissions policies in the Amazon Verified Permissions User Guide.

Customizing tokens

To change, add, and remove the user claims that you want to present to Verified Permissions, customize the content in your access and identity tokens with a Pre token generation Lambda trigger. With a pre token generation trigger, you can add and modify claims in your tokens. For example, you can query a database for additional user attributes and encode them into your ID token.

For more information about how Verified Permissions maps claims in Amazon Cognito tokens to authorization policies, see Mapping Amazon Cognito tokens to Verified Permissions schema.

API authorization with Verified Permissions

Your ID or access tokens can authorize requests to back-end Amazon API Gateway REST APIs with Verified Permissions. You can create a policy store with immediate links to your user pool and API. With the Set up with Cognito and API Gateway starting option, Verified Permissions adds a user pool identity source to the policy store, and a Lambda authorizer to the API. When your application passes a user pool bearer token to the API, the Lambda authorizer invokes Verified Permissions. The authorizer passes the token as a principal and the request path and method as an action.

The following diagram illustrates the authorization flow for an API Gateway API with Verified Permissions. For a detailed breakdown, see API-linked policy stores in the Amazon Verified Permissions User Guide.

Verified Permissions structures API authorization around user pool groups. Because both ID and access tokens include a cognito:groups claim, your policy store can manage role-based access control (RBAC) for your APIs in a variety of application contexts.

Choosing policy store settings

When you configure an identity source on a policy store, you must choose whether you want to process access or ID tokens. This decision is significant to the way that your policy engine operates. ID tokens contain user attributes. Access tokens contain user access-control information: OAuth scopes. Although both token types have group-membership information, we generally recommend the access token for RBAC with a Verified Permissions policy store. The access token adds to group membership with scopes that can contribute to the authorization decision. The claims in an access token become context in the authorization request.

You must also configure the user and group entity types when you configure a user pool as an identity source. Entity types are principal, action, and resource identifiers that you can reference in Verified Permissions policies. Entities in policy stores can have a membership relationship, where one entity can be a member of a parent entity. With membership, you can reference principal groups, action groups, and resource groups. In the case of user pool groups, the user entity type that you specify must be a member of the group entity type. When you set up an API-linked policy store or follow Guided setup in the Verified Permissions console, your policy store automatically has this parent-member relationship.

The ID token can combine RBAC with attribute-based access control (ABAC). After you create an API-linked policy store, you can enhance your policies with user attributes and group membership. The attribute claims in an ID token become principal attributes in the authorization request. Your policies can make authorization decisions based on principal attributes.

You can also configure a policy store to accept tokens with an aud or client_id claim that matches a list of acceptable app clients that you provide.

Example policy for role-based API authorization

The following example policy was created by the setup of a Verified Permissions policy store for a PetStore example REST API.

permit(
  principal in PetStore::UserGroup::"us-east-1_EXAMPLE|MyGroup",
  action in [ PetStore::Action::"get /pets", PetStore::Action::"get /pets/{petId}" ],
  resource
  );

Verified Permissions returns an Allow decision to the authorization request from your application when:

Example policy for an Amazon Cognito user

Your user pool can also generate authorization requests to Verified Permissions in conditions other than API requests. You can submit any access control decisions in your application to your policy store. For example, you can supplement Amazon DynamoDB or Amazon S3 security with attribute-based access control before any requests transit the network, reducing quota use.

The following example uses the Cedar Policy Language to permit Finance users who authenticate with one user pool app client to read and write example_image.png. John, a user in your app, receives an ID token from your app client and passes it in a GET request to a URL that requires authorization, https://example.com/images/example_image.png. John's ID token has an aud claim of your user pool app client ID 1234567890example. Your pre token generation Lambda function also inserted a new claim costCenter with a value, for John, of Finance1234.

permit (
   principal,
   actions in [ExampleCorp::Action::"readFile", "writeFile"],
   resource == ExampleCorp::Photo::"example_image.png"
)
when {
   principal.aud == "1234567890example" &&
   principal.custom.costCenter like "Finance*"
};

The following request body results in an Allow response.

{
   "accesstoken": "[John's ID token]",
   "action": {
      "actionId": "readFile",
      "actionType": "Action"
   },
   "resource": {
      "entityId": "example_image.png",
      "entityType": "Photo"
   }
}

When you want to specify a principal in a Verified Permissions policy, use the following format:

permit (
   principal == [Namespace]::[Entity]::"[user pool ID]"|"[user sub]",
   action,
   resource
);

The following is an example principal for a user in a user pool with ID us-east-1_Example with sub, or user ID, 973db890-092c-49e4-a9d0-912a4c0a20c7.

principal == ExampleCorp::User::"us-east-1_Example|973db890-092c-49e4-a9d0-912a4c0a20c7",

When you want to specify a user group in a Verified Permissions policy, use the following format:

permit (
   principal in [Namespace]::[Group Entity]::"[Group name]",
   action,
   resource
);

The following is an example

Attribute-based access control

Authorization with Verified Permissions for your apps, and the attributes for access control feature of Amazon Cognito identity pools for Amazon credentials, are both forms of attribute-based access control (ABAC). The following is a comparison of the features of Verified Permissions and Amazon Cognito ABAC. In ABAC, a system examines the attributes of an entity and makes an authorization decision from conditions that you define.