Workflows

What are Access Workflows?

Workflows are used in Common Fate to inform the policy engine how long access should last. Workflows connect with other resources like availabilities and Slack alerts.

Creating an Access Workflow

Access workflows are created using the commonfate_access_workflow resource in Terraform.

resource "commonfate_access_workflow" "workflow-demo" {
  name                     = "demo"
  access_duration_seconds  = 60 * 60
  priority                 = 100
}

Note

Changing the access duration on a Workflow does not affect the duration of any existing Access Requests.

For example, if you have an Access Workflow with a 2 hour access duration, create an Access Request, and then reduce the duration of the Access Workflow to 1 hour, the existing Access Request will still have a 2 hour duration.

The priority governs whether the policy will be used. If a different policy with a higher priority and the same role exists that one will be used over another.

Configuring request expiry

Note

Added in Common Fate v1.41.0. Requires Common Fate Terraform Provider v2.16 or later.

RequestedToApprovedExpiry and RequestedToActivateExpiry Added in Common Fate Terraform Provider v2.27.0.

Common Fate can be configured to automatically close approved requests if they are not activated within a particular duration. To configure an activation expiry, set the activation_expiry variable in the Access Workflow:

resource "commonfate_access_workflow" "workflow-demo" {
  name                     = "demo"
  access_duration_seconds  = 60 * 60
  priority                 = 100
 activation_expiry        = 60 * 60 * 8
 requested_to_approved_expiry = 60 * 60 * 4
 requested_to_activate_expiry = 60 * 60 * 4
}

The activation_expiry causes requests to expire if they are approved but not activated for a specified amount of time following being approved.

The requested_to_activate_expiry causes requests to expire if they are requested but not approved for a specified amount of time following being requested.

The requested_to_activate_expiry causes requests to expire if they are approved but not activated for a specified amount of time following being requested.

In the example above any requests approved but not activated after 8 hours will be closed, requiring the user to re-request access.

Requiring a reason on Access Requests

Note

Added in Common Fate v1.42.0. Requires Common Fate Terraform Provider v2.17 or later.

To require a reason on Access Requests for a particular workflow, you can specify the validation variable on the Access Workflow:

resource "commonfate_access_workflow" "workflow-demo" {
  name                     = "demo"
  access_duration_seconds  = 60 * 60
  priority                 = 100
 validation = {
   has_reason = true
 }
}

Validating the reason on Access Requests

Note

Added in Common Fate v2.7. Requires Common Fate Terraform Provider v2.26.1 or later.

To require add validation to the reason on Access Requests for a particular workflow, you can specify the validation variable on the Access Workflow:

resource "commonfate_access_workflow" "workflow-demo" {
  name                     = "demo"
  access_duration_seconds  = 60 * 60
  priority                 = 100
  validation = {
    reason_regex = [
      {
        regex_pattern = ".{20}",
        error_message = "Reason must be at least 20 characters long",
      },
      {
        regex_pattern = "CF-\\d+"
        error_message = "Please include a ticket ID (CF-XXX)"
      }
    ]
  }
}

Make sure to double escape any backslash characters by using \. In the example above, the regex \d+ needs to be escaped like \\d+ so that Terraform is able to read the string.

Specifying a default duration for Access Requests

Note

Added in Common Fate v1.42.0. Requires Common Fate Terraform Provider v2.17 or later.

The Common Fate web console and CLI will default to the maximum duration when requesting access. You can change the default duration by providing the default_duration_seconds variable on the Access Workflow:

resource "commonfate_access_workflow" "workflow-demo" {
  name                     = "demo"
  access_duration_seconds  = 60 * 60
  default_duration_seconds = 30 * 60
  priority                 = 100
}

Enabling Access Request Extensions

Note

Added in Common Fate v4.4.0. Requires Common Fate Terraform Provider v2.22.0 or later.

By default, the Common Fate web console will not allow extensions if the extension_conditions configuration is not specified on the Access Workflow.

Note

A cedar policy also needs to be defined to allow the Access::Action::“Extension” action on the resource.

resource "commonfate_access_workflow" "workflow-demo" {
  name                     = "demo"
  access_duration_seconds  = 60 * 60
  priority                 = 100
 extension_conditions = {
   maximum_number_of_extensions = 2
   extension_duration_seconds = 10 * 60
 }
}

The maximum_number_of_extensions parameter sets the number of times an Access Request can be extended. This can be set to 0, effectively disabling extensions.

The extension_duration_seconds parameter defines the duration, in seconds, that the Access Request will be extended by.

Extensions can only be requested after at least 50% of the duration has elapsed. This ensures that extensions are used judiciously and not immediately after access is granted.

For example, with an initial access duration of 60 minutes:

1. You must wait at least 30 minutes (50% of the initial duration) before requesting your first extension.
2. If you extend when you have 25 minutes remaining, your access will be extended to 35 minutes.
3. You can request a second extension after another 5 minutes (50% of the extension duration) has elapsed.
4. With a maximum of two extensions, you can add up to 20 minutes to your initial access duration.

This approach ensures that extensions are used thoughtfully and only when necessary.

Multi-step Approvals

Common Fate v2.8.0 introduced the ability to specify multi step approval flows inside Access Workflows. All conditions / steps on the approval flow must pass before the end user can activate a request.

Multi-step approvals follow similar syntax to cedar policies in that they have a when clause to evaluate the reviewing user.

The when expression can reference the principal and/or the resource.grant.

resource "commonfate_access_workflow" "workflow-demo" {
    name                     = "demo"
    access_duration_seconds  = 60 * 60
    priority                 = 100
    approval_steps = [
        {
        name = "Approval from Jack"
        when = <<EOF
        principal == CF::User::"usr_2ixfjkldsjlk23z09b1Da"
        EOF
        },
        {
        name = "Apporoval is Required from one of the Security Team"
        when = <<EOF
        principal in Entra::Group::"Security"
        EOF
        },
    ]
  }

Results in the following approval steps on a request for access.

Multi-step approvals require each step to be completed by a different reviewer. When a reviewer matches more than one of the approval steps, they will be automatically assigned to one. The other step will require action from a different user.

In cases where multiple reviews are required and the reviewers match more than one of the steps, Common Fate will automatically reassign the reviewers to the steps such that all steps are satisfied and the request is approved.