Introduction
Common Fate uses a policy-as-code to govern the various decision points around granting access to entitlements. Common Fate policies are written using the open-source policy language Cedar. Writing Cedar policies is similar to writing software code: you can test and review changes using your existing tools like Terrafom and GitHub.
We recommend using the Cedar Language Guide in conjunction with our guide below. Cedar policies are structured with four main components:
Decorators
Decorators are annotations added to Cedar policies to provide additional instructions or messages to end users. They serve as helpful hints or notifications regarding the policy rules. For instance:
This decorator provides guidance to users by indicating that the access is automatically approved due to it being in the test environment.
Principal
The principal
component specifies the entity seeking access. For example:
Actions
Actions define the operations that can be performed within Common Fate. These actions include:
- Request access:
Access::Action::"Request"
- Activate access:
Access::Action::"Activate"
- Breakglass access:
Access::Action::"BreakglassActivate"
- Approve access:
Access::Action::"Approve"
- Extend access:
Access::Action::"Extend"
- Close request:
Access::Action::"Close"
The following is the workflow of the Cedar actions:
Additionally, we also have the following actions to enhance observability:
CF::Authz::Action::"GetEvaluation"
CF::Admin::Action::"Read"
You can find more details about them here.
Resource
The resource
component specifies the target or subject of the action. It identifies the entity upon which actions are taken. For example:
When and Unless
The when
and unless
components define additional conditions under which the action is allowed. For instance:
Policy Example
Here’s an example Cedar policy allowing users to close their own requests:
This policy grants permission for a user to close their own request. It verifies that the principal (user) matches the principal associated with the resource, ensuring that only the requester can close their own request.
How Common Fate uses Cedar
Each authorization evaluation in Cedar has a Principal and a Resource. For actions including Access::Action::"Approve"
, Access::Action::"Request"
, Access::Action::"Activate"
and Access::Action::"Close"
, the Principal is a User and Resource being acted upon is a Grant.
Grants represents temporary access to a particular target (the resource, like an AWS Account, GCP Project, or DataStax Organization) with a particular role (AWSAdministratorAccess, roles/owner or R/O User) and have an ID like Access::Grant::"gra_2ZTR7P2ITax3jXa8OC4u88A4ZQk"
. You can see the role and target amongst the other attributes in the screenshot below.
The following would work:
The problem here though is that you’d need to write a policy like this for every requested Grant which is not scalable. Instead, we can use attributes like resource.role
and resource.target
. Cedar doesn’t allow these in the permit()
or forbid()
block, we have to use them in the when {}
block instead. So we get a policy like this:
Another example, if you wanted to auto-approve access to a read-only role, you could use:
If you wanted to restrict the policy to particular accounts, you could use:
Here’s a reference from the Cedar docs on this we’d recommend too.
Base Policies Overview
Here are some basic policy examples are shown below to familiarise yourself with Cedar. During the deployment process we’ll provide you with tailored Cedar policies for your authorization use cases.
Managing Request, Auto-Approve, and Approval Policies
Explore the flexibility of managing access requests, auto-approvals, and approval policies by modifying Cedar policies. Here are a few examples:
Auto-Approve Access Requests
To enable automatic approval, set the action for the resource to action == Access::Action::"Activate"
. The following policy is an example of enabling auto-approval for access requests targeting the GCP project within a Test folder:
Deny Access Request from Specific User
To deny access requests from a particular user, use the following policy:
You can also match a user based on their email address:
This policy prevents the user from submitting access requests.
Extend Access
To allow access to be extended on a Grant, you can use the Access::Action::"Extend"
action:
Auto-approval for on-call users
You can set auto-approval for on-call users from PagerDuty and OpsGenie. Below is an example of automatically approving access for on-call responders in PagerDuty:
Deploying Authorization Policies to Terraform
You can organize the authorization policies in different files, such as policies/demo.cedar
, and apply them using Terraform in a file named policies.tf
:
After applying the changes to Terraform, you should see CF::PolicySet appear in your Resources tab in the web UI.
Writing Cedar Policies in Terraform
Common Fate maintains a Cedar Terraform Provider Cedar Terraform Provider to make authoring Cedar policies easier in Terraform. The provider allows you to write authorization policies using HCL, Terraform’s configuration syntax.
To use the provider, add it to your required_providers
in Terraform:
Here’s a simple example:
The cedar_policyset
resource renders a Cedar policy, available as data.cedar_policyset.example.text
. Here’s what the resulting policy looks like:
The provider allows you to use Terraform variables in your policies. For example, we can configure an on-call rotation in PagerDuty, as well as authorization policies for access workflows in one place:
You can learn more about the provider here.