|
| 1 | +--- |
| 2 | +title_tag: Configure OpenID Connect for Doppler | Pulumi ESC |
| 3 | +meta_desc: This page describes how to configure OIDC token exchange in Doppler for use with Pulumi |
| 4 | +title: Doppler |
| 5 | +h1: Configuring OpenID Connect for Doppler |
| 6 | +meta_image: /images/docs/meta-images/docs-meta.png |
| 7 | +menu: |
| 8 | + esc: |
| 9 | + name: Doppler |
| 10 | + parent: esc-configuring-oidc |
| 11 | + weight: 4 |
| 12 | +--- |
| 13 | + |
| 14 | +This document outlines the steps required to configure Pulumi to use OpenID Connect to authenticate with Doppler. OIDC |
| 15 | +in Doppler uses [service account identities](https://docs.doppler.com/docs/service-account-identities) to access |
| 16 | +Doppler resources. Access to the temporary credentials is authorized using identities that validate the contents of |
| 17 | +the OIDC token issued by the Pulumi Cloud. |
| 18 | + |
| 19 | +## Prerequisites |
| 20 | + |
| 21 | +* Your Doppler workplace must be on the Team or Enterprise plan in order to use service account identities. |
| 22 | +* You must be an admin of your Doppler workplace to create and configure service account identities. |
| 23 | + |
| 24 | +{{< notes type="warning" >}} |
| 25 | +Please note that this guide provides step-by-step instructions based on the official provider documentation which is |
| 26 | +subject to change. For the most current and precise information, always refer to |
| 27 | +the [official Doppler documentation](https://docs.doppler.com/docs/service-account-identities). |
| 28 | +{{< /notes >}} |
| 29 | + |
| 30 | +## Creating a Service Account |
| 31 | + |
| 32 | +To create a new service account, in the navigation pane of the [Doppler dashboard](https://dashboard.doppler.com): |
| 33 | + |
| 34 | +1. Select **Team**, **Service Accounts** and then click **New Service Account**. |
| 35 | +2. Provide a name for your service account (ex: `pulumi-esc-oidc-app`). |
| 36 | +3. Click **Create**. |
| 37 | +4. Select a **Role** for the service account or manually grant project access. |
| 38 | + |
| 39 | +## Add an Identity (OIDC Authentication) |
| 40 | + |
| 41 | +To add an identity to a service account: |
| 42 | + |
| 43 | +1. Navigate to the service account from **Team**, **Service Accounts** |
| 44 | +2. Click **New Identity**. |
| 45 | +3. Fill in the form fields as follows: |
| 46 | + * **Discovery URL:** `https://api.pulumi.com/oidc`. |
| 47 | + * **Audience:** This is different between Pulumi deployments and ESC. For Deployments this is only the name of your Pulumi organization. For ESC this is the name of your Pulumi organization prefixed with `doppler:` (e.g. `doppler:{org}`). |
| 48 | + * **Subject:** `pulumi:environments:org:<your-pulumi-org>:env:<your-project>/<your-environment>` (see more examples at the end of this section). |
| 49 | +4. Click **Create Identity**. |
| 50 | +{{< notes type="info" >}} |
| 51 | +For environments in the `default` project the audience will use just the Pulumi organization name. This is to |
| 52 | +prevent regressions for legacy environments. |
| 53 | +{{< /notes >}} |
| 54 | + |
| 55 | +After the Identity has been created, take note of the following details: |
| 56 | + |
| 57 | +* Identity ID |
| 58 | + |
| 59 | +This value will be necessary when enabling OIDC for your service. |
| 60 | + |
| 61 | +## Configure ESC for OIDC |
| 62 | + |
| 63 | +To configure OIDC for Pulumi ESC, create a new environment in the [Pulumi Console](https://app.pulumi.com/). Make sure |
| 64 | +that you have the correct organization selected in the left-hand navigation menu. Then: |
| 65 | + |
| 66 | +1. Click the **Environments** link. |
| 67 | +2. Click the **Create environment** button. |
| 68 | +3. Provide a project to create your new environment in and a name for your environment. |
| 69 | + * This should be the same as the identifier provided in the subject claim of your federated credentials. |
| 70 | +4. Click the **Create environment** button. |
| 71 | +5. You will be presented with a split-pane view. Delete the default placeholder content in the editor and replace it |
| 72 | + with the following code: |
| 73 | + |
| 74 | + ```yaml |
| 75 | + values: |
| 76 | + doppler: |
| 77 | + login: |
| 78 | + fn::open::doppler-login: |
| 79 | + oidc: |
| 80 | + identityId: <your-identity-id> |
| 81 | + environmentVariables: |
| 82 | + DOPPLER_TOKEN: ${doppler.login.accessToken} |
| 83 | + ``` |
| 84 | +
|
| 85 | +6. Replace `<your-identity-id>` with the value from the previous steps. |
| 86 | +7. Scroll to the bottom of the page and click **Save**. |
| 87 | + |
| 88 | +You can validate that your configuration is working by running either of the following: |
| 89 | + |
| 90 | +* `esc open <your-org>/<your-project>/<your-environment>` command of the [ESC CLI](/docs/esc-cli/) |
| 91 | +* `pulumi env open <your-org>/<your-project>/<your-environment>` command of the [Pulumi CLI](/docs/install/) |
| 92 | + |
| 93 | +Make sure to replace `<your-org>`, `<your-project>`, and `<your-environment>` with the values of your Pulumi |
| 94 | +organization, project, and environment file respectively. You should see output similar to the following: |
| 95 | + |
| 96 | +```json |
| 97 | +{ |
| 98 | + "doppler": { |
| 99 | + "login": { |
| 100 | + "accessToken": "dp.said.XXX..." |
| 101 | + } |
| 102 | + }, |
| 103 | + "environmentVariables": { |
| 104 | + "DOPPLER_TOKEN": "dp.said.XXX..." |
| 105 | + } |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +To learn more about how to set up and use the various providers in Pulumi ESC, please refer to |
| 110 | +the [relevant Pulumi documentation](/docs/esc/integrations/) |
| 111 | + |
| 112 | +## Subject claim customization |
| 113 | + |
| 114 | +You can [customize](/docs/esc/environments/customizing-oidc-claims/) the subject claim in the OIDC token to control |
| 115 | +which Pulumi environments or users are allowed to assume a given identity. This allows for more granular access control |
| 116 | +than the default organization-level permissions. |
| 117 | + |
| 118 | +This is done by configuring the `subjectAttributes` setting. It expects an array of keys to include in it: |
| 119 | + |
| 120 | +* `rootEnvironment.name`: the name of the environment that is opened first. This root environment in turn opens other |
| 121 | + imported environments |
| 122 | +* `currentEnvironment.name`: the full name (including the project) of the environment where the ESC login provider and |
| 123 | + `subjectAttributes` are defined |
| 124 | +* `pulumi.user.login`: the login identifier of the user opening the environment |
| 125 | +* `pulumi.organization.login`: the login identifier of the organization |
| 126 | + |
| 127 | +The subject always contains the following prefix `pulumi:environments:pulumi.organization.login:{ORGANIZATION_NAME}` and |
| 128 | +every key configured will be appended to this prefix. For example, consider the following environment: |
| 129 | + |
| 130 | +```yaml |
| 131 | +values: |
| 132 | + doppler: |
| 133 | + login: |
| 134 | + fn::open::doppler-login: |
| 135 | + oidc: |
| 136 | + identityId: <your-identity-id> |
| 137 | + subjectAttributes: |
| 138 | + - currentEnvironment.name |
| 139 | + - pulumi.user.login |
| 140 | +``` |
| 141 | + |
| 142 | +The subject will be |
| 143 | +`pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:project/development:pulumi.user.login:userLogin`. |
| 144 | +Note how the keys and values are appended along with the prefix. |
| 145 | + |
| 146 | +{{< notes type="warning" >}} |
| 147 | + |
| 148 | +If not customized, the subject claim has the following format by default: |
| 149 | + |
| 150 | +`pulumi:environments:org:<organization name>:env:<project name>/<environment name>` |
| 151 | + |
| 152 | +{{< /notes >}} |
| 153 | + |
| 154 | +{{< notes type="warning" >}} |
| 155 | + |
| 156 | +For environments within the legacy `default` project, the project will **not** be present in the subject to preserve |
| 157 | +backwards compatibility. The format of the subject claim when `subjectAttributes` are not set is |
| 158 | +`pulumi:environments:org:<organization name>:env:<environment name>`. If `currentEnvironment.name` is used as a custom |
| 159 | +subject attribute it will resolve to only the environment name (e.g. |
| 160 | +`pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:development:pulumi.user.login:personA`). |
| 161 | +Due to this it is recommended to move your environments out of the `default` project for best security practices. |
| 162 | + |
| 163 | +{{< /notes >}} |
| 164 | + |
| 165 | +## Subject claim example |
| 166 | + |
| 167 | +Here is an example of a valid, not customized subject claim for the `project/development` environment of the `contoso` |
| 168 | +organization: |
| 169 | + |
| 170 | +* `pulumi:environments:org:contoso:env:project/development` |
| 171 | + |
| 172 | +{{< notes type="warning" >}} |
| 173 | + |
| 174 | +If you are integrating Pulumi ESC with Pulumi IaC, the default subject identifier of the ESC environment will not work |
| 175 | +at this time. There is a [known issue](https://github.com/pulumi/pulumi/issues/14509) with the subject identifier's |
| 176 | +value sent to Doppler from Pulumi. |
| 177 | + |
| 178 | +Use 'subjectAttributes' to customize the subject identifier to work with Pulumi IaC. Alternatively, you can use this |
| 179 | +syntax: `pulumi:environments:org:contoso:env:<yaml>` when configuring the subject claim in your cloud provider account. |
| 180 | +Make sure to replace `contoso` with the name of your Pulumi organization and use the literal value of `<yaml>` as shown. |
| 181 | + |
| 182 | +{{< /notes >}} |
0 commit comments