> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Account

> Cloud account mappings to AWS, Azure, and GCP. Covers integration methods, role configuration, and credential management for cloud provider access.

## Overview

A **cloud account** establishes a secure integration between your [org](/reference/org) and an external cloud provider. When creating a cloud account, you are guided to create a provider-side bridge role or service principal with minimum access permissions. This bridge identity allows Control Plane to securely manage and query cloud resources on behalf of your [org](/reference/org).

Cloud accounts are scoped to an [org](/reference/org) and are used in conjunction with [identities](/reference/identity) to set up [cloud access](/reference/identity#cloud-access-universal-cloud-identity) rules.

Your [workload](/concepts/workload) can then be associated with an [identity](/reference/identity) and will have access to permitted cloud provider resources without additional configuration.

For example, if an application uses AWS S3 for storage and Azure Cosmos DB for its database, a workload can access both services regardless of the [location](/reference/location) where the workload is deployed. The [workload](/concepts/workload) interacts with each service as if it were directly connected, while the [identity](/reference/identity) handles secure routing and credential exchange transparently.

## Create a Cloud Account

See the [Create a Cloud Account](/guides/create-cloud-account) guide for setup instructions.

## AWS Details

* Cloud Account Creation

  * When registering a cloud account targeting AWS, your AWS administrator must create a new AWS role (named `cpln-ORG_NAME`) with the following policies:
    * A `cpln-connector` policy granting permissions to create and manage IAM roles.
    * `ReadOnlyAccess` policy for read-only access to AWS services and resources.
  * A "trust relationship" must be configured to allow Control Plane to assume this role.

* Identity Creation

  * When an [identity](/reference/identity) targets AWS, Control Plane creates an IAM role with least-privilege permissions for the requested services.
  * When a [workload](/concepts/workload) requests AWS access via its [identity](/reference/identity), Control Plane issues temporary credentials by assuming the IAM role and injecting them into the [workload](/concepts/workload) at runtime.

* Removing an AWS Cloud Account
  * If you no longer require Control Plane to create identities targeting AWS:
    * Delete all cloud access rules targeting AWS from existing workload [identities](/reference/identity). This will delete any associated roles.
    * Delete the cloud account.
    * Your AWS administrator will need to remove the `cpln-connector` policy and the `cpln-ORG_NAME` role.

## Azure Details

When registering an Azure cloud account, you can choose between the following integration methods:

* [Azure SDK](#azure-sdk)
  * Access tokens are minted using an Azure service principal.
* [Azure Connector](#azure-connector)
  * An [Azure Function App](https://azure.microsoft.com/en-us/services/functions/)
    acts as a bridge that calls internal Azure APIs to obtain access tokens.

<Tip>
  During Azure cloud account setup, credentials generated via Azure CLI are securely stored and used by Control Plane to provision identities and manage resources. These credentials are uploaded and stored securely as an [Azure-SDK secret](/reference/secret#azure-sdk) or [Azure-Connector secret](/reference/secret#azure-connector) and can be viewed by clicking `Secrets` from the left menu in the console after creating an Azure cloud account.

  If you don't have the Azure CLI installed locally, you can run the commands in [Azure Cloud Shell](https://shell.azure.com/bash) — a browser-based shell with `az` preinstalled and authenticated against your signed-in account.
</Tip>

### Azure SDK

* Cloud Account Creation
  * When registering a cloud account targeting Azure using the Azure SDK, an Azure service principal is created by your Azure administrator using the Azure CLI. The output of the Azure CLI command contains credentials that are uploaded, stored securely, and assigned to the cloud account.
  * The name of this service principal is the name of your [org](/reference/org) prefixed with `cpln-` (i.e., cpln-ORG\_NAME).
  * The only Azure API permission required by this principal is `Application.ReadWrite.OwnedBy` (which belongs to the Microsoft Graph API).
  * By granting this permission, the cloud account can create and manage app registrations and query available Azure scopes and roles during the creation of an [identity](/reference/identity).

<Info>
  The permissions `Application.ReadWrite.OwnedBy` "allows the app to create other applications, and fully manage those applications (read, update, update application secrets and delete), without a signed-in user. It cannot update any apps that it is not an owner of".

  For every [identity](/reference/identity) created, Control Plane creates an app registration, generates short-lived credentials, and injects them into your [workload](/concepts/workload) using the native cloud provider identity interface. Regardless of where your workload is running, Control Plane conveys the identity information correctly to the consumed services. Control Plane mints tokens for the [identity](/reference/identity) bound to the workloads.
</Info>

* Identity Creation

  * When creating an [identity](/reference/identity), [cloud access](/reference/identity#cloud-access-universal-cloud-identity) rules targeting Azure can define the minimum access needed by the identity. When the [identity](/reference/identity) is saved in the console, the Azure cloud account uses the service principal to create a new app registration with the configured access.
  * Any [workload](/concepts/workload) can be configured to use this [identity](/reference/identity) and will have access to the defined resources.

* Expired / Compromised Credentials

  * If the service principal credentials assigned to the cloud account expire or have been compromised, perform the following:

    * From the Azure portal:
      * Click `Azure Active Directory` and click `App registrations` in the left menu.
      * Click `All applications` and then click the app registration named `cpln-ORG_NAME`.
      * Click `Certificates & secrets` and then click `New client secret` and follow the wizard.
      * Copy the value of the new secret to the clipboard.
      * Delete the old secret.
    * From the Control Plane console:
      * Click `Secrets` in the left menu and select the `azure-sdk` secret that belongs to the cloud account (it will be named `CLOUD_ACCOUNT_NAME-access`).
      * Click the `Edit Data` button and then click the eye icon.
      * Update the `clientSecret` property with the value of the new secret by pasting it from the clipboard.

  * Until a valid secret value has been updated, Control Plane will not be able to manage workload [identities](/reference/identity).

* Removing an Azure Cloud Account

  * If you no longer require Control Plane to create identities targeting Azure:

    * Delete all cloud access rules targeting Azure from existing workload [identities](/reference/identity). This will delete any associated app registrations.
    * Delete the cloud account.
    * Delete the [azure secret](/reference/secret#azure-sdk) that was mapped to the cloud account (named `CLOUD_ACCOUNT-access`).
    * Your Azure administrator will need to delete the service principal from Azure by running the following Azure CLI command:

    ```bash theme={null}
    az ad sp delete --id http://cpln-ORG_NAME
    ```

### Azure Connector

* Cloud Account Creation

  * When registering a cloud account targeting Azure using the console, your organization's Azure administrator will use the Azure CLI to perform the following:
    * Create an `Azure Function App` using an existing resource group and storage account.
    * Download the Control Plane Azure connector code.
    * Deploy the code to the function app.
    * Obtain the URL of the deployed function.
    * Obtain the code/key of the deployed function.
  * After the registration is completed, a secret of type [azure-connector](/reference/secret#azure-connector) will be created. This secret can be reused to create another cloud account (using the same Function App) or if an existing cloud account was inadvertently deleted.

* Functionality

  * The Function App that is deployed has a function called `iam-broker`. This function is called by Control Plane to obtain and inject the access token on behalf of the calling workload.
  * The Function App is set as an `Owner` of the subscription. This role assignment is needed to create the managed identities.

* Identity Creation

  * When an [identity](/reference/identity) is created targeting Azure resources, a managed identity is assigned to the function so that the function can act on its behalf. This [identity](/reference/identity) has only the minimum permissions required to access the targeted services. When an [identity](/reference/identity) is assigned to a [workload](/concepts/workload) that requests access to an Azure resource, Control Plane obtains a temporary access token that impersonates the roles and injects it into the [workload](/concepts/workload), granting it access.

* Pricing

  * The Function App runs as a managed service and is subject to charges against your Azure subscription.
  * See the [Azure Function Pricing](https://azure.microsoft.com/en-us/pricing/details/functions/)
    page to view current pricing.

* Compromised Code

  * If the Function App code has been compromised, perform the following:

    * From the Azure portal:
      * In the search bar, enter `Function App` and click the first result.
      * Click the app to update and click `Functions`.
      * Click `iam-broker` and then click `Function Keys`.
      * For the `default` Function Key, click `Renew key value`. A confirmation modal will be displayed, click `Renew`.
      * After the new key has been generated, click the link `Hidden value. Click to show value`.
      * Copy the value of the new code to the clipboard.
    * From the Control Plane console:
      * Click `Secrets` in the left menu and select the `azure-connector` secret that belongs to the cloud account (it will be named
        `CLOUD_ACCOUNT_NAME-access`).
      * Click the `Edit Data` button and then click the eye icon.
      * Update the `Code` property with the value of the new code by pasting it from the clipboard.

  * Until a valid code has been updated, Control Plane will not be able to manage workload [identities](/reference/identity).

* Removing an Azure Cloud Account

  * If you no longer require Control Plane to create identities targeting Azure:

    * Delete all cloud access rules targeting Azure from existing workload [identities](/reference/identity). This will delete any user assigned identities.
    * Delete the cloud account.
    * Delete the [azure connector secret](/reference/secret#azure-connector) that was mapped to the cloud account (named `CLOUD_ACCOUNT-access`) if it is not being used by another cloud account.
    * Your Azure administrator will need to delete the Function App from the Azure portal or by running the following Azure CLI command:

    ```bash theme={null}
    az functionapp delete --name FUNCTION_APP_NAME --resource-group AZURE_RESOURCE_GROUP
    ```

## GCP Details

* Cloud Account Creation

  * When registering a cloud account targeting GCP, your GCP administrator will add the Control Plane GCP service account as a member of your GCP account with the following roles:
    * `Viewer`
    * `Project IAM Admin`
    * `Service Account Admin`
    * `Service Account Token Creator`
  * The Control Plane GCP service account is in the format: `cpln-ORG_NAME@ENV.iam.gserviceaccount.com`.

* Identity Creation

  * When an [identity](/reference/identity) is created targeting GCP, Control Plane creates a new service account in your GCP account with the minimum permissions required to access the targeted services.
  * When a [workload](/concepts/workload) assigned an [identity](/reference/identity) requests credentials to access GCP services, Control Plane obtains a temporary access token that impersonates the service account and injects it into the [workload](/concepts/workload), granting it access.
  * If the [identity](/reference/identity) connects with a particular GCP service, the Control Plane GCP service account needs the `Admin` role for that service.
    * For example, if the [identity](/reference/identity) uses Cloud Storage, the `cpln-ORG_NAME@ENV.iam.gserviceaccount.com` service account needs the `Storage Admin` role. Adding this role allows Control Plane to grant a temporary access token to the workload when reading from or writing to a storage bucket.
    * Control Plane cannot assign roles similar to `Compute Network User` unless `Compute Admin` is assigned to the `cpln-ORG_NAME@ENV.iam.gserviceaccount.com` service account.

<Tip>
  If your workload [identities](/reference/identity) use many GCP services, it may be easier to grant the `cpln-ORG_NAME@ENV.iam.gserviceaccount.com` service account the `Owner` role instead of granting the `Admin` role for each service.
</Tip>

* Removing a GCP Cloud Account
  * If you no longer require Control Plane to create identities targeting GCP:
    * Delete all cloud access rules targeting GCP from existing workload [identities](/reference/identity). This will delete any associated service account.
    * Delete the cloud account.
    * Remove the Control Plane user from your GCP account.

## Permissions

The permissions below are used to define [policies](/reference/policy) together with one or more of the four
[principal types](/concepts/access-control):

| Permission | Description                    | Implies                                    |
| :--------- | :----------------------------- | :----------------------------------------- |
| browse     | Browse account contents        | view                                       |
| create     | Create new cloud accounts      |                                            |
| delete     | Delete existing cloud accounts |                                            |
| edit       | Modify existing cloud accounts | view, browse                               |
| manage     | Full access                    | browse, create, delete, edit, manage, view |
| view       | Read-only access               |                                            |

## Access Report

Displays the permissions granted to principals for the cloud account.

## CLI

To view the CLI documentation for cloud accounts, see the [Cloud Account CLI reference](/cli-reference/commands/cloudaccount).