Search…
How to Use the Permissions Boundary to Restrict ReleaseHub Access
This page describes how to restrict the broad permissions that are available to ReleaseHub for special cases where customers need more fine-grained control over the defaults.

Overview

ReleaseHub performs most of the magic behind the scenes by using a role that is created in a customer AWS account which typically uses PowerUser access to create and deploy infrastructure and code to the customer account. This level of access gives ReleaseHub enough permissions to do everything that is needed to spin up clusters, load balancers, RDS databases and snapshots, configure DNS, and so forth. However, the Power User access does have some extra permissions that customers may feel uncomfortable allowing for one reason or another. For example, customers might ask, "Why does ReleaseHub need access to all my S3 buckets?" or "What happens if ReleaseHub accidentally spins up huge services and billable resources that I don't authorise or know about?" or "What if ReleaseHub accidentally deletes one of my most important databases?"
While it is theoretically possible to come up with a list of every single action and permission that ReleaseHub needs, in reality it is not possible to document every single API, resource, action, and permission that ReleaseHub needs to perform on behalf of customers in advance, now and in the future. AWS APIs and resources change and are added, policies get updated, and so on; which ultimately causes too much friction in narrowing the exact scope of permissions that are required to be able to function properly on our customers' behalf. Also, ReleaseHub may need to shrink or grow permissions and resources but doing so by itself might require permissions that allow ReleaseHub to do even more than originally agreed and intended by the customer which leads back to the same problem.
However, there is a way that customers can still protect themselves and their assets and sleep a little bit better at night knowing that ReleaseHub cannot exceed a certain level of permissions, or at least the customer can restrict certain areas of specific concern they may have for permissions in their accounts.

Permissions Boundaries to the Rescue

AWS supports using Permissions Boundaries to restrict access by binding a policy to a role (or a user, but ReleaseHub does not create users or credentials) which restricts the permissions and resources that the role can access, even if the role has an attached permission that allows some greater level of access. For example, ReleaseHub could request all access to all S3 buckets but the customer could apply a boundary policy that restricts buckets with only certain names or prefixes; or only allows "READ" permissions and not "DELETE".
ReleaseHub allows users to apply a permissions boundary to the default console role which will restrict access to only the subset of activities that are required by the customer and that will not diminish the functionality of the ReleaseHub product. During the course of normal operations, for example, it might not be necessary to provision any infrastructure or create DNS zones in the customer account. Only during upgrades or building a new cluster (for example) would such access be required. In this case, the normal day-to-day operations of the default ReleaseHub role would be restricted by a permissions boundary and whenever more access is required, the permissions boundary can be temporarily expanded or removed and then replaced when the access is not needed any further.

Prerequisites

The following prerequisites are needed to configure and apply a permissions boundary:
  • A ReleaseHub-provisioned cluster into your account or subaccount that you (the end-user customer) have access to.
  • The ReleaseHub-created console role ARN in your account. You can look in the /release/ namespace in IAM. Here is an example: arn:aws:iam::99999999999:role/release/releasehub-integration-ConsoleRole-1ABCDE2345
  • The ReleaseHub-created Cloudformation stack ARN in your account. You can look in the stacks listed in the region where the Cloudformation stack was built (we default to us-west-2 but could be in any region you chose. Here is an example: arn:aws:cloudformation:us-west-2:9999999999:stack/releaseStack/1111-111-2222-2222222
  • A suitable policy ARN that restricts access to the services and/or resources you don't want ReleaseHub to access; a starter template with permissions that are the minimal required for most use-cases is also in your account under the /release/ namespace. The example we provide is similar to arn:aws:iam::99999999999:policy/release/releasehub-integration-ReleaseHubMinimalPolicy-1ABCDE2345
  • Login credentials to either the AWS Console or CLI

Creating a Reduced Permissions Boundary Policy

The actual policy that you create to restrict access to API actions and resources in the end-customer's account is up to each customer, but ReleaseHub does provide a "minimal normal operational" policy that includes a lot of standard operations that could be performed by ReleaseHub in the normal day-to-day operations of deploying and updating code. In some cases, the existing minimal access policy would be fine to use as-is. In fact, we recommend you start with that policy (or revert back to it) if you are just testing the permissions boundary. The actual permissions boundary you will want to create is beyond the scope of this document but feel free to consult with our support team to work out a solution.
ReleaseHub recommend starting with the "Minimal Access Policy" as a template and removing permissions that you do not want. We believe that it would be suitable for most use cases. However, by either explicitly using the "Effect" of "Deny" or by removing the allowed reference, you will be restricting access with an implicit "Deny" for any privileges not listed in the policy. Use "Deny" policies to exclude very-fine-grained resources and permissions as detailed below.
As a simple example to get started and be clearer to implement, let's pretend that the existing minimal policy is suitable; except that you do not like the broad permissions applied in the following stanza:
{
"Action": [
"rds:Create*",
"rds:DeleteDBCluster",
"rds:DeleteDBInstance",
"rds:ModifyDBCluster",
"rds:ModifyDBInstance",
"rds:ModifyDBClusterParameterGroup",
"rds:ModifyDBParameterGroup",
"rds:ModifyDBSubnetGroup",
"rds:StartDBCluster",
"rds:StartDBInstance",
"rds:StopDBCluster",
"rds:StopDBInstance"
],
"Resource": [
"arn:aws:rds:*:999999999:cluster:*",
"arn:aws:rds:*:999999999:cluster-pg:*",
"arn:aws:rds:*:999999999:cluster-snapshot:*",
"arn:aws:rds:*:999999999:db:*",
"arn:aws:rds:*:999999999:pg:release-*",
"arn:aws:rds:*:999999999:og:release-*",
"arn:aws:rds:*:999999999:secgrp:release-*",
"arn:aws:rds:*:999999999:snapshot:*",
"arn:aws:rds:*:999999999:subgrp:*"
],
"Effect": "Allow"
}
This is the set of permissions that ReleaseHub requests, but you can go ahead and restrict with the following example to meet your expectations:
{
"Action": [
"rds:DeleteDBCluster",
"rds:DeleteDBInstance",
"rds:ModifyDBCluster",
"rds:ModifyDBInstance",
"rds:ModifyDBClusterParameterGroup",
"rds:ModifyDBParameterGroup",
"rds:ModifyDBSubnetGroup"
],
"Resource": [
"arn:aws:rds:*:999999999:db:production-*"
],
"Effect": "Deny"
}
In this way, you would block ReleaseHub from accessing databases that are prefixed by the name production- which is very reasonable. You can also see that ReleaseHub could still use StartDBInstance with production databases because the original policy still would permit that Action.
You can continue this process for any services, APIs, actions, and resources until you are happy with the results. We recommend you send over the policy for ReleaseHub to review since breaking things for your deployments might not be obvious until much later and harder to troubleshoot.

Getting Started

This section will document the Console method, you can find the commands for the CLI in the next section. Navigate to the Cloudformation console, find the ReleaseHub-created stack in the region you created it, and then click the Update button as shown.
Update the Cloudformation stack
Choose "Replace Current Template" with an "Amazon S3 Url" and enter https://release-template.s3-us-west-2.amazonaws.com/integration.yml as shown, then click Next.
The decision to use "Replace Current Template" vs. "Use Current Template" is yours; ReleaseHub recommends to always update to the latest version of our template by downloading the newest S3 location, especially if your integration was installed more than a few months ago. If you have recently updated the template or feel that the template is the latest, please do use the existing template.
DO NOT use the "Edit Template in Designer" option!
Replace the existing template
Now input the ARN to the managed policy that you would like to use as the Permissions Boundary as shown (leave all the boxes as-is, but fill in the desired permissions boundary policy ARN) then click the Next button again.
The permissions boundary ARN is just a policy ARN, but it must be fully qualified as a complete ARN, not just the policy name or path.
Fill in the permissions boundary policy ARN
On the next page, you can review all the tags, rollback policies and so forth; most customer will not adjust any settings here but advanced users can do so. Click Next one more time.
On the next page, you can review everything that you've edited up to now and click the Update Stack button as shown.
Acknowledge the Notes, Review the Settings, and Update the Stack

CLI Instructions

The permissions boundary can also be updated automatically which makes it much easier to provision by an administrator or security team. The exact setup steps are beyond the scope of the document, but any technical person can usually apply the scripts to update the following with enough examples shown. If there are any questions or concerns, feel free to contact ReleaseHub support for advice or help!
Make sure you fill in the actual values for your account, not the actual examples shown below.
#!/bin/sh
AWS_PROFILE=production
AWS_REGION=us-west-2
CF_STACK_ARN="arn:aws:cloudformation:${AWS_REGION}:9999999999:stack/releaseStack/1111-111-2222-2222222"
BOUNDARY_ARN="arn:aws:iam::99999999999:policy/release/releasehub-integration-ReleaseHubMinimalPolicy-1ABCDE2345"
aws cloudformation update-stack --stack-name $CF_STACK_ARN \
--template-url 'https://release-template.s3-us-west-2.amazonaws.com/integration.yml' \
--no-use-previous-template \
--parameters ParameterKey=AccountId,UsePreviousValue=true \
ParameterKey=ExternalId,UsePreviousValue=true \
ParameterKey=IntegrationUrl,UsePreviousValue=true \
ParameterKey=PermissionsBoundaryArn,ParameterValue=${BOUNDARY_ARN} \
--capabilities CAPABILITY_IAM

Restoring Normal Permissions

In order to restore normal operations, ReleaseHub recommends using the provided "Minimal Access Policy" created by the Cloudformation template as the permissions boundary. However, to restore the defaults to allow elevated permissions (such as during cluster upgrades or provisioning new clusters), we recommend removing the permissions boundary or consulting with our support team to create a policy that is required for the specific actions that are being worked on.