Controlling Access to Amazon API Gateway with CyberArk Identity and Amazon Verified Permissions

By Gil Adda, Principal Software Architect – CyberArk
By Aliaksei Ivanou, Partner Solutions Architect, Security and Identity – AWS

CyberArk

Software as a service (SaaS) applications and services secure access to their resources by adding logic to make decisions when handling a user request. These decisions can be based on user roles and attributes, request context, and more.

This post reviews how to control access to an Amazon API Gateway resource by using Amazon Verified Permissions as a managed authorization service and CyberArk Identity as the identity provider (IdP). CyberArk Identity works seamlessly with Amazon Verified Permissions, which provides a scalable, fine-grained permissions management and authorization service for custom applications.

We review the architecture and flows, setup instructions, and code examples. Using this approach, you can reduce your development efforts and time to market, increase authorization logic visibility, and respond faster to security needs.

CyberArk is an AWS Security Competency Partner and AWS Marketplace Seller that is a global leader in identity security. The CyberArk Identity solution is CyberArk’s SaaS-delivered identity and access management.

Integration Benefits

Hard-coding authorization logic into the source code can introduce challenges, including:

Weaker governance
Maintenance overhead
Increased time to market

Amazon Verified Permissions co-deployed with CyberArk Identity brings the following benefits:

Improved access control logic governance and reduced total cost of ownership: Access control logic is managed in a central location with a single policy language to help you reduce total cost of ownership (TCO).
Increased flexibility: Policy-based access control model allows you to create role-based and attribute-based access control models with additional context conditions to address your specific needs.
Easier updates of access control logic: Deploy access logic to your external authorization engine and react faster to logic changes.
Reduced development efforts and time to market: Reuse the same implementation across multiple services.

Solution Overview

In our sample solution, the authorization enforcement is handled by an AWS Lambda token authorizer. It receives the user access token in the request authorization header (bearer token) and validates its integrity.

The next step is the retrieval of the user attributes from the IdP and calling the Amazon Verified Permissions service to authorize the request. The authorization decision is based on the access control policies stored there.

This approach decouples the authorization logic from the application code, and is reusable for multiple API Gateway resources. The diagram in Figure 1 describes the architecture and user flow from the client application (like a browser) up to the service.

The components involved in this integration are:

CyberArk Identity: For identity and access management.
Amazon Verified Permissions: Scalable, fine-grained permissions management and authorization service.
Amazon API Gateway: Service to manage and secure REST, HTTP, and Web Socket APIs.
AWS Lambda authorizer: An API Gateway feature that uses an AWS Lambda function to control resource access.
Service business logic: An example of our logic is implemented as a Lambda function.

Authorization Flow

The authorization flow is depicted in the following diagram and described after:

Figure 1 – Architecture and authorization flow.

The flow starts with the browser or other client accessing the service and authenticating to the IdP (1), which returns an access token on a successful attempt (2).
The browser/client calls the service API Gateway method with that access token (3).
API Gateway calls the Lambda authorizer passing the token and method Amazon Resource Name (ARN), as described in the documentation (4).
The Lambda authorizer:
- Verifies the token signature by using the public key received from the IdP (5).
- Extracts the token claims and retrieves custom user attributes from CyberArk Identity (6).
- Prepares a request in Amazon Verified Permissions format (7) and invokes the service to authorize the request (8).
- Builds an IAM policy based on Amazon Verified Permissions decision and returns it to the API Gateway (9).
- API Gateway invokes the service Lambda function, if the request is allowed (10), and returns the response to the client.

Setup

We need to set up the following:

CyberArk Identity account and a user with custom attributes.
Amazon Verified Permissions policies.
Amazon API Gateway and AWS Lambda authorizer demo resource.

CyberArk Identity (Identity Provider) Setup

The steps to set up CyberArk Identity are depicted in the diagram below and elaborated after.

Figure 2 – CyberArk Identity setup and usage.

CyberArk Identity setup steps:

Register for CyberArk Identity and get a free trial account. After registering, you can manage your users and assign them to roles.
Log in as an administrator to CyberArk Identity with the credentials you received by email.
Set up users’ custom attributes schema:
- Go to Admin Portal > Settings > Customization > Additional Attributes and press Add. Enter the attribute name, type, and description.
- In this example, we’ll use the following attributes:
  - user_dept – to describe the user department.
  - user_project – to describe the user project.

Figure 3 – CyberArk Identity setup of custom user attribute form.

Add a user in the CyberArk Identity console (detailed in the documentation); for example, my-user. CyberArk Identity requires you to define a suffix which is used for your username. The username would be my-user@my-suffix. This suffix is also used for the default admin (cloudadmin), meaning you need to log in with the username cloudadmin@my-suffix after you defined a suffix.

Figure 4 – CyberArk Identity add user form.

Check the option Is OAuth confidential client. More information on CyberArk Identity authentication methods can be found in the documentation.
Add the user attributes by updating the Additional Attributes option.

Figure 5 – CyberArk Identity user attributes.

Add a role such as “System Administrator” and assign your user to that role. You can do it by selecting the role, and the members list of that role. On the role members list, add your user to the role members. Additional details can be found in the documentation.

Figure 6 – CyberArk Identity adding users to a role.

Amazon Verified Permissions Policy Setup

The AWS Lambda authorizer decision is based on the policies defined in Amazon Verified Permissions. To set the policies, you need to create a policy store and manage policies there. The policies are written in a language called Cedar to express a role-based policy and attribute-based policy with additional conditions.

Learn more about Cedar language, and explore the Amazon Verified Permissions documentation.

The policy in our demo contains the following conditions:

User should belong to the “System administrators” user group (this is the role-based part).
Resource should be “protected-resource” and the action is “POST.”
Login weekday is restricted from Monday to Thursday (to simulate working days).
User should be part of the HR department and a project called “Eagle.” Set the policy below to your Amazon Verified Permissions policy store (follow the instructions in the user guide).

permit (
    principal in UserGroup::"System Administrator",
    action == Action::"POST",
    resource == Resource::"protected-resource"
)
when {
    [0, 1, 2, 3, 4 ].contains(context.weekday) &&
    principal.user_dept == "HR" &&
    principal.user_project == "Eagle"
};

API Gateway and Lambda Authorizer Demo Resource

To deploy a demo solution, please use this GitHub repo which contains instructions and an AWS CloudFormation template. Follow the steps below:

Clone the repo at https://github.com/cyberark/identity-aws-verified-permissions-demo
Create an Amazon Simple Storage Service (Amazon S3) bucket.
Run this command to set up the API Gateway with the Amazon Verified Permissions token authorizer and a sample resource:

./prepare_authorizer_package.sh <s3 bucket name> <verified permissions policy store id> <cyberark identity url> <region>

To get the Amazon Verified Permissions policy store ID, refer to the documentation.
To get the CyberArk Identity URL, log in to the CyberArk Identity portal and copy the URL (without the path parameters). It looks similar to: https://{tenant_id}.id.cyberark.cloud/

As a result of the deployment, you see a new API Gateway with a Lambda token authorizer.

Figure 7 – Token authorizer.

The API Gateway contains a resource called “protected resource” with a “POST” method that is protected by the Lambda authorizer. The input to the Lambda authorizer is the access token and the method ARN. The sample code can be found on GitHub.

Figure 8 – API Gateway resource method with the Lambda authorizer.

This token authorizer can be reused for multiple API Gateway resources. To implement it:

Attach the token authorizer to the API Gateway resource and method.
Create an Amazon Verified Permissions policy to match the new resource. For example, duplicate the preceding example policy and change it to the relevant resource and action.

This approach leverages the external authorization service to reduce development efforts and time to market.

Testing the Integration

The integration testing is based on a script that performs a login to CyberArk Identity, receives an auth token, and invokes the API Gateway resource method with that token. The script input is the username, CyberArk Identity URL, and API Gateway URL.

To get the resource URL, please obtain an API’s invoke URL in the Amazon API Gateway console. It should look like this: https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}

Next, install the script dependencies:

pip install -r requirements.txt

To invoke the script run the following command and enter your password when asked:

python access-demo-resource.py -u <username> -i <identity url> -g <resource url>

In case you are authorized, the result message is “Hello from Lambda!” – otherwise, you get “User is not authorized to access this resource with an explicit deny.”

Now, let’s change the policy to allow access for the Dev department instead of the HR department. Go to the Amazon Verified Permissions policy editor, select the policy, and update it to:

permit (
    principal in UserGroup::"System Administrator",
    action == Action::"POST",
    resource == Resource::"protected-resource"
)
when {
    [0, 1, 2, 3, 4].contains(context.weekday) &&
    principal.user_dept == "Dev" &&
    principal.user_project == "Eagle"
};

In that case, the access is blocked as the user is from the HR department. The Rest API message is “User is not authorized to access this resource with an explicit deny.”

To troubleshoot, look at the instructions in GitHub.

Cleanup

To clean up the resource we created in this post:

Delete the AWS CloudFormation stack named avp-authorizer-stack
Delete the temporary Amazon S3 bucket

Conclusion

In this post, we demonstrated Amazon API Gateway resource access control based on an AWS Lambda authorizer. The Lambda authorizer logic uses Amazon Verified Permissions as the access control decision service and CyberArk Identity to get the user information.

This integration provides the benefit of decoupling the access control logic from the source code and provides an efficient method to provide access control logic to new services.

While this integration was implemented using an API Gateway with a custom Lambda authorizer, it can be modified to support different enforcement points technologies on top of the API Gateway. Cedar, an open-source language for defining permissions as policies, offers flexibility to support a variety of strategies to construct the policies, including role-based access control (RBAC) and attribute-based access control (ABAC).

Learn more about CyberArk Identity and try this out with Amazon Verified Permissions.

Sample code, software libraries, command line tools, proofs of concept, templates, or other related technology are provided as AWS content or third-party content under the AWS Customer Agreement, or the relevant written agreement between you and AWS (whichever applies). You should not use this AWS content or third-party content in your production accounts, or on production or other critical data. You are responsible for testing, securing, and optimizing the AWS content or third-party content, such as sample code, as appropriate for production grade use based on your specific quality control practices and standards. Deploying AWS content or third-party content may incur AWS charges for creating or using AWS chargeable resources, such as running Amazon EC2 instances or using Amazon S3 storage.

.

.

CyberArk – AWS Partner Spotlight

CyberArk is an AWS Partner and global leader in identity security with a rich portfolio of SaaS products for which customers can buy and use a subscription-based license.

Contact CyberArk | Partner Overview | AWS Marketplace

AWS Partner Network (APN) Blog