Skip to content
Common Fate
Docs Granted

Testing

Common Fate uses authorization policy-as-code powered by Cedar. In this guide, you’ll learn how to write tests to verify the behaviour of your Cedar policies and confirm that Common Fate resource syncing is working as expected.

The Common Fate CLI allows tests to be written using a YAML file in the following format:

# group-tests test whether a user is a member of a group or not.
group-tests:
- user: alice@example.com
  group: 2df6c5c4-0e09-477a-b796-9ad9bd756d83
  is-member: true


# access-tests test whether a user is allowed to access a particular entitlement or not.
access-tests:
- user: alice@example.com
  target: development-aws-account
  role: AWSReadOnlyAccess
  expected-result: auto-approved


- user: alice@example.com
  # you can also use Cedar entity IDs here for the target or role
  target: AWS::Account::"123456789012"
  role: AWS::IDC::PermissionSet::"3d06e8e5-93d3-4bfd-ae4f-e5caf43c99ad"
  expected-result: requires-approval


- user: alice@example.com
  target: very-sensitive-aws-account
  role: AWSReadOnlyAccess
  expected-result: no-access

Prerequisites

If you’re running a BYOC (“Bring-Your-Own-Cloud”) deployment of Common Fate in your own AWS account, you’ll need to be on v1.31.0 or later of the common-fate/common-fate-deployment/aws Terraform module.

You will need the Common Fate cf CLI installed - v1.15.1 or higher. You can check this by running cf --version. You should see an output similar to the below:

Terminal window
cf --version
cf version v1.15.1
# version must be v1.15.1 or higher for this guide.

Creating a test file using the CLI

To create a new test file, run the following command:

Terminal window
cf tests create -f tests.yml

You should see an output as follows:

[✔] created tests.yml

After creating a tests file, edit the file in your code editor to add users, groups and entitlements based on your deployment.

Running tests using the CLI

To run tests, use the command:

Terminal window
cf tests run -f tests.yml

You should see an output similar to the below, containing the results of the tests:

retrieving users for email address lookups...
retrieved 126 users
-------------- ACCESS TESTS --------------
running 2 access tests...


[PASS] chris@commonfate.io requires-approval to Sandbox-1 with role ViewOnlyAccess


[FAIL] chris@commonfate.io auto-approved to Sandbox-2 with role ViewOnlyAccess: got requires-approval
  policies contributing to requesting access: [basic.policy0]
  policies contributing to activating access: []


-------------- GROUP MEMBERSHIP TESTS --------------
running 2 group membership tests...


[PASS] chris@commonfate.io is member of c9bed4d8-d091-7057-4ed7-6d60bcf1e8bf


[PASS] chris@commonfate.io is not member of 790e94a8-2071-7016-a43c-86e66212a43d


1 Access Tests failed
All Group Membership Tests passed

If any access tests fail, the Cedar policies contributing to the authorization decision will be shown below. For example:

[FAIL] chris@commonfate.io auto-approved to Sandbox-2 with role ViewOnlyAccess: got requires-approval
  policies contributing to requesting access: [basic.policy0]
  policies contributing to activating access: []

In the output above, the basic.policy0 policy is allowing the user to request access, and there are no policies allowing the user to activate the access. The policies are in the format <policy ID>.policyN, where <policy ID> is the ID of the Cedar policy set specified in Terraform, and N is the index of the policy in the policy set.

Policy sets can contain multiple policies as shown below:

// if the policy set has the ID 'basic'


// this policy will be 'basic.policy0'
permit(principal, action == Access::Action::"Request", resource);


// this policy will be 'basic.policy1'
permit(principal, action == Access::Action::"Approve", resource);

Next steps

Running access tests in CI