Authorization with Amazon Verified Permissions - Amazon Cognito

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 token to Verified Permissions in an IsAuthorizedWithToken API request. The IsAuthorizedWithToken API also accepts your user's requested Action on the Resource that they want to access, and additional custom Context that can contribute to a granular access decision.

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

  1. Your user pool is a configured Verified Permissions identity source for the requested policy store.

  2. The client_id or aud claim, in your access or identity token respectively, matches a user pool app client ID that you provided to Verified Permissions. To verify this claim, you must configure client ID validation in your Verified Permissions identity source.

  3. Your token isn't expired.

  4. The value of the token_use claim in your token matches the parameters that you passed to IsAuthorizedWithToken. The token_use claim must be access if you passed it to the accessToken parameter, and id if you passed it to the identityToken parameter.

  5. The signature in your token comes from the published JSON web keys (JWKs) of your user pool. You can view your JWKs at user pool ID/.well-known/jwks.json.

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


Because of the way that Verified Permissions processes claims, don't add claims named cognito, dev, or custom in your pre token generation function. When you present these reserved claim prefixes not in colon-delimited format like cognito:username but as full claim names, your authorization requests fail.

Verified Permissions doesn't process the cognito:groups claim.

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.

Authorization example

The following is an example user pool flow for Amazon Cognito and Verified Permissions with a custom ID token and retrieval of resources from Amazon API Gateway.

        An example user pool flow for Amazon Cognito and Verified Permissions with custom tokens and retrieval of
          resources from Amazon API Gateway.
Example authorization flow
  1. Your user requests a resource in your app that your app must retrieve from an API.

  2. Your user signs in to your Amazon Cognito user pool.

  3. Your user pool sends your user's details to your user pool Pre token generation Lambda trigger. The use of a pre token trigger is optional.

  4. Your Lambda function looks up your user in Amazon DynamoDB and adds claims to your user's ID or access tokens.

  5. Amazon Cognito returns the access and ID tokens to your app.

  6. Your app presents your user's ID token and metadata in a request to Verified Permissions.

  7. Verified Permissions processes your user's claims and compares them to the policies in your organization's policy store. When it finds an Allow condition with no overriding Deny, Verified Permissions responds with its Allow decision.

  8. Your app processes the Allow response and presents your user's access token to your API Gateway Amazon Cognito authorizer. In this example, the access token has a dual purpose in its contribution to the fine-grained access control decision by Verified Permissions, and the scope-based access control decision by API Gateway.

  9. Your API accepts your user's token and returns the requested resource to your app.

  10. Your app displays the requested resource to your user.

  11. When your user requests another protected resource, your app returns to the Authorization step and presents the new request to Verified Permissions.

Example policy for an Amazon Cognito user

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, 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 [Action::"readFile", "writeFile"], resource == ExampleCorp::File::"a8f3f048-ded7-4a95-89ca-e283644e1898" // example_image.png ) when { principal.aud == "1234567890example" && principal.costCenter like "Finance*" };

The following request body results in an Allow response.

{ "accesstoken": "[John's access 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:

principal == namespace::User::"[user pool ID]"|"[user sub]"

The following is an example principal statement 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",
Attribute-based access control

Authorization with Verified Permissions for your apps, and the attributes for access control feature of Amazon Cognito identity pools for AWS 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.

Service Process Result
Amazon Verified Permissions Returns an Allow or Deny decision from analysis of a user pool JWT. Access to application resources succeeds or fails based on Cedar policy evaluation.
Amazon Cognito identity pools (attributes for access control) Assigns session tags to your user based on their attributes. IAM policy conditions can check tags Allow or Deny user access to AWS services. A tagged session with temporary AWS credentials for an IAM role.