If we use Cognito User pools as an identity provider, AWS now enables us to configure fine-grained access control to our API Gateway endpoints using Amazon Verified Permissions.
1. A recent release
AWS has recently published a new feature for Cognito. The release introduces the use of Amazon Verified Permissions (AVP) to securely manage access to REST-type API Gateway endpoints via a Lambda authorizer.
2. The scenario
Bob was thrilled to explore this new feature and quickly implemented it in one of his company's applications. He had previously secured several endpoints using scopes and access tokens. When his manager requested the addition of a new endpoint, Bob chose to implement the new AVP-based access control mechanism.
In this post, I will compare two of their API endpoints: GET /scope
and GET /avp
(names have been changed for privacy đ ). Both endpoints use access tokens to make authorization decisions, but they are secured differently - through scopes and AVP, respectively.
3. Protecting API Gateway endpoints with Verified Permissions
Before diving into the comparison let's review the resources needed to implement this new access control mechanism with Cognito and AVP.
3.1. Using the wizard
Verified Permissions includes a new wizard that creates all necessary resources for this feature.
The wizard guides us through several steps:
- Importing the API endpoints we wish to protect by selecting the API and its stage.
- Choosing the Cognito user pool.
- Assigning Cognito group users to specific endpoints.
The final step involves the wizard provisioning all the resources listed below. Currently, we need to manually add the API Gateway authorizer to the endpoints and then deploy the API if using the AWS console.
3.2. Verified Permissions resources
We'll need the following resources for AVP, all created via the console wizard.
Policy store
A container for policies, described with the API ID and stage included.
Identity source
Currently, the only supported identity provider is Cognito. We specify our Cognito user pool here with MyApi::User
as the principal type (MyApi
is the policies' namespace). We choose whether to use identity or access tokens for authorization and can opt to authorize requests that match a specific app client ID.
Schema
This defines the supported actions and entity types. For example, User
is the principal, get /avp
is the action, and Application
is the resource.
Policies
Policies are written in Cedar language and determine whether to ALLOW
or DENY
requests similarly to IAM policies. An example policy looks like this:
permit(
principal in MyApi::UserGroup::"IDENTITY_POOL_ID|avp-group",
action in [ MyApi::Action::"get /avp" ],
resource
);
This policy will allow users in the avp-group
Cognito group to call the GET /avp
endpoint in MyApi
.
We can also create policies for individual Cognito users. In this case, we should specify the Cognito ID as principal
in the policy:
permit(
principal in MyApi::User::"IDENTITY_POOL_ID|USER_ID",
action in [ MyApi::Action::"get /avp" ],
resource
);
Although it allows us to control granular access at the user level, I would still use groups and add the users to them as it seems to provide less management overhead.
3.3. Cognito resources
We should create a user pool and several groups, such as the avp-group
that contains certain users. This group acts as the principal
element in the AVP policy.
3.4. Lambda authorizer
API Gateway calls this function when a request reaches the protected endpoint. The function sends the necessary data to the IsAuthorizedWithToken
Verified Permissions endpoint for authorization.
Sample input payload:
{
accessToken: 'ACCESS_TOKEN',
policyStoreId: 'POLICY_STORE_ID',
action: { actionType: 'MyApi::Action', actionId: 'get /avp' },
resource: { entityType: 'MyApi::Application', entityId: 'MyApi' }
}
IsAuthorizedWithToken
will verify the token and make an authorization decision based on the payload and the available policies.
The response object (avpResponse
) includes an ALLOW
or DENY
decision, based on the policies.
const avpResponse = {
'$metadata': {
httpStatusCode: 200,
attempts: 1,
totalRetryDelay: 0
// other properties
},
decision: 'ALLOW',
determiningPolicies: [
{ policyId: 'POLICY_ID_1' },
{ policyId: 'POLICY_ID_2' }
],
errors: [],
principal: {
entityType: 'MyApi::User',
entityId: 'COGNITO_USER_POOL_ID|COGNITO_USER_ID'
}
}
The COGNITO_USER_ID
will match the sub
claim of the access (or identity) token.
The Lambda function returns an IAM policy object reflecting this decision to API Gateway:
{
principalId: 'PRINCIPAL_ID',
policyDocument: {
Version: '2012-10-17',
Statement: [
{
Action: 'execute-api:Invoke',
Effect: avpResponse.decision.toUpperCase() === 'ALLOW'
? 'Allow'
: 'Deny',
Resource: 'RESOURCE'
}
]
},
}
API Gateway then allows or denies the request.
3.5. API Gateway authorizer
Finally, we need a Lambda authorizer resource linked to the function in API Gateway. This can be set up separately or through the wizard.
4. Comparing access control with tokens only and AVP
Now let's compare the traditional token-based API access control to the AVP method described above.
4.1. Access tokens
Access tokens embed authorization details in the scope
claim, which API Gateway inherently recognizes. If the scope in the token matches what's defined in the API Gateway authorizer settings, the request is allowed to proceed; if not, it's automatically rejected.
However, this approach isn't without its challenges. It requires additional setup steps that can complicate the process.
Firstly, we must establish a resource server in Cognito and define the specific scopes you intend to use. Then, during user authentication - essentially when users log into your application - we must ensure that these required scopes are included in the request to the token endpoint. Failure to include these scopes means they won't appear in the access token, potentially blocking access where it's needed.
This method can become cumbersome if the system requires a variety of permissions. An alternative is to implement a pre-token generation function within Cognito. This function dynamically injects user-specific scopes into the access token based on membership in Cognito groups or according to rules defined in a database.
4.2. ID tokens
Identity tokens primarily store user information. API Gateway is capable of validating these ID tokens to confirm user authentication.
However, since ID tokens lack authorization data, additional measures are necessary to manage access control. We have two options: deploy a Lambda authorizer that assigns permissions based on user or group identity or handle the authorization logic at the backend. In either scenario, we should maintain an external map of users and their corresponding permissions to ensure secure and efficient access management.
4.3. Using AVP
As highlighted earlier, this new feature utilizes a Lambda authorizer. Currently, API Gateway does not directly support authorization using Verified Permissions.
Using AVP eliminates the administrative burden associated with managing scopes and custom authorizations. The Lambda authorizer employs standardized code that remains consistent across different users, groups, and policies, simplifying the setup process.
AVP enables detailed access control without the reliance on scopes. This method enhances scalability allowing quick integration of new Verified Permissions policies into the policy store. Configuring access for user groups to specific endpoints is straightforwardâsimply by making selections in the console. Moreover, there's no need for the pre-token generation Lambda functions previously required.
In my experience testing API Gateway with AVP authorization, I found it significantly simpler than managing scopes. If AWS integrates native support for Verified Permissions within API Gateway - eliminating the need for a separate Lambda authorizer - it would offer a significant improvement over traditional access control methods in API Gateway.
4.4. Access vs ID token
As noted earlier, when setting up resources for Verified Permissions, we must specify whether to use ID or access tokens.
Both token types can effectively manage access control since Cognito embeds group information into each token type's cognito:groups
claim. However, it's important to note that this doesn't apply simultaneously.
Choosing an ID token during the setup means that attempting to use an access token later will result in an error:
ValidationException: Failed to verify IdentityToken: \
invalid token type: Expected IdentityToken in the IdentityToken \
parameter but received AccessToken.
The reverse scenario also holds true - if our configuration specifies an access token AVP will not accept an ID token. Therefore, we should make a clear decision about the token type from the start and consistently use that type for authorization.
5. Summary
We can now enhance the security of API Gateway endpoints using Cognito and Verified Permissions. The required resources can be efficiently provisioned through the wizard available on the Verified Permissions console page.
This new method of access control simplifies the developerâs task of setting up endpoint authorization by eliminating the need for configuring scopes and streamlining the authorization process.
6. Further reading
Authorization with Amazon Verified Permissions - More examples and details on the feature
Create a new user pool - What the page title says
IsAuthorizedWithToken - The IsAuthorizedWithToken endpoint specification
Amazon Verified Permissions policy stores - Good title for this page
Amazon Verified Permissions policy store schema - Straightforward documentation page titles today
Amazon Verified Permissions policies - About AVP policies