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. This SP's credentials are stored in the Doppler integration and are 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 three steps to configure Azure Service Principal rotation:

1. Configure the managing Service Principal in Azure
2. Create the integration in Doppler
3. Create the rotated secret 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. Navigate to Certificates & secrets and create a new client secret for the managing SP. Save the Client Secret value — you will need it when creating the Doppler integration
6. From the managing SP's Overview page, note the Application (Client) ID and Directory (Tenant) ID

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.

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. Name your integration and provide the managing Service Principal credentials:
   • Client ID: the Application (Client) ID of the managing SP
   • Client Secret: the client secret value of the managing SP
   • Tenant ID: the Directory (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