# 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 authorization 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](policy-stores-create.md#policy-stores-create.title). 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](https://aws.amazon.com/blogs/security/use-amazon-verified-permissions-for-fine-grained-authorization-at-scale/) on the *AWS Security Blog*. **Topics** + [Available API operations for authorization](#authorization-operations) + [Testing your authorization model](authorization-testing.md) + [Integrating your authorization models with applications](authorization-sdk.md) ## Available API operations for authorization The Verified Permissions API has the following authorization operations. **[IsAuthorized](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorized.html)** 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 evaluates your request against all policies in the requested policy store that apply to the entities in the request. **[IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)** The `IsAuthorizedWithToken` operation generates an authorization request from user data in JSON web tokens (JWTs). Verified Permissions works directly with OIDC providers like 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 identity source. 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](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_BatchIsAuthorized.html)** 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](quotas.md#quotas-tps.title) 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](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_BatchIsAuthorizedWithToken.html)** 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](quotas.md#quotas-tps.title) 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 a user directory. 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 Amazon Verified Permissions authorization decision when you deploy your application, you can evaluate your policies as you develop them with the [Using the Amazon Verified Permissions test bench](test-bench.md) 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](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorized.html), [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html), and [BatchIsAuthorized](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_BatchIsAuthorized.html) as [signed AWS API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) to Regional [service endpoints](https://docs.aws.amazon.com/general/latest/gr/verifiedpermissions.html). 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 ] 1. Open the Verified Permissions console at [Verified Permissions console](https://console.aws.amazon.com/verifiedpermissions/). Create a policy store from the **Sample policy store** with the name **DigitalPetStore**. 1. Select **Test bench** in your new policy store. 1. Populate your test bench request from [IsAuthorized](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorized.html#API_IsAuthorized_Examples) 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`. 1. Set Alice's role as customer. Choose **Add a parent**, choose `DigitalPetStore::Role`, and enter Customer. 1. Set the resource as order "1234." For **Resource that the principal is acting on**, choose `DigitalPetStore::Order` and enter `1234`. 1. The `DigitalPetStore::Order` resource requires an `owner` attribute. Set Alice as the owner of the order. Choose `DigitalPetStore::User` and enter `Alice` 1. Alice requested to view the order. For **Action that principal is taking**, choose `DigitalPetStore::Action::"GetOrder"`. 1. Choose **Run authorization request**. In an unmodified policy store, this request results in an `ALLOW` decision. Note the **Satisfied policy** that returned the decision. 1. Choose **Policies** from the left navigation bar. Review the static policy with the description **Customer Role - Get Order**. 1. Observe that Verified Permissions allowed the request because the principal was in a customer role and was the owner of the resource. ------ #### [ REST API ] 1. Open the Verified Permissions console at [Verified Permissions console](https://console.aws.amazon.com/verifiedpermissions/). Create a policy store from the **Sample policy store** with the name **DigitalPetStore**. 1. Note the **Policy store ID** of your new policy store. 1. From [IsAuthorized](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorized.html#API_IsAuthorized_Examples) in the Verified Permissions API reference, copy the request body of **Example 4** that references the **DigitalPetStore** sample. 1. 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](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorized.html#API_IsAuthorized_Examples). 1. Paste in the sample request body and change the value of `policyStoreId` to the policy store ID you noted earlier. 1. 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. 1. 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`. 1. 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. 1. 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 your authorization models with applications 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** 1. 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](identity-sources.md#identity-sources.title) linked to your policy store or from another [OpenID Connect (OIDC) provider](cognito-validation.md#identity-sources-other-idp.title). 1. 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. 1. Determine the action that your user wants to take. 1. 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. 1. 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](https://aws.amazon.com/tools/). The following are links to documentation for Verified Permissions resources in various AWS SDKs. + [AWS SDK for .NET](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/VerifiedPermissions/NVerifiedPermissions.html) + [AWS SDK for C\$1\$1](https://sdk.amazonaws.com/cpp/api/LATEST/aws-cpp-sdk-verifiedpermissions/html/class_aws_1_1_verified_permissions_1_1_verified_permissions_client.html) + [AWS SDK for Go](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/verifiedpermissions) + [AWS SDK for Java](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/verifiedpermissions/package-summary.html) + [AWS SDK for JavaScript](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/verifiedpermissions/) + [AWS SDK for PHP](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-verifiedpermissions-2021-12-01.html) + [AWS SDK for Python (Boto)](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/verifiedpermissions.html) + [AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/VerifiedPermissions/Client.html) + [AWS SDK for Rust](https://docs.rs/aws-sdk-verifiedpermissions/latest/aws_sdk_verifiedpermissions/) The following AWS SDK for JavaScript example for `IsAuthorized` originates from [Simplify fine-grained authorization with Amazon Verified Permissions and Amazon Cognito](https://aws.amazon.com/blogs/security/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** + [Amazon Verified Permissions workshop](https://catalog.workshops.aws/verified-permissions-in-action) + [Amazon Verified Permissions - Resources](https://aws.amazon.com/verified-permissions/resources/) + [Implement custom authorization policy provider for ASP.NET Core apps using Amazon Verified Permissions](https://aws.amazon.com/blogs/dotnet/implement-a-custom-authorization-policy-provider-for-asp-net-core-apps-using-amazon-verified-permissions/) + [Build an entitlement service for business applications using Amazon Verified Permissions](https://aws.amazon.com/blogs/security/build-an-entitlement-service-for-business-applications-using-amazon-verified-permissions/) + [Simplify fine-grained authorization with Amazon Verified Permissions and Amazon Cognito](https://aws.amazon.com/blogs/security/simplify-fine-grained-authorization-with-amazon-verified-permissions-and-amazon-cognito/)