Developer’s Guide to Amazon Verified Permissions and Third-Party Identity Providers

Recently, Amazon Verified Permission, an AWS cloud-based authorization as a service that supports role, attribute, and policy access models, announced the support of third-party identity providers including CyberArk Identity. Until now, the authenticated user information was passed to the authorization service as a principal object containing the user attributes such as username and roles.

This new feature enables authorization using an OIDC token (ID or Access token) created during the authentication process. The use of the token eliminates the need to retrieve the user information from the identity provider. This feature supports any third-party OIDC token provider, in addition to the AWS Cognito token which is already supported. In this post, we describe the steps to integrate CyberArk Identity with Amazon Verified Permissions.

What’s the Difference Between an ID Token and an Access Token?

An ID token, formatted as a JWT token, contains claims about an authenticated user’s identity and is issued by an OIDC identity provider. In contrast, an access token is used to grant access to protected resources or APIs and is issued by an authorization server as part of OAuth 2.0. The access token can be in JWT format and others as well.

Existing Third-Party Integrations with Amazon Verified Permissions

The existing integration of third-party identity providers with Amazon Verified Permissions is explained in this post. A custom AWS Lambda Authorizer extracts user information from token claims and extends it using CyberArk identity APIs. Subsequently, it authorizes API Gateway calls using Amazon Verified Permissions and the is_authorized() API.

A New Kid in Town: Authorizing with Third-Party Identity Providers (OIDC Tokens)

Amazon Verified Permissions now allows authorization with third-party Identity Provider tokens, such as CyberArk Identity, instead of extracting the principal attributes from the identity provider. This streamlines integration improves performance by reducing API calls, and enables fine-grained permissions based on token claims.

Tips:

• Use JWKS tokens (not opaque ones) signed by the RSA 256 algorithm.
• Ensure the Identity Providers configuration server certificate is signed by default Amazon Linux 2 distribution certificate authorities

Set Up Cyberark Identity and Amazon Verified Permissions Integration

Setting the integration requires the setting of:

1. CyberArk Identity account for authentication
2. Setting Amazon Verified Permissions with one of the following methods:

• Using Quick Start — a step-by-step wizard to walk you through the setup process and automatically apply Verified Permissions policies to your Amazon API Gateway resources.
• Manual configuration of a Policy Store, Schema, Policies, and Identity Source.

Setting CyberArk Identity for ID or Access Token Authentication

To set up CyberArk Identity, follow these steps:

1. Ensure you have a CyberArk Identity account and an AWS Account.
2. Register for a free trial CyberArk Identity account if needed.
3. Add users, roles, and set custom attributes for fine-grained authorization policies.
4. Create an OIDC web application in CyberArk Identity by selecting one of the following options: OAuth2 Client, OAuth2 Server, or Open ID Connect.

Web UI to select the type of application

5. Customizing token claims is an optional step. If you need user attributes for authorization policies, you can edit the login script (as in the figure below) of your OIDC web application (instructions here). The JavaScript script enables you to set claims based on user fields and custom attributes. An example script is given here.

CyberArk Identity Script Editor

Amazon Verified Permissions Quick Start Wizard for Amazon API Gateway Authorization

Amazon Verified Permissions simplifies authorization for API Gateway using ID or Access tokens. It provides the ability to have a role-based authorization on your Amazon API Gateway resources, in a few Quick Start steps. A great demo video by the Amazon Verified Permissions team provides clear instructions to set up Amazon API Gateway resources access control using Amazon Verified Permissions and a third-party Identity Providers token.

Those steps include configuring the Amazon API Gateway resources to be controlled, the Identity Provider configuration, and token claims mapping to the policies. The wizard deploys a custom authorizer on the relevant Amazon API Gateway resources and new policies in the Policy Store. This approach is easy and requires zero coding.

The Authorization Flow with the Amazon API Gateway Resource

After setting up Amazon Verified Permissions and Amazon API Gateway using the wizard, we can provide controlled access to our resources (role-based access control).
The flow starts with a client, authenticating to the Identity provider, and receiving an ID or Access token (1). The client invokes the API Gateway endpoint with the token set in the header (as a bearer token) (2). The API Gateway invokes the Custom Lambda Authorizer (3) which invokes Amazon Verified Permissions with the token (4) Amazon Verified Permissions, get the Identity Provider configuration and public keys (5). It verifies the token signature, handles the token and request information, and runs an authorization check. It returns the authorization result to the Custom Lambda Authorizer (6) which returns the result (7) to the API Gateway. If the call is allowed, the API Gateway calls the service (8) and returns its response to the client (9,10).

API Gateway Access Flow

Manual Set-Up of Authorizing Using Amazon Verified Permissions API

We may need to use Amazon Verified Permissions API when Role-based access control is insufficient or our API backend is not Amazon API Gateway. Setting Amazon Verified Permissions manually requires to:

1. Create an Amazon Verified Permissions Policy Store and set its schema.
2. Define the policy store Identity Source.
3. Set policies to specify access-control logic.

An example script to create those resources can be found here. with the following commands:

cd examples/identity-source
./deploy_policy_store.sh <identity-tenant-domain-name>

For example:

./deploy_policy_store.sh <tenant-id>.my.dev.idaptive.app

The schema differs for ID tokens and Access tokens. For example, the schema for an ID Token includes attributes like ‘project_list’, ‘name’, and ‘session_config_json’ mapped to the principal. The context schema for access tokens maps claims to policy context objects. A schema for an ID Token can be found here and a schema for an Access Token can be found here.

The Identity Source configuration are different for an Access and ID Token. They can be found here and here.

Amazon Verified Permissions Policies for ID and Access Tokens

To authorize using the is_authorized_with_token API, you need policies at the policy store. These policies are defined in Cedar language, mapping specific objects to token claims. In an ID Token, ‘roles’ are used in the principal condition, while other claims serve as principal attributes.

Example Policy for ID Token:

permit (
    principal in NAMESPACE::Role::"System Administrator",
    action in [NAMESPACE::Action::"View"],
    resource
)
when
{
    principal has app_id &&
    principal.app_id == "AVPCyberArk" &&
    principal has name &&
    principal.name like "Prata*" &&
    principal.project_list.contains("Lion") &&
    principal.session_time_long > 100000 &&
    principal.session_config_json.session_idle > 20
};

For Access Tokens, claims are set as policy context properties under the token sub-object:

permit (principal, action, resource)
when
{
    context has token &&
    context.token has app_id &&
    context.token.app_id == "AVPCyberArk" &&
    context.token has auth_time &&
    context.token.auth_time > 100000 &&
    context.token has project_list &&
    context.token.project_list.contains("Lion")
};

Tip: The Amazon Verified Permissions API determines which token is used based on the id_token or access_token parameter.

API Authorization Flow using Amazon Verified Permissions and CyberArk Identity

The flow depicted here represents a general approach for an API backend to utilize an Identity Provider (IDP) for authentication, with Amazon Verified Permissions serving as the authorization service. In this flow, the backend directly calls the Amazon Verified Permissions API. This approach is particularly relevant for handling fine-grained resource and context conditions that fall outside the scope of the Amazon API Gateway custom authorizer discussed earlier. The client authenticates with the IDP and receives a token(1). The client then invokes the API Service (2). The service calls Amazon Verified Permissions using the is_authorized_with_token method (3). Amazon Verified Permissions retrieves the Identity Provider configuration and keys to validate the token (4). After token validation and authorization, Amazon Verified Permissions provides the decision to the backend service (5). If allowed, the backend service invokes the business logic (6). Finally, the backend service returns the response to the client (7).

Authentication and Authorization Flow for an API Call

Here is an example code for server authorization using Amazon Verified Permissions.

def check_authorization_with_token(policy_store_id: str,
                                  region: str,
                                  id_token: str = None,
                                  access_token: str = None,
                                  action: str = None,
                                  resource_id: str = None,
                                  user_attributes: Dict = None) -> str:

   kwargs = _get_avp_common_kwargs(policy_store_id=policy_store_id,
                                   action=action,
                                   resource_id=resource_id,
                                   user_attributes=user_attributes)
   if id_token:
       kwargs['identityToken'] = id_token
       claims = jwt.get_unverified_claims(id_token)

   elif access_token:
       kwargs['accessToken'] = access_token
       claims = jwt.get_unverified_claims(access_token)

   if claims and len(claims) > 0:
       kwargs['context'] = _get_context_map(claims)

   authz_response = _get_avp_client(region=region).is_authorized_with_token(
       **kwargs)

   return authz_response['decision']

A complete example can be found here with instructions. To run it use the following command:

python examples/token_login_authorize.py -i https://<identity-url> -a <app-id> -c <client-id>

Tips:

• This flow requires a user’s authorization code, you need to run a redirect server by this command: python examples/redirect.py.
• The redirect application should be defined in CyberArk Identity.

CyberArk Identity Tokens and Beyond

In this post, we’ve covered an easy way to integrate authentication using CyberArk Identity and authorization using Amazon Verified Permissions. While we’ve specifically used CyberArk identity tokens in code examples and identity source configuration, you can apply the same approach with other OIDC third-party providers.

Give this method a try to enhance your code’s security and modularity. I’d also like to express my gratitude to my colleagues Pratap Uppu from CyberArk and Aliaksei Ivanou from AWS for their valuable support and review.

I’m also happy to hear any feedback you have about this post, so feel free to share!