Convera Implements Fine-Grained API Authorization with Amazon Verified Permissions

Convera, a company handling billions in cross-border payments annually for global businesses and financial institutions, faced the challenge of securing its expanding API platform. A robust authorization system was essential to protect sensitive financial data and maintain operational efficiency. This article describes how Convera implemented a fine-grained authorization model for its API platform using Amazon Verified Permissions.

Background

With the expansion of Convera’s services, a scalable, secure, and auditable method for enforcing role-based and attribute-based access control became necessary. The objective was to ensure that all users, whether internal or external, could only access resources and perform actions for which they were explicitly authorized, while also allowing for adaptability to changing business requirements. Initially, Convera considered developing an internal access control system. However, it became clear that creating policy management, real-time authorization, logging, and auditing from the ground up would demand substantial engineering effort and continuous upkeep, diverting focus from core business activities. Convera ultimately selected Amazon Verified Permissions for implementing fine-grained authorization for its payment APIs due to several key advantages:

• Seamless integration with AWS services such as Amazon Cognito and Amazon API Gateway.
• The Cedar policy language‘s capability to define intricate authorization rules.
• The capacity to evaluate various attributes, including user roles, transaction values, and geographical locations.
• High-performance authorization decisions, often within milliseconds.

Due to its adaptability and scalability, Verified Permissions served as the core architectural blueprint for managing access control in two primary contexts:

• Fine-grained Access Control – Convera’s Payment platform caters to a wide range of users, including customers, internal personnel, and machine-to-machine interactions. Each requires specific permissions determined by their roles, organizational structure, and operational context.
• Multi-tenancy Controls – A significant challenge for Convera involved implementing multi-tenant access control while ensuring rigorous data isolation. Verified Permissions enabled the definition of policies that dynamically assessed tenant ownership, user roles, and contextual attributes.

The following sections detail Convera’s implementation strategy across its key use cases.

Fine-grained access control

Fine-grained access control is essential for application security, ensuring users are granted precisely defined permissions to access only specific resources or actions within an application. With Verified Permissions, a schema can be defined to specify entity types, attributes relevant to the authorization model, and valid combinations of principal types, resource types, and actions. This schema is then used by Verified Permissions to validate that static policies or policy templates align with the application’s authorization model.

Convera deployed Verified Permissions to achieve fine-grained access control across various user types and interaction scenarios.

Customer access management

For the user interface, Convera utilized Verified Permissions to regulate API access according to distinct user characteristics. In their financial applications, for instance, the display of transaction functionalities, such as modifying payment parameters, is dynamically managed by Verified Permissions policies.

The diagram below illustrates the user authorization decision flow for financial transactions.

Figure 1: User Authorization Decision for financial transactions

An example Cedar policy, shown below, can be used with Verified Permissions for this use case. This policy ensures that only authorized users with specific roles can access sensitive financial controls. The same policy must be evaluated at the API level when a transfer request is initiated. At the service level, the policy is designed to enforce fine-grained access controls.

permit (
    principal,
    action in [MyApp::Action::"ViewTransferButton"],
    resource
) when {
    principal.role == "PAYMENT_INITIATOR" &&
    resource.accountType == "BUSINESS" &&
    resource.status == "ACTIVE"     
};

Applications can integrate with Verified Permissions via its API to authorize user access requests. For every authorization request, the service retrieves and evaluates applicable policies to determine if a user is allowed to perform an action on a resource, considering contextual inputs like user identities, roles, group memberships, and attributes.

The following figure presents the end-to-end architectural diagram of this implementation.

Figure 2: Fine-grained User Authorization control with Verified Permissions

The workflow proceeds through these steps:

1. Users log in via the client application.
2. The client authenticates using Amazon Cognito.
3. Amazon Cognito activates a pre-token generation AWS Lambda function to retrieve user roles.
4. The Lambda function retrieves user roles from Amazon Relational Database Service (Amazon RDS).
5. The Lambda function enhances a JSON Web Token (JWT) with user role details.
6. The client application receives the enriched JWT containing user roles.
7. The client application initiates an API call, sending an authorization request to API Gateway with the enriched JWT.
8. A Lambda authorizer validates the JWT and its role permissions, then calls Verified Permissions.
9. Verified Permissions evaluates access policies stored as Cedar policies and makes an authorization decision.
10. Verified Permissions relays the authorization result to the Lambda authorizer.
11. Based on the authorization result, the Lambda authorizer sends an AWS Identity and Access Management (IAM) policy to API Gateway, either allowing or denying the request.
12. API Gateway then permits or rejects the request to the client application.
13. API Gateway caches the IAM policy for future use.

Convera’s infosec team manages policy governance using a tightly controlled IAM role. Modifications to Cedar policies are recorded via Amazon DynamoDB Streams and consistently synchronized with Verified Permissions.

To enhance performance, Convera implemented a two-tier caching system. This system utilized the API Gateway‘s integrated cache for authorization decisions and application-level caching for Amazon Cognito tokens. The Lambda function calls Verified Permissions to authorize requests. If a ‘deny’ decision is returned, the request is rejected with an HTTP 403 (unauthorized) response. If an ‘allow’ decision is returned, the request proceeds. This multi-level caching strategy achieved sub-millisecond response times, reduced operational expenses, and upheld security controls.

Internal customer connect applications

Convera successfully repurposed the same architecture for internal user access, benefiting roles like customer service associates who require rapid access to client information for efficient service delivery, all while safeguarding sensitive data. By leveraging Verified Permissions, a role-specific Cedar policy was developed to accomplish the following:

• Provide view-only access to fundamental customer profiles, encompassing contact details and service history.
• Limit editing capabilities to particular fields, such as updating contact preferences or recording support interactions.
• Prevent access to confidential financial data or internal business metrics.

In this scenario, internal users authenticate via their enterprise identity provider (IdP), specifically Okta, through the Convera Connect App. They then acquire ID and access tokens from Amazon Cognito. Amazon Cognito, utilizing a pre-token generation hook, customizes the access token with user attributes stored in Amazon DynamoDB. While the Cedar policies are specifically designed for internal roles and responsibilities (differing from customer-facing policies), the core process involving API Gateway, a Lambda authorizer, Verified Permissions policy evaluation, and decision caching remains consistent. This architectural consistency eliminated the need for Convera to reconstruct its authorization infrastructure, allowing the application of identical performance optimizations, security controls, and operational procedures across both customer and internal user access models.

Extending the model to service communication

Following the successful implementation of Verified Permissions for customer and internal user access, Convera identified the potential to extend this architecture to secure service-to-service communications. Similar to user authentication managed via Amazon Cognito user pools, each client service is registered within Convera’s client configuration system. Verified Permissions then establishes a dedicated policy store for service-specific permissions. Services authenticate through Amazon Cognito using client credentials (rather than user credentials) to acquire access tokens containing service-specific attributes like service identifier, tier, permitted operations, and rate limits.

The diagram below illustrates the machine-to-machine architecture for both internal and external partner integrations.

Figure 3: Machine to machine architecture for internal and external partner integration

The workflow encompasses these steps:

1. Service A dispatches an API request to the authentication token endpoint in API Gateway, including its access token.
2. The request is then routed to Amazon Cognito, which validates the token from the machine-to-machine user pool.
3. Once authenticated, Service A makes a request to the business API (Service B) via API Gateway.
4. API Gateway forwards the request to the Lambda authorizer, which processes the incoming request and extracts the service context from the token.
5. The Lambda authorizer submits the authorization request to Verified Permissions for evaluation against stored Cedar policies. This evaluation considers:
   1. Service identity.
   2. The requested operation.
   3. The resource context.
   4. Relevant environmental factors.
6. Verified Permissions returns an ‘allow’ or ‘deny’ decision. If ‘allow’ is returned:
   1. The Lambda authorizer generates an appropriate IAM policy.
   2. API Gateway caches the authorization decision.
   3. The request is then forwarded to Service B.
   4. Subsequent similar requests can utilize the cached decision.

Multi-tenancy controls

As Convera broadened its support for multi-tenant Software as a Service (SaaS) integrations, the need arose for implementing tenant-specific access controls and data isolation. The primary challenge was to ensure that users within each tenant could only access their designated resources, while also empowering tenant administrators to manage their own access policies. Convera addressed these requirements by adapting its existing Verified Permissions architecture, employing a per-tenant policy store strategy.

Verified Permissions per-tenant policy store

Convera opted for a per-tenant policy store approach due to several advantages:

• Simplified isolation of tenant policies.
• Flexibility to customize templates and schemas for each tenant.
• Streamlined tenant onboarding and offboarding processes.
• Management of resource quotas on a per-tenant policy store basis.

The figure below illustrates the process of implementing fine-grained authorization control using Verified Permissions with a per-tenant policy store.

Figure 4: Fine-grained authorization control using Verified Permissions with per-tenant policy store

The complete process flow involves these steps:

1. A tenant-specific Amazon Cognito pool is established with a custom tenant_id attribute. Users log into this pool using their user claims (e.g., user_id).
2. Amazon Cognito employs a pre-token generation Lambda function to retrieve the user_id from a DynamoDB table that maps users to tenants.
3. A DynamoDB table is maintained to store user and tenant configuration mappings.
4. The pre-token generation Lambda hook retrieves the tenant_id from DynamoDB and adds it as a custom attribute to the access token.
5. The user then makes an API call to API Gateway with the enriched JWT.
6. API Gateway validates the token and forwards the request to a custom Lambda authorizer.
7. The Lambda authorizer function extracts the tenant_id from the JWT and retrieves the corresponding Verified Permissions policy-store-id from a DynamoDB table.
8. The Lambda authorizer verifies the JWT’s validity and claims against the Verified Permissions-associated Amazon Cognito pool, as indicated in the access token.
9. Upon successful authentication, it invokes Verified Permissions to confirm the user’s authorization for the requested action.
10. If authorized, Verified Permissions returns an IAM policy granting ‘Allow’ access (with a default ‘Deny’ stance) and forwards the request to backend Kubernetes pods, including the tenant_id in a custom header.
11. Backend services receive the tenant_id, re-validate with Verified Permissions (for zero-trust adherence), establish a tenant context, and then forward the request to Amazon RDS. Amazon RDS is configured to accept only requests with a specific tenant context and returns data relevant to the requested tenant_id.

Below are examples of Cedar policies employed for multi-tenant isolation:

permit (
    principal in
        convera_connect_authz::userGroup::"ConveraConnect-PAYEE_MGMT",
    action in [convera_connect_authz::Action::"PUT /customer/user/{id}"],
    resource
);
 
permit (
    principal,
    action in [convera_connect_authz::Action::"EDIT"],
    resource
)
when
{
    principal.role.contains("UPDATE_USER_STATUS") &&
    resource.type == "PUT" &&
    resource.path == "/customers/user"
};

Conclusion

This article detailed how Convera leveraged Verified Permissions to construct an advanced, fine-grained authorization model for its API platform. The discussion covered Convera’s successful implementation of fine-grained access for customers, multi-tenant SaaS integrations, machine-to-machine communication, and internal customer connect applications using Verified Permissions. Through this implementation, Convera achieved several key benefits:

• Deployment of fine-grained access control across diverse use cases.
• Strengthened security through attribute-based access control in multi-tenant environments.
• Improved scalability, processing thousands of authorization requests per second with sub-millisecond latency.
• Increased operational efficiency, leading to a 60% reduction in time spent on access management.
• Development of a future-ready authorization framework capable of adapting to evolving business demands.

For further information on implementing these patterns and best practices, the Verified Permissions User Guide is available. For practical experience, the Verified Permissions workshop offers practical examples and guided exercises.