Secret Rotation (PRO + ENTERPRISE)¶

Rotation automates the rotation of App Registration secrets and certificates, updating all linked Key Vault secrets in one operation.

Overview¶

Rotation solves the credential rotation problem:

• App Registration discovery: Find all App Registrations in your tenant
• Secret matching: Link App Registration secrets to Key Vault entries
• One-click rotation: Generate new credentials and update vaults
• Rotation history: Complete audit trail of all rotations
• Exclusion patterns: Skip specific apps or secrets

How Rotation Works¶

The Problem¶

When an App Registration secret expires:

1. Generate new secret in Microsoft Entra ID
2. Find all Key Vaults storing the secret
3. Update each Key Vault secret
4. Update any applications using the secret
5. Verify everything works
6. Delete the old secret

Without CertifyClouds: Manual, error-prone, time-consuming

With CertifyClouds: One click, automated, audited

The Solution¶

App Registration                     Key Vaults
┌────────────────────┐     ┌─────────────────────────────┐
│ MyApp              │     │ kv-prod: myapp-secret       │
│ ├── Secret 1 ──────┼─────│ kv-dev: myapp-dev-secret    │
│ └── Secret 2       │     │ kv-staging: myapp-secret-v2 │
└────────────────────┘     └─────────────────────────────┘
                                        │
                                        ▼
                              CertifyClouds Rotation
                                        │
                                        ▼
                              1. Generate new secret
                              2. Update all KV entries
                              3. Verify
                              4. Audit log

App Registration Discovery¶

Initial Discovery¶

Run discovery to find all App Registrations:

1. Go to Automation > Rotation
2. Click Run Discovery
3. Wait for discovery to complete
4. View discovered apps with their secrets

What's Discovered¶

The results are listed under Automation → Rotation → Inventory.

Federated sign-in¶

An App Registration can let a workload sign in with a token from a trusted issuer instead of a client secret or certificate. This is a federated credential. Discovery reads them for the home tenant and onboarded corporate tenants, using the Application.Read.All permission it already has.

In the Inventory, set Show to Federated sign-in to list only the apps that have one. Each such row names the kind of workload: GitHub Actions, Azure DevOps, GitLab, Kubernetes, Managed identity or Other issuer. Expand the row to see each federated credential's subject, issuer and audiences.

An app that signs in this way usually no longer needs a client secret, and one left in place can still be used. Compliance rule FIC001 fails while such an app still holds a client secret; see App Registration rules.

Discovery Schedule¶

Rotation discovery runs on its own background worker. You need an admin account to change it.

1. Go to Settings → Advanced → Workers
2. Under Scan & Discovery Workers, find Rotation Discovery
3. Turn on Auto-discover
4. Pick how often it runs: every 6, 12, 24, 48 or 72 hours, or weekly

The change saves as soon as you make it. The card shows when the worker last ran and whether it is enabled. Non-admin users see the same card without the controls.

Enterprise Applications (monitor-only)¶

The same discovery run also inventories Microsoft Entra Enterprise Applications (service principals). Open Automation > Rotation > Enterprise Apps to see the results. This monitoring is available on STARTER, PRO, and ENTERPRISE.

CertifyClouds reads Application and Legacy service principals and records:

• SAML token-signing certificates, including which certificate Entra marks active
• Service-principal client secrets and non-SAML certificates
• Owners and an owner-less flag when the owner fetch completed
• Inactive SAML rollover certificates, kept in inventory for context

This uses the Application.Read.All permission already required for App Registration discovery, so Enterprise Application monitoring needs no new consent.

Owner detection counts every owner object returned by Microsoft Graph, including service-principal owners. Resolving user names and email addresses still requires the optional User.ReadBasic.All permission. CertifyClouds does not rotate any Enterprise Application credential.

Discovery status and its completion email include Enterprise Application counts and an ok, truncated, or failed scan status. A truncated or failed Enterprise Application scan makes the overall discovery run partial rather than green.

Expiry alerts¶

The STARTER+ alert source Enterprise Application credentials covers service-principal secrets, non-SAML certificates, and the active SAML signing certificate. Inactive rollover certificates remain visible in inventory but never alert. See Alerts & Notifications.

Compliance checks¶

The Enterprise Applications category is part of the Discovery product and is available on STARTER+. It includes:

• EA001: no expired active SAML signing certificate
• EA002: no active SAML signing certificate within the critical threshold
• EA003: every SAML Enterprise Application whose owners were fetched has at least one owner

How to roll over a SAML signing certificate¶

CertifyClouds monitors this process; it does not perform it.

1. In the Microsoft Entra admin centre, open the Enterprise Application and its Single sign-on > SAML Certificates settings.
2. Create a new signing certificate. Entra mints the certificate.
3. Give the new certificate or federation metadata to the service provider and confirm that it accepts the new signing key before the current certificate expires.
4. Set the new certificate as active in Entra and complete the service provider's SAML sign-in check.
5. Run discovery again to confirm the new active marker and expiry date in CertifyClouds.

Secret Matching¶

How Matching Works¶

CertifyClouds analyses multiple signals across naming, metadata, and Azure context to link App Registration secrets to Key Vault entries.

Confidence Levels¶

Each match is assigned a confidence level:

Confidence describes how strong the evidence is, not permission to write. CertifyClouds never overwrites an existing Key Vault entry until you approve that exact vault and item name: the first time a target is configured (and again if you remove it and add it back), the save is refused with a confirmation dialog listing every existing entry it would overwrite. Approval is recorded per destination, and removing or unconfirming a destination withdraws it.

Improving Matches¶

To improve matching accuracy:

1. Use consistent naming: {app-name}-client-secret
2. Add tags: app-id, app-name tags on KV secrets
3. Store App ID: Include App ID in secret name or tags

Running Rotation¶

Single Secret Rotation¶

1. Go to Automation > Rotation
2. Find the App Registration
3. Click Rotate on the target secret
4. Review:
5. Linked Key Vault secrets (what will be updated)
6. New expiry date
7. Confidence level
8. Click Confirm Rotation
9. Monitor progress

Bulk Rotation¶

Rotate multiple secrets at once:

1. Select multiple apps/secrets
2. Click Rotate Selected
3. Review all affected Key Vaults
4. Confirm

Managing Targets¶

Manage Targets edits which Key Vault entries a record updates. Removing a target is staged: the row is struck through with an Undo option, and nothing is deleted until you click Save. Re-adding a destination you removed asks for the overwrite confirmation again, the earlier approval does not carry over.

A target that a replication keeps in sync from an item in another vault is a copy: rotating only the copy would be undone by the next sync. The target is marked Target is a copy and the row names the item it is copied from. You can still save, but Rotate now stays off until you add that source item as a target too (the Add button on the row does it), or remove the copy. A source item that another app registration already rotates cannot also be added here: the row names that app and has no Add button, so remove the copy or free the source item from the other app.

Entra External ID records upgraded from an earlier CertifyClouds release have their certificate targets' legacy approvals cleared: automatic rotation pauses and the queue shows Confirm target until you approve the listed certificate destinations again.

Scheduled Rotation¶

Automatic rotation is three separate controls. All of them have to line up before a credential rotates on its own.

1. Turn the rotation worker on (admin only). Go to Settings → Advanced → Workers, find Rotation Worker under Automation Workers, enable it, and choose how often it checks: every 30 minutes, 1, 2, 4, 6, 12 or 24 hours. This is the process that performs unattended rotations. Without it, only Rotate Now works.

2. Enable auto-rotate for the individual records. Open Automation → Rotation → Queue. Each row has an Auto toggle. The worker only touches records that are enabled and have a confirmed, currently live discovered match. A record wired only to a manual destination shows Auto waits for a confirmed match and rotates only through Rotate now. The queue's auto and manual filters count records with this toggle on and off, respectively.

3. Set the lead time. Open a record's Configure Rotation and set Rotate N days before expiry (1 to 365). New records inherit the default from Settings → Advanced → Automation (Default rotation lead time, 30 days out of the box), and each record can override it.

The worker skips a record whose App Registration is at its credential limit (the queue shows At credential limit), because the rotation would be refused. Expiry alerts for it keep firing.

Rotation notifications are not configured here. They come from your alert rules in Settings → Alerts.

Rotation Workflow¶

Step-by-Step¶

1. Initiate: User clicks Rotate or auto-rotation triggers
2. Generate: New secret created in Microsoft Entra ID
3. Update Key Vaults: All matched secrets updated
4. Verify: Confirm new values are accessible
5. Audit: Log rotation details
6. Notify: Send success/failure notification
7. Cleanup: Old credential removed automatically after the grace period, once its copies have the new value (see Waiting for copies)

Real-time Progress¶

Monitor rotation in real-time:

• Live progress for each step
• Status per Key Vault update
• Error details if any step fails

Certificate Rotation¶

Certificate rotation creates one new certificate and writes that same certificate to all matched and manual targets, including several certificates with different names in the same vault. The new certificate keeps the subject, key type and other settings of the one it replaces, with a new key and thumbprint, and CertifyClouds adds it to the App Registration.

Key Vault auto-renewal stays off. A certificate CertifyClouds rotates for an App Registration never keeps Key Vault's own auto-renewal, on the original or on any copy in another vault. If Key Vault renewed it, the new certificate would not be on the App Registration, and every app signing in with it would fail. CertifyClouds' rotation renews it instead. Where auto-renewal was on, the rotation changes it to emailing the certificate's contacts before it expires. For the same reason, Turn on auto-renew is not offered on these certificates.

The run page's Certificate section shows where the new certificate's settings came from, its issuer, and for each copy whether Key Vault renewal was turned off. If a copy's renewal could not be turned off, the run finishes with a warning naming the vault: check that CertifyClouds can update certificates there (see Azure Permissions), then rotate again.

CA-issued certificates¶

On PRO, a manual rotation of a certificate that a certificate authority (CA) issued renews it through that CA instead of replacing it with a self-signed one:

• A CA connected to Key Vault: Key Vault orders the new certificate. You confirm the paid order before the rotation starts.
• Any other CA: you create a certificate request on the renewal page, send it to your CA, and upload the signed certificate there (see Certificate Renewal).

In the queue, such a certificate's button says Renew instead of Rotate now, with a line saying whether your CA signs the new certificate or Key Vault orders it. This comes from what the last scan stored, so it can lag a change made in Azure since; the confirmation dialog checks again before anything starts.

While a renewal is waiting, nothing else can rotate that certificate, including Replace with self-signed. Its queue row reads Waiting for renewal with an Open renewal button that goes straight to the renewal page, where you upload the signed certificate or cancel the renewal.

The run shows Waiting for renewal, the current step (Waiting for CA, Waiting for signed certificate or Adding to App Registration) and a link to the renewal. The current certificate stays in use until the new one is ready. CertifyClouds then adds the new certificate to the App Registration and writes it to every Key Vault target, creating it in a target vault that does not hold the certificate yet.

If a target vault cannot take the new certificate, the run page names the vault and the reason, for example a deleted certificate with the same name that can still be recovered (recover or purge it in Azure). CertifyClouds keeps trying and finishes once the vault accepts it; Resume adding to App Registration on the renewal page tries again straight away.

After the grace period the old certificate is removed from the App Registration and its old versions in the other target vaults are switched off, as for any certificate rotation. Roll back on the renewal restores the previous certificate and puts the App Registration back.

When rotation refuses a certificate¶

Replacing a CA certificate with a self-signed one. In a manual rotation, an admin may choose Replace with self-signed. CertifyClouds then replaces the CA-issued certificate with a self-signed one on the same subject. Any client that trusts the CA's chain may then fail to connect, so check that first. The replacement is recorded in the audit log.

Grace Period, Cleanup, and Rollback¶

After a successful rotation the old credential is not removed immediately. It stays valid for the configured grace window (default 24 hours, configurable in Settings > Advanced), giving anything still using the old value time to pick up the new one.

Automatic Cleanup¶

When the grace window elapses, a background worker removes the old credential automatically. History entries show a pending indicator until cleanup completes.

Waiting for copies¶

CertifyClouds updates the copies of what a rotation wrote (in AWS, Google Cloud, or another Key Vault by replication). If a copy does not have the new value yet when the grace window ends, the old credential is kept, so apps that read that copy keep working. It is retired on its own once every copy CertifyClouds manages has the new value.

• The wait is limited: 72 hours after the rotation by default. An admin can change it in Settings → Advanced → Automation. When the limit is reached, the old credential is retired anyway and the run records which copies still had the old value. Set it to 0 to never wait; the run page then warns about copies that still use the old credential.
• A paused copy holds retirement too, because resuming it copies the new value.
• A copy that is excluded from sync or no longer matched does not hold it, but the run page still lists it.
• A rollback of the run that did not finish holds retirement with no time limit, because it may have put the old value back in Key Vault. It clears when a retried rollback finishes, or when an admin uses Retire now.

Copies on the run page¶

Open a run from Automation → Rotation → History to see its page. The Copies card lists every copy of what the rotation wrote, including copies of a Key Vault copy (an AWS or Google Cloud copy of a replica shows "via Key Vault ..."), and where each one stands:

Admins can run Sync now on a copy from the card. The card also says whether the old credential is being kept for its copies, and until when.

Retire Now¶

An admin can retire the old credential before cleanup is due:

1. Go to Automation → Rotation → History and open the run
2. Click Retire now
3. The old credential is removed immediately, ending the grace period early and unblocking re-rotation. The new credential stays in place.

If copies still use the old credential, the dialog lists them, and you must tick I understand these copies still use the old secret (or certificate) first. Apps that read those copies fail until they are updated. If a rollback of the run did not finish, you must also tick I understand the rollback did not finish. Retiring early is recorded in the audit log.

Rollback¶

While cleanup is still pending, a rotation can be rolled back from History: the new credential is removed and the previous one is restored, reverting matched Key Vault entries to their prior values.

• Available for corporate App Registration rotations only
• Only while the grace-period cleanup is still pending
• Secret rotations need at least one matched Key Vault secret to revert; manual-target-only rotations cannot be rolled back

Credential Ownership¶

Each rotation record can carry an optional owner (name and email):

• Set the owner when editing a rotation record
• On rotation, the Key Vault entry is tagged with certifyclouds-owner and certifyclouds-owner-email
• Owners receive owner-scoped copies of rotation and expiry alert emails for their credentials - see Alerts

Rotation Settings¶

Configuration Options¶

The first five settings are in Settings → Advanced → Automation. The last one is not in the app: a deployment administrator sets it as an environment variable.

Keeping a credential out of automatic rotation¶

There is no pattern-based exclusion list for rotation. Exclusion is per record: open Automation → Rotation → Queue and turn the record's Auto toggle off. The toggle only governs automated rotation: the worker skips disabled records. Rotate now and the rotation API still work when the record is otherwise ready, for both corporate and External-tenant secrets and certificates. All other gates still apply, including acknowledged targets, credential validity, concurrent rotation, grace-period cleanup, and quota. A ready record with Auto off shows Ready with the reason waits for Rotate now; with Auto on the reason says how many days before expiry it rotates. Either way it ends with whether the row is wired to a manual target or a discovered match; the vault itself is named in the Key Vaults column.

Pattern-based exclusions exist only for multi-cloud sync. See Exclusions on the sync page.

Rotating CertifyClouds' Own Credentials¶

CertifyClouds authenticates to your Microsoft Entra tenant using its own credentials: the service principal secret used for B2C discovery, and the application secret used for SSO sign-in. Like any credential these expire, and if they lapse, discovery or SSO sign-in stops working.

CertifyClouds monitors both credentials and can rotate them for you.

Expiry monitoring¶

A background monitor reads the live expiry of each credential from Microsoft Graph and shows it in Settings:

• B2C discovery secret on each B2C tenant card
• SSO application secret on the SSO configuration panel

Settings → Access also shows each tenant connection's secret expiry (admins only).

When a credential nears its threshold (30 days), CertifyClouds raises the same expiry alert it uses for your own App Registration credentials. It warns admins even when no alert rule covers these credentials; see CertifyClouds' own secrets.

Automatic and manual rotation¶

Rotation is opt-in per credential:

• Auto-rotate before expiry: toggle on, and CertifyClouds rotates the credential automatically before it expires.
• Rotate now: rotate immediately at any time.

Each rotation mints a new credential, verifies it, persists it, and only then retires the old one. CertifyClouds keeps the existing credential until the new one is stored, so a failed rotation leaves the working credential in place.

Verification differs by credential, and this matters when you are responding to a leak:

• Discovery service principal secrets (B2C, Entra External ID, corporate tenants) are verified by acquiring a real Microsoft Graph token with the new secret.
• The SSO application secret cannot be tested that way, because signing in needs a person. CertifyClouds checks that the new secret is on the application, and then waits for a successful SSO sign-in using the new secret before it will remove the previous one. A successful Rotate now is therefore not proof that sign-in works: sign in once to confirm it.

Retiring the previous secret¶

Where the previous secret is removed later rather than immediately (Entra External ID and SSO), it stays valid for a grace period, 24 hours by default, configurable in Settings → Advanced → Automation, so anything still holding it keeps working. The managed-secret monitor runs daily by default (its interval is configurable in Settings → Advanced → Workers) and removes the predecessor on its next run once the grace period has passed, and, for SSO, once a sign-in with the new secret has succeeded. Settings shows when removal is due and why a removal is being held back.

Retire previous secret now bypasses the grace timer only. It does not bypass the SSO sign-in requirement, and it will refuse, telling you which keys it kept and why, when the secret is still the current credential of another CertifyClouds connection on the same application, or another connection on that application still needs it.

Permissions Required¶

Microsoft Graph API¶

Key Vault¶

Granting Permissions¶

Grant the required Graph API permissions via the Azure Portal or CLI:

1. Navigate to Microsoft Entra ID > App registrations > Your app > API permissions
2. Add Application.Read.All and Application.ReadWrite.All (Application type) from Microsoft Graph
3. Click Grant admin consent

Grant Key Vault access via RBAC:

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Key Vault Secrets Officer" \
  --scope /subscriptions/{sub-id}

Rotation History¶

View all rotation events:

1. Go to Automation > Rotation
2. Click History tab
3. Filter by:
4. Date range
5. App name
6. Status (success/failed)

History Entry Details¶

Each entry includes:

• Timestamp
• App Registration
• Secret rotated
• Key Vaults updated
• New expiry date
• Actor (user or system)
• Status and any errors

Edits to rotation records are also written to the audit log with a human-readable before / after summary of what changed.

API access¶

Rotation endpoints are listed in API Endpoints; exact request and response shapes are in your deployment's /docs.

Troubleshooting¶

"No matches found"¶

Cause: Can't link App Registration secret to Key Vault.

Fix: - Add tags to Key Vault secrets (app-id, app-name) - Use consistent naming conventions

"Insufficient permissions"¶

Cause: Missing Graph API or Key Vault permissions.

Fix: - Grant Application.ReadWrite.All Graph permission - Grant Key Vault Secrets Officer role - Ensure admin consent is granted

"Rotation failed - Key Vault update error"¶

Cause: Can't update specific Key Vault.

Fix: - Check Key Vault permissions - Verify Key Vault is not soft-deleted - Check network access to Key Vault

"Low confidence matches"¶

Cause: Naming conventions don't align.

Fix: - Add explicit tags linking app to secrets - Rename secrets to include App ID - Review and manually verify matches

Best Practices¶

1. Run discovery first: Always start with discovery before rotation
2. Verify matches: Review low/medium confidence matches before rotating
3. Start with HIGH confidence: Only auto-rotate HIGH confidence matches
4. Test in non-prod: Validate rotation process in staging first
5. Monitor alerts: Set up notifications for rotation events
6. Keep grace period: Don't delete old secrets immediately
7. Document exclusions: Record why specific apps are excluded