API operations API testing Integrating with apps

Implementing authorization in Amazon Verified Permissions

After you build your policy store, policies, templates, schema, and authorization model, you're ready to start authorizing requests using Amazon Verified Permissions. To implement Verified Permissions authorization, you must combine configuration of policies in AWS with integration in an application. To integrate Verified Permissions with your application, add an AWS SDK and implement the methods that invoke the Verified Permissions API and generate authorization decisions against your policy store.

Authorization with Verified Permissions is useful for UX permissions and API permissions in your applications.

UX permissions: Control user access to your application UX. You can permit a user to view only the exact forms, buttons, graphics and other resources that they need to access. For example, when a user signs in, you might want to determine whether a "Transfer funds" button is visible in their account. You can also control actions that a user can take. For example, in same banking app you might want to determine whether your user is permitted to change the category of a transaction.
API permissions: Control user access to data. Applications are often part of a distributed system and bring in information from external APIs. In the example of the banking app where Verified Permissions has permitted the display of a "Transfer funds" button, a more complex authorization decision must be made when your user initiates a transfer. Verified Permissions can authorize the API request that lists the destination accounts that are eligible transfer targets, and then the request to push the transfer to the other account.

The examples that illustrate this content come from a sample policy store. To follow along, create the DigitalPetStore sample policy store in your testing environment.

For an end to end sample application that implements UX permissions using batch authorization, see Use Amazon Verified Permissions for fine-grained authorization at scale on the AWS Security Blog.

API operations for authorization

The Verified Permissions API has the following authorization operations.

IsAuthorized

The IsAuthorized API operation is the entry point to authorization requests with Verified Permissions. You must submit principal, action, resource, context, and entities elements. Verified Permissions validates the entities in your request against your policy store schema. Verified Permissions then evaluates your request against all policies in the requested policy store that apply to the entities in the request.

IsAuthorizedWithToken

The IsAuthorizedWithToken operation generates an authorization request from user data in Amazon Cognito JSON web tokens (JWTs). Verified Permissions works directly with Amazon Cognito as an identity source in your policy store. Verified Permissions populates all attributes to the principal in your request from the claims in users' ID or access tokens. You can authorize actions and resources from user attributes or group membership in an Amazon Cognito user pool.

You can't include information about group or user principal types in an IsAuthorizedWithToken request. You must populate all principal data to the JWT that you provide.

BatchIsAuthorized

The BatchIsAuthorized operation processes multiple authorization decisions for a single principal or resource in a single API request. This operation groups requests into a single batch operation that minimizes quota usage and returns authorization decisions for each of up to 30 complex nested actions. With batch authorization for a single resource, you can filter the actions that a user can take on a resource. With batch authorization for a single principal, you can filter for the resources that a user can take action on.

BatchIsAuthorizedWithToken

The BatchIsAuthorizedWithToken operation processes multiple authorization decisions for a single principal in one API request. The principal is provided by your policy store identity source in an ID or access token. This operation groups requests into a single batch operation that minimizes quota usage and returns authorization decisions for each of up to 30 requests for actions and resources. In your policies, you can authorize their access from their attributes or their group membership in an Amazon Cognito user pool.

Like with IsAuthorizedWithToken, you can't include information about group or user principal types in a BatchIsAuthorizedWithToken request. You must populate all principal data to the JWT that you provide.

Testing your authorization model

To understand the effect of Verified Permissions authorization decision when you deploy your application, you can evaluate your policies as you develop them with the Test bench and with HTTPS REST API requests to Verified Permissions. The test bench is a tool in the AWS Management Console to evaluate authorization requests and responses in your policy store.

The Verified Permissions REST API is the next step in your development as you move from a conceptual understanding to application design. The Verified Permissions API accepts authorization requests with IsAuthorized, IsAuthorizedWithToken, and BatchIsAuthorized as signed AWS API requests to Regional service endpoints. To test your authorization model, you can generate requests with any API client and verify that your policies are returning authorization decisions as expected.

For example, you can test IsAuthorized in a sample policy store with the following procedure.

Test bench

Open the Verified Permissions console at https://console.aws.amazon.com/verifiedpermissions/. Create a policy store from the Sample policy store with the name DigitalPetStore.
Select Test bench in your new policy store.
Populate your test bench request from IsAuthorized in the Verified Permissions API reference. The following details replicate the conditions in Example 4 that references the DigitalPetStore sample.
1. Set Alice as the principal. For Principal taking action, choose DigitalPetStore::User and enter Alice.
2. Set Alice's role as customer. Choose Add a parent, choose DigitalPetStore::Role, and enter Customer.
3. Set the resource as order "1234." For Resource that the principal is acting on, choose DigitalPetStore::Order and enter 1234.
4. The DigitalPetStore::Order resource requires an owner attribute. Set Alice as the owner of the order. Choose DigitalPetStore::User and enter Alice
5. Alice requested to view the order. For Action that principal is taking, choose DigitalPetStore::Action::"GetOrder".
Choose Run authorization request. In an unmodified policy store, this request results in an ALLOW decision. Note the Satisfied policy that returned the decision.
Choose Policies from the left navigation bar. Review the static policy with the description Customer Role - Get Order.
Observe that Verified Permissions allowed the request because the principal was in a customer role and was the owner of the resource.

REST API

Open the Verified Permissions console at https://console.aws.amazon.com/verifiedpermissions/. Create a policy store from the Sample policy store with the name DigitalPetStore.
Note the Policy store ID of your new policy store.
From IsAuthorized in the Verified Permissions API reference, copy the request body of Example 4 that references the DigitalPetStore sample.
Open your API client and create a request to the Regional service endpoint for your policy store. Populate the headers as shown in the example.
Paste in the sample request body and change the value of policyStoreId to the policy store ID you noted earlier.
Submit the request and review the results. In a default DigitalPetStore policy store, this request returns an ALLOW decision.

You can make changes to policies, schema, and requests in your test environment to change the outcomes and produce more complex decisions.

Change the request in a way that changes the decision from Verified Permissions. For example, change Alice's role to Employee or change the owner attribute of order 1234 to Bob.
Change policies in ways that affect authorization decisions. For example, modify the policy with the description Customer Role - Get Order to remove the condition that the User must be the owner of the Resource and modify the request so that Bob wants to view the order.
Change the schema to allow policies to make a more complex decision. Update the request entities so that Alice can satisfy the new requirements. For example, edit the schema to allow User to be a member of ActiveUsers or InactiveUsers. Update the policy so that only active users can view their own orders. Update the request entities so that Alice is an active or inactive user.

Integrating with apps and AWS SDKs

To implement Amazon Verified Permissions in your application, you must define the policies and schema that you want your app to enforce. With your authorization model in place and tested, your next step is to start generating API requests from the point of enforcement. To do this, you must set up application logic to collect user data and populate it to authorization requests.

How an app authorizes requests with Verified Permissions

Gather information about the current user. Typically, a user's details are provided in the details of an authenticated session, like a JWT or web session cookie. This user data might originate from an Amazon Cognito identity source linked to your policy store or from another OpenID Connect (OIDC) provider.
Gather information about the resource that a user wants to access. Typically, your application will receive information about the resource when a user makes a selection that requires your app to load a new asset.
Determine the action that your user wants to take.
Generate an authorization request to Verified Permissions with the principal, action, resource, and entities for your user's attempted operation.Verified Permissions evaluates the request against the policies in your policy store and returns an authorization decision.
Your application reads the allow or deny response from Verified Permissions and enforces the decision on the user's request.

Verified Permissions API operations are built into AWS SDKs. To include Verified Permissions in an app, integrate the AWS SDK for your chosen language into the app package.

To learn more and download AWS SDKs, see Tools for Amazon Web Services.

The following are links to documentation for Verified Permissions resources in various AWS SDKs.

The following AWS SDK for JavaScript example for IsAuthorized originates from Simplify fine-grained authorization with Amazon Verified Permissions and Amazon Cognito.


const authResult = await avp.isAuthorized({
    principal: 'User::"alice"',
    action: 'Action::"view"',
    resource: 'Photo::"VacationPhoto94.jpg"',
    // whenever our policy references attributes of the entity,
    // isAuthorized needs an entity argument that provides    
    // those attributes
    entities: {
       entityList: [
         {
            "identifier": {
                "entityType": "User",
                "entityId": "alice"
            },
            "attributes": {
                "location": {
                    "String": "USA"
                }
            }
         }
       ]
    }
});

More developer resources

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

Test bench