Azure Service Principal

Doppler supports rotating Azure Service Principal client secrets. By rotating the client secret rather than the Service Principal itself, the Application (Client) ID and Tenant (Directory) ID remain consistent while the sensitive credential is regularly refreshed.

Requirements

• Understand the Doppler rotation methodology
• Azure AD (Entra ID) tenant with the ability to:
  • Create or access App Registrations
  • Assign Microsoft Graph API permissions
  • Manage application ownership

Overview

Doppler rotates Azure Service Principal client secrets using our issuer methodology. After you complete the rotated secret creation process, Doppler will issue the first client secret on the target application. At the defined frequency, Doppler will then issue a new client secret before revoking a previous client secret (reminder: there's always two).

Two Service Principals are involved in the rotation process:

• Managing Service Principal: authenticates with the Microsoft Graph API to perform rotation operations. Doppler authenticates as this SP either keylessly, via a federated credential, or with a client secret. A client secret used here is stored in the Doppler integration and is not rotated.
• Target Application: the app registration whose client secrets are rotated by Doppler.

The managing Service Principal must have the Application.ReadWrite.All Microsoft Graph API application permission, or Application.ReadWrite.OwnedBy and be an owner of the target application. This ensures Doppler can create and remove client secrets on the target app.

🚧

Client secret expiration

Azure requires an expiration date for client secrets (up to two years). Doppler sets each credential to expire after 366 days. Credentials are revoked on rotation, so this expiration should never be hit.

Configuration

There are four steps to configure Azure Service Principal rotation:

1. Configure the managing Service Principal in Azure
2. Authorize Doppler to act as that Service Principal
3. Create the integration in Doppler
4. Create the rotated secret in Doppler

Doppler supports two ways to authenticate as the managing Service Principal. Workload identity federation is recommended, since it leaves no credential stored in Doppler.

Configure the Managing Service Principal

The managing Service Principal authenticates with the Microsoft Graph API on behalf of Doppler. If you already have a Service Principal configured for Doppler, you can reuse it.

1. In the Azure Portal, navigate to App registrations
2. Select an existing app registration or create a new one to serve as the managing Service Principal
3. Under API permissions, add the following Application permission:
   • Microsoft Graph > Application.ReadWrite.All, or
   • Microsoft Graph > Application.ReadWrite.OwnedBy if the managing SP is an owner of the target application
4. Grant admin consent for the permission
5. From the managing SP's Overview page, note the Application (Client) ID and Directory (Tenant) ID

You'll authorize Doppler to act as this SP in Keyless Authentication or Client Secret Authentication below.

Make the Managing SP an Owner of the Target Application

If using the Application.ReadWrite.OwnedBy permission, the managing Service Principal must be added as an owner of the target application.

🚧

The Azure Portal's Owners UI only supports adding users, not service principals. You must use the Azure CLI to add a Service Principal as an owner.

Using the Azure CLI:

1. Get the Object ID of the managing Service Principal:

   Bash

   az ad sp show --id <managing-sp-client-id> --query id -o tsv

2. Add the managing Service Principal as an owner of the target application:

   Bash

   az ad app owner add --id <target-app-object-id> --owner-object-id <managing-sp-object-id>

3. Verify the owner was added:

   Bash

   az ad app owner list --id <target-app-object-id> --query "[].{displayName:displayName, id:id}" -o table

📘

If the managing SP and target application are the same (self-management), use the same application's Client ID and Object ID in the commands above.

workplace:<workplace-slug>:connection:<connection-id>

For rotated secrets, the Create the Connection in Doppler step above happens inside the Add Rotated Secret wizard described below. Once that wizard finishes, come back and add the federated credential.

Client Secret Authentication

Use this method if you'd rather give Doppler a client secret than set up federation.

1. In the Azure Portal, open the managing SP's app registration
2. Navigate to Certificates & secrets and create a new client secret
3. Save the Client Secret value — you'll paste it into Doppler below

Create the Rotated Secret in Doppler

1. Navigate to the Doppler config you would like to add a rotated secret to
2. Click the dropdown next to Add Secret and select Add Rotated Secret
3. In the modal, select Azure Service Principal
4. Choose how Doppler should authenticate:
   • Workload identity federation — Name your integration, then provide the managing SP's Client ID and Tenant ID
   • Client secret — Name your integration, then provide the managing SP's Client ID, Client Secret, and Tenant ID
5. Hit Next
6. Name your rotated secret. As you do, you'll get a live look at the three secrets that will be dynamically injected into your config.
7. Provide the Object ID of the target app registration (found on the app's Overview page)
8. Set the Interval at which you'd like your rotated secret instances to be rotated
9. Hit Next
10. The setup is complete and Doppler has created the first rotated secret instance, which is immediately available in your config

Injected Values

After creating the Azure Service Principal rotated secret, three individual secrets will be available in the config. Doppler ensures the active secret instance is returned when requested or synced. Each is prefixed with the name of your rotated secret.

For example, a rotated secret named AZURE_SP would have the following secrets injected:

• AZURE_SP_CLIENT_ID — the Application (Client) ID of the target app
• AZURE_SP_CLIENT_SECRET — the rotated client secret value
• AZURE_SP_TENANT_ID — the Directory (Tenant) ID of the target app