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 Azure AD
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¶

Discovery Schedule¶

Configure automatic discovery:

1. Go to Settings > Rotation
2. Enable Scheduled Discovery
3. Set frequency (daily/weekly)
4. Save

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:

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
4. Use hint caching: Enable to speed up matching

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.

Scheduled Rotation¶

Set up automatic rotation for secrets approaching expiry:

1. Go to Settings > Rotation
2. Enable Auto-Rotation
3. Configure:
4. Days before expiry to rotate (e.g., 30)
5. Minimum confidence (e.g., HIGH only)
6. Notification settings
7. Save

Rotation Workflow¶

Step-by-Step¶

1. Initiate: User clicks Rotate or auto-rotation triggers
2. Generate: New secret created in Azure AD
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

Real-time Progress¶

Monitor rotation in real-time:

• WebSocket updates for progress
• Status per Key Vault update
• Error details if any step fails

Certificate Rotation¶

Certificate rotation renews one certificate (same key and thumbprint) and writes it to all matched and manual targets - including multiple certificates with different names in the same vault.

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.

Force Cleanup Early¶

Operators can complete cleanup without waiting:

1. Go to Automation > Rotation > History
2. Find the entry with cleanup pending
3. Use the cleanup action - the old credential is removed immediately, completing the grace period early and unblocking re-rotation. The new credential stays in place.

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¶

Exclusions¶

Exclude apps or secrets from rotation:

1. Go to Settings > Rotation > Exclusions
2. Add exclusion:
3. By App ID
4. By App name pattern
5. By secret name pattern
6. Save

Example Exclusions¶

• app-id:12345678-* - Exclude specific app
• name:legacy-* - Exclude apps with "legacy" prefix
• secret:do-not-rotate - Exclude secrets with specific name

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 login 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

When a credential nears its threshold (30 days), CertifyClouds raises the same expiry alert it uses for your own App Registration credentials.

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 works before trusting it (a real Microsoft Graph token acquisition), persists it, and only then retires the old one. There is no window in which CertifyClouds is left without a valid credential.

Permissions Required¶

Microsoft Graph API¶

Key Vault¶

Granting Permissions¶

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

1. Navigate to Azure AD > 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) - Enable hint caching for value matching - 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