Approve to Promote

Approve to promote (ATP) helps platform owners ensure global policies are reviewed and approved before they are eligible for production environments. With ATP enabled, the Immuta application workflow guides policy authors to create, assess, and revise policies in development. When the policy author is ready for review, the approvers can inspect the policy and indicate their approval through the Immuta application. Once a policy has reached the configured number of approvals, the change becomes eligible for promotion. For instructions to enable this feature, see Enable approve to promote. To use the feature, see Approve and promote policies to production.

Requirements

Approve to promote requires the following environment settings and Immuta CLI versions:

• One Immuta tenant per policy-authoring environment and production environment. SaaS tenants should be hosted under separate domains.
• Approve to promote is enabled only in the policy-authoring environment.
• Immuta CLI 1.1.0+.

Approve to promote conceptual overview

When approve to promote is enabled, any global policies that are created, edited, or staged will go through this process:

1. A data governor creates a global policy in the development environment.
2. The policy author requests a review, and a notification is sent to approvers.
3. The policy is reviewed by data owners and other data governors, who either request changes or approve the policy.
4. Once the policy reaches the required number of approvals, a data governor promotes the policy through the Immuta CLI.
5. A data governor saves the policy to the production environment though the Immuta CLI.

Policy authoring

Users with the GOVERNANCE or CREATE_DATA_SOURCE permissions can create and edit global policies.

When ATP is enabled, policy changes will take effect in the policy-authoring environment before the policy is approved. This behavior allows users to iterate on these policies in the authoring environment before they are reviewed by others. When ready, the policy author requests a review from approvers through the Immuta policy builder user interface, who can then approve or request changes.

Once under review, the policy will display the approval history and progress.

Data governors and data owners can click a policy to see its status in the review process, approve it, or request changes to it.

Policy review and approval

After the policy author requests for approval, the policy is in review. The review period ends when the approval threshold is met, a reviewer requests for changes, or the policy is modified. ATP requires the configured minimum number of reviewers to approve a policy before it can be promoted.

For example, if the ATP approval threshold is configured to require approvals from three users and a policy review receives 3 approvals, then the review has ended and no other reviewers can request for changes. However if the same policy receives two approvals, a third reviewer may end the review for rework by requesting changes.

Users with the following Immuta permissions can review and approve policies:

• CREATE_DATA_SOURCE: Data owners can author and approve global policies that apply to data sources they own, but they cannot approve their own policies.
• GOVERNANCE: Governors can author and approve global policies, but they cannot approve their own policies.

When these users request changes to a policy, they are required to provide an explanation for the revision. Then, the request freezes the approval process until an update is made to the policy by a data governor. Users who previously approved the policy will need to re-approve the changes before the policy can be promoted.

When users approve a policy, they are prompted to provide an optional comment. After their approval, the policy status updates to show how many more approvals are required.

Policy promotion

After a policy has been approved, governors promote the policy through the Immuta CLI. The policy must then be cloned and saved to the production environment via the Immuta CLI. Once this has been completed, policies are marked as promoted in the UI.

Immuta does not prevent governors from directly editing policies in production environments, so administrators should ensure that the GOVERNANCE permission is granted to a limited number of users in production environments to prevent policy changes that circumvent the approval process.

Audit

In the policy-authoring environment, no audit records are emitted by Immuta for approvals. However, when policies are promoted, audit records will be emitted for the following actions:

• Global policy created
• Global policy review requested
• Global policy change requested
• Global policy approval rescinded
• Global policy approved
• Global policy promoted

The policy references (PolicyKey) are stable across environments, as long as they are not modified manually after cloning the policies for promotion.

Limitations

• Immuta does not prevent users with the GOVERNANCE permission from editing policies directly in production without going through the approval workflow, so administrators should grant that permission to a limited number of users in the production environment.
• Approval chains are not supported, so they must be coordinated outside Immuta.

Enable approve to promote

1. Click the App Settings icon in the left sidebar.
2. Select Advanced Settings at the bottom of the left panel to expand the list.
3. Click Preview Features.

4. Scroll to the Approve To Promote section and click the Enable Approve to Promote checkbox. Note: Set the number of users required to approve the global policy in the Required Number of Approvals field. The example below requires 2 users, but adjust this number to meet your needs.

5. Click Save and Confirm to update the settings.

Approve and promote a global policy

Prerequisite

Approve to promote is enabled on a development tenant of Immuta.

Configure the dev and prod tenant in the Immuta CLI

Before you can add promoted policies to the production environment, you need to configure the production environment as an additional profile in the Immuta CLI.

1. Run immuta configure -p dev. Note: dev is the profile name of the development tenant in this example. You can use a different name.

2. Enter the URL and your API Key for your development Immuta tenant in the interactive prompt.

   $ immuta configure -p dev
   ? What is the url of the immuta instance you use?: https://your.dev.instance.url.com/
   ? What is the api key of your immuta user account?:  ***************************
   
   Updated the config at /Users/user/.immutacfg.yaml
   

3. Run immuta configure -p prod. Note: prod is the profile name of the production tenant in this example. You can use a different name.

4. Enter the URL and your API Key for your production Immuta tenant in the interactive prompt.

   $ immuta configure -p prod
   ? What is the url of the immuta instance you use?: https://your.prod.instance.url.com/
   ? What is the api key of your immuta user account?:  ***************************
   
   Updated the config at /Users/user/.immutacfg.yaml
   

Below is the configuration file that will be saved at ~/.immutacfg.yaml:

dev:
  api_key: <api key>
  host: https://your.dev.instance.url.com
prod:
  api_key: <apiKey>
  host: https://your.prod.instance.url.com

Build the global policy in dev

1. Create a Global Data Policy in the development tenant.

2. Request a review from approvers by clicking Start Approval Process in the Immuta policy builder.

Once under review, the policy will will be marked as In Review and will display the approval history and progress.

Review the policy

After reviews are requested, other data governors and users who own affected data sources will be notified that a global policy is ready for their review.

1. Navigate to the policy on the Policies page.

2. Opt to approve the policy or request changes. Use the tabs below to view both of these options.

   Approve the policyRequest changes

   Approve the policy

   1. Click the policy to expand the In Review window and click the dropdown button to expand the list of options.

   2. Click Approve, and opt to provide a comment in the modal that appears.

   3. Click Send Approval to confirm.

   Once the configured number of users (set on the App Settings page) approves the policy, the policy moves out of review and can be promoted.

   Request changes

   1. Click the policy to expand the In Review window and click the dropdown menu to expand the list of options.

   2. Click Request Changes and provide a comment in the modal that appears.

   3. Click Send Request to confirm.

   If changes are requested, a data governor must revise the global policy to apply the changes. Once these changes are made, the policy will need to be reviewed again by the specified number of users. Users will receive another notification that their review is required.

Revise the policy

1. Navigate to global policy and select Edit from the dropdown menu.

2. Update the policy to reflect the changes requested. In this example, the data governor updates the policy to mask personal identifiers by making null.

3. When ready, click Start Approval Process in the Immuta policy builder.

Users will receive another notification that their review is required.

Promote the policy

To promote the policy, run the following command that clones the policy and saves it in a policy folder in the path you specify. Note: If you run this command more that one time, you need to change the names of (or delete) the files that were already cloned to avoid an error; this process preserves the cloning history.

immuta policy clone --promote ./approved-policies-folder

Once a policy is promoted, the Immuta UI displays the Promoted status.

Save the policy in prod

To add the global policy to the production environment, save the policy through the Immuta CLI, specifying the name of the profile you created for the production environment in this step, the file path, and the policy name.

immuta policy save --profile prod ./approved-policies/policy/Mask--PII.yaml

The policy will be applied to data sources in the production environment.

Rescind your approval

Users can also rescind their approval of a policy.

1. Click the policy to expand the In Review window.
2. Click Undo Your Approval and opt to provide a comment in the modal that appears.
3. Click Rescind to confirm.