Secure access to your AWS accounts

Bref Cloud accesses your AWS accounts to deploy and manage resources, such as AWS Lambda, S3 buckets, etc. To do this, it interacts with AWS via its SDK and API.

Instead of using long-lived AWS credentials (access keys), Bref Cloud uses IAM roles with temporary credentials following AWS best practices. This document explains how Bref Cloud accesses these AWS accounts securely in more detail.

Introduction

“Accessing an AWS account” means that Bref Cloud performs actions in the account, like creating a Lambda function or an S3 bucket. Practically, this is done via the AWS API using the AWS SDK.

To use the AWS API, Bref Cloud needs AWS credentials that give access to the target account.

Bref Cloud does not use long-lived AWS credentials (aka AWS access keys). Instead, it follows standard AWS best practices and uses IAM roles with temporary credentials .

Note that all of this happens automatically and is easy to set up in the Bref Cloud web interface.

How it works

To connect an AWS account to Bref Cloud, you create a BrefCloudAccess IAM role in that account. The role is created by the bref-cloud-connect CloudFormation stack, deployed in the us-east-1 region (IAM roles are global, so you can deploy applications to any region). You can deploy that stack:

from the Bref Cloud dashboard, which opens the AWS console with the stack ready to create,
or with the bref connect command, which uses the AWS credentials configured on your machine (use --profile to choose an AWS profile).

You can also create the IAM role manually and paste its ARN in Bref Cloud.

This role:

gives permissions to access specific resources in your account (like Lambda functions)
can only be “assumed” by the BrefCloudAccessor role from the Bref Cloud AWS account (called a “trust policy”).

When Bref Cloud needs to access your account, it:

assumes the BrefCloudAccessor role in its own AWS account
uses this new role to assume the BrefCloudAccess role in your AWS account
gets temporary credentials that have the permissions of the BrefCloudAccess role

These credentials are valid for a short period of time. Bref Cloud uses them to perform the actions you requested (like retrieving logs). When you run bref deploy, they are also sent to the bref CLI, which runs serverless deploy with them on your machine or in your CI, without you having to configure AWS credentials.

Bref Cloud does not store these credentials. They are only used for the duration of the operation.

Why use IAM roles?

IAM roles are the recommended way to grant access to AWS resources over long-lived credentials (like access keys). Access keys can be leaked and are hard to rotate. IAM roles can only be used by the Bref AWS account.

Thanks to IAM roles, Bref Cloud does not store AWS credentials.

You can also transparently review the permissions that Bref Cloud has in your account, adjust them (the IAM role lives in your account), or revoke access at any time by deleting the bref-cloud-connect stack from your account.

Why use a separate `BrefCloudAccessor` role?

The BrefCloudAccessor role is an additional layer of security: instead of directly granting the PHP application (Bref Cloud) access to your account, it jumps through an intermediate role (BrefCloudAccessor).

The reasons for this are:

We can very tightly restrict access to this role (principle of least privilege). For example Bref AWS account administrators (IAM users) do not have access to the BrefCloudAccessor role.
The PHP application is deployed often, but the BrefCloudAccessor role should almost never change. Separating those helps avoid accidental unwanted changes.

What permissions does the `BrefCloudAccess` role have?

The BrefCloudAccess role can deploy any CloudFormation stack, including IAM roles: in practice, it has administrator access to the AWS account. This is required to deploy applications that create their own IAM roles, queues, databases, etc. It can also read logs and metrics. You can review these permissions in the IAM role, in your account.

When a team member with the Write or Admin role, or a bot, runs bref deploy, the bref CLI receives temporary credentials of this role (valid 30 minutes) to run the deployment. Only give Write access to people you would trust with deploying to the AWS account.

You can also customize the permissions of the BrefCloudAccess role if you want to restrict it further. Of course, all Bref Cloud features may not work correctly in some cases if you restrict the permissions too much.

Updating the permissions

When new Bref Cloud features need new permissions, the “AWS accounts” page in Bref Cloud shows “permissions update available” next to the account. Click it to review the changes, then click “Update permissions”: Bref Cloud updates the bref-cloud-connect stack in your account. Updating the stack can overwrite the changes you made manually to the role’s permissions.

How does Bref Cloud know which role to assume?

When you connect your AWS account to Bref Cloud, the ARN of the BrefCloudAccess role is stored in Bref Cloud. This is how Bref Cloud knows which role to assume in your account.

A note about `ExternalId`

Bref Cloud follows AWS best practices and uses the ExternalId feature for cross-account access.

The ExternalId is a unique identifier that is passed by Bref Cloud when assuming the role. This identifier is configured when the role is created, and is checked by AWS when the role is assumed.

External IDs are randomly generated per Bref Cloud team and are stored encrypted in the Bref Cloud database.

This technique has the following benefits:

It ensures that only a specific Bref Cloud team can assume the role and access your account (protection against the “confused deputy” problem).
In case of an extreme security breach where the BrefCloudAccessor IAM role is compromised, the attacker would not be able to access customer AWS accounts (the ExternalId acts as an additional layer of security).
On top of that, the ExternalId being stored in the database means that the attacker would need to also compromise the database to get it, which is an additional layer of security.
On top of that, the ExternalId being stored encrypted means that the attacker would also need to compromise the encryption key to get it (stored separately from the code and the database), which is another additional layer of security.

Note that nothing is foolproof, but having multiple layers of security helps mitigate risks.

Self-hosted Bref Cloud

Self-hosting means running Bref Cloud inside your own AWS account. This is useful for companies that have strict security requirements and do not want to give access to a third-party service to their AWS account.

Self-hosting is available with the Enterprise plan: contact us .

When you self-host Bref Cloud, cross-account access happens as usual but the big difference is that access happens from an AWS account that you own to another AWS account that you own.

Frequently Asked Questions

Can I revoke Bref Cloud’s access to my AWS account?

Yes, you can revoke access at any time:

Delete the bref-cloud-connect CloudFormation stack in the us-east-1 region of your AWS account (or the IAM role, if you created it manually). Deleting only the role would leave the stack out of sync.
Remove the AWS account from the “AWS accounts” page in Bref Cloud.

How does Bref Cloud handle multi-account deployments?

If you need to deploy to multiple AWS accounts, you can connect each account to Bref Cloud separately. Each account will have its own BrefCloudAccess IAM role with appropriate permissions.

How often are temporary credentials refreshed?

Temporary credentials are only used for the duration of specific operations and are not stored. They are valid for 30 minutes (1 hour when you sign in to the AWS console from Bref Cloud).

Can I audit what actions Bref Cloud performs in my account?

You can enable AWS CloudTrail to log all actions made in your AWS account. This allows you to audit the actions performed by Bref Cloud.

Bref Cloud also keeps an audit log of the actions of your team members: deployments, commands, secrets, databases, AWS accounts, team members, etc. Team admins can see it, and export it, in the “Audit logs” page of the Bref Cloud dashboard.

Can I customize the permissions granted to Bref Cloud?

Yes, you can modify the permissions in the BrefCloudAccess IAM role to restrict what Bref Cloud can do in your AWS account. However, restricting permissions too much may prevent certain Bref Cloud features from working correctly. Feel free to reach out to Bref Cloud support if you need help with this.

Does Bref Cloud comply with my organization’s security requirements?

Bref Cloud follows AWS security best practices, including temporary credentials and cross-account access controls. For organizations with specific compliance requirements (like SOC2, HIPAA, etc.), you may want to consider the self-hosted option for complete control over the infrastructure.