Secret Rotation (PRO)¶

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 uses 6 signals to match App Registration secrets to Key Vault entries:

Confidence Scoring¶

Combined signals produce a confidence score:

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

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 secret can be deleted after 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

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

Permissions Required¶

Microsoft Graph API¶

Key Vault¶

Granting Permissions¶

# Add Graph API permissions to Managed Identity
az ad app permission add \
  --id $CLIENT_ID \
  --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions 1bfefb4e-e0b5-418b-a88f-73c46d2cc8e9=Role

# Grant admin consent
az ad app permission admin-consent --id $CLIENT_ID

# Grant Key Vault Secrets Officer
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

API Reference¶

Run Discovery¶

POST /api/automation/rotation/discover

List App Registrations¶

GET /api/automation/rotation/apps

Get Matches for App¶

GET /api/automation/rotation/apps/{app_id}/matches

Rotate Secret¶

POST /api/automation/rotation/rotate
Content-Type: application/json

{
  "app_id": "12345678-1234-1234-1234-123456789012",
  "secret_id": "secret-key-id",
  "expiry_days": 365,
  "update_key_vaults": true
}

Get Rotation History¶

GET /api/automation/rotation/history

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