Corporate Tenant Registry¶

Manage multiple Microsoft Entra ID tenants that belong to the same organisation. CertifyClouds discovers, monitors, and rotates credentials across all of them from a single deployment.

Overview¶

A typical enterprise spans more than one Entra ID tenant: a primary ("home") tenant for day-to-day operations and additional tenants for subsidiaries, acquired companies, geographic regions, or environment boundaries (dev / staging / production). The Corporate Tenant Registry lets you onboard those additional tenants so CertifyClouds can:

• Discover and monitor Key Vault secrets, certificates, and keys across every onboarded tenant
• Rotate App Registration credentials in any onboarded tenant
• Surface all assets in the unified inventory with a per-tenant badge
• Alert on expiring credentials regardless of which tenant they live in

Corporate tenants vs external tenants¶

Concepts¶

Home tenant¶

The tenant in which CertifyClouds itself is deployed. Its Managed Identity (or Service Principal) is the deployment credential. The home tenant is added to the registry automatically at first start; you cannot delete it. Scan, rotation, and sync for home-tenant assets use the deployment credential as before.

Onboarded tenant¶

Any additional Entra ID tenant you register in the Corporate Tenant Registry. Each onboarded tenant gets its own dedicated Service Principal (provisioned by the onboarding script) whose client secret is stored encrypted at rest. Credential operations on onboarded-tenant assets always use that tenant's own credential - they never reuse the home deployment credential.

Credential routing¶

Every Azure write operation resolves its credential at the point of execution:

• Home assets use the deployment credential.
• Onboarded-tenant assets use the per-tenant ClientSecretCredential, wrapped in a bounded wrapper that enforces a wall-clock timeout per token acquisition. Credentials are cached with tenant-scoped keys so SP rotation invalidates the cache automatically.

Before any write is executed, the platform verifies that the credential's actual token tid matches the intended tenant. A mismatch is a hard refusal - the write is never sent.

Prerequisites¶

• ENTERPRISE licence (the multi_tenant feature entitlement)
• Azure CLI (az) installed on the machine running the onboarding script
• jq installed (brew install jq on macOS, apt install jq on Debian/Ubuntu)
• Admin access in the target (onboarded) Entra tenant to create an App Registration and grant admin consent for Microsoft Graph permissions

Step 1: Provision the Service Principal (onboarding script)¶

Run onboard-corporate-tenant.sh (included in your CertifyClouds delivery package; contact [email protected] if your package predates it) in the target tenant to create the App Registration, Service Principal, client secret, and role assignments CertifyClouds needs.

Sign in to the target tenant¶

The Azure CLI creates App Registrations in the tenant of the current session. You must sign in to the target tenant before running the script:

az login --tenant <TARGET_TENANT_GUID> --allow-no-subscriptions

The script validates that your current session matches --tenant and refuses to run if they differ, preventing accidental provisioning in the wrong directory.

Preview first (no changes)¶

By default the script is a dry run - it prints every az command it would execute without making any changes:

On Windows, read Running from Windows before running the script.

./onboard-corporate-tenant.sh --tenant <TARGET_TENANT_GUID>

Review the output, then add --apply to actually provision:

./onboard-corporate-tenant.sh --tenant <TARGET_TENANT_GUID> --apply

Flags¶

Grants by mode¶

Admin consent for Microsoft Graph permissions¶

Application.Read.All (and Application.ReadWrite.All when --with-rotation is used) are application permissions that require tenant-wide admin consent from a Global Administrator. The script attempts to grant consent automatically. If your account lacks that role, it prints the portal steps to hand to an admin:

1. Azure Portal > Microsoft Entra ID > App registrations
2. Open the app (e.g. CertifyClouds Corporate Tenant Workload (Production))
3. Go to API permissions
4. Click Grant admin consent for [Tenant Name] and confirm

The Key Vault scan and subscription enumeration work without consent. App Registration discovery in the onboarded tenant requires consent before it returns results.

Script output¶

On a successful --apply run, the script prints the values to paste into the CertifyClouds UI:

  Tenant ID (GUID):     xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  Tenant domain:        yourcompany.onmicrosoft.com
  App (client) ID:      yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
  Client secret:        <secret value>
  Secret expires:       <date>

Key Vault firewalls on onboarded tenants¶

CertifyClouds can enumerate a Key Vault resource with Azure RBAC while still receiving data-plane 403 (ForbiddenByFirewall) responses when it tries to list secrets, certificates, or keys. If the vault firewall is off (properties.networkAcls.defaultAction is Allow, or the vault has no network ACLs), there is nothing to configure. If it is Deny, grant the CertifyClouds deployment a network path using one of the three options below. All three keep the vault firewalled to everyone else.

Which option to choose:

az keyvault network-rule add \
  --name <onboarded-vault> \
  --subscription <onboarded-subscription> \
  --subnet "/subscriptions/<home-sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>/subnets/<deployment-subnet>"

# find the deployment's stable egress IP (NAT gateway public IP; Container Apps: outboundIpAddresses)
az containerapp show --name <app> --resource-group <rg> --query properties.outboundIpAddresses
az keyvault network-rule add --name <onboarded-vault> --subscription <onboarded-subscription> --ip-address <egress-ip>/32

Step 2: Register the tenant in CertifyClouds¶

1. Go to Tenants in the left-hand navigation and open the Corporate tab
2. Click Add Tenant

3. Enter the values from the script output:

   Field	Value
   Tenant ID	Target tenant GUID
   Tenant Domain	e.g. yourcompany.onmicrosoft.com
   Display Name	A friendly name for the tenant
   Client ID	App Registration (client) ID
   Client Secret	Secret from the onboarding script

4. Click Test Connection to verify. A successful test confirms CertifyClouds can authenticate to the tenant.

5. Click Register Tenant to save.

Step 3: Run a scan¶

After registering a tenant, trigger an initial Key Vault scan:

• All tenants at once: go to Assets > Scan and click Run Scan. The scan runs across the home tenant and all active onboarded tenants sequentially.
• Via the API: POST /api/assets/discovery/scan with { "corporateTenantId": <id> } to scan a single onboarded tenant.

Discovered assets are tagged with their owning tenant. The unified inventory shows all assets together; filter by tenant using the tenant switcher in the header or the corporateTenantId filter on the Assets page.

Per-tenant scanning¶

The platform scans each onboarded tenant using that tenant's own Service Principal credential. The home subscription allow-list does not apply to onboarded-tenant scans - each onboarded tenant is scanned across all subscriptions visible to its Service Principal.

Assets inherit their tenant from their subscription: after a scan, each asset's corporate_tenant_id is set to match the subscription it lives in. This tag propagation is idempotent and only updates rows whose tag is stale.

Per-tenant rotation¶

Rotation for onboarded-tenant assets follows the same flow as home-tenant rotation (confirm dialog, real-time progress stream, grace window, history entry with a tenant badge), with the routing layer ensuring the correct credential is used:

1. The rotation engine resolves which tenant owns the operation's legs (vault, subscription, App Registration). If any leg belongs to an onboarded tenant, the routing resolves to that tenant's credential.
2. Before each Azure write, the token tid is verified to match the intended tenant. A mismatch is a hard refusal.
3. The rotation record is stamped with the resolved corporate_tenant_id so the history table reflects which tenant was written.

Cross-tenant operations (where rotation legs span more than one tenant) are refused. Each rotation job is single-tenant.

Tenant isolation model¶

Service Principal expiry¶

The onboarded tenant's Service Principal secret has a 2-year validity by default. The tenant card on Tenants → Corporate shows the expiry date alongside a status badge so you can see at a glance when renewal is due.

The Auto-rotate before expiry toggle uses the managed-secret monitor schedule to mint a new secret, verify it, save it, and retire the old one before expiry. If the toggle is off, set a calendar reminder before the expiry date; if the secret expires, scanning, discovery, and rotation for that tenant will fail until it is renewed by re-running the onboarding script with --rotate-secret --apply and updating the client secret in the tenant registration form in the UI.

Troubleshooting¶

Security best practices¶

1. Least privilege: use --with-rotation only if you need CertifyClouds to rotate credentials in that tenant. Discovery-only onboarding does not require write grants.
2. Rotation write grants are subscription-scoped: after onboarding, narrow them to a resource group or vault if your security policy requires least-privilege.
3. Monitor SP expiry: the onboarded tenant's SP secret expires in 2 years. The expiry date is shown on the tenant card. Set a calendar reminder and renew by re-running the onboarding script with --rotate-secret --apply, then updating the client secret in the tenant registration form.
4. az login --tenant <guid> is interactive when the target tenant enforces MFA or Conditional Access, so be ready to complete the sign-in in a browser or device prompt.
5. Re-running the onboarding script without --rotate-secret keeps the existing secret; a new secret is only minted on the first run or when you pass --rotate-secret.
6. Review access: periodically review the CertifyClouds App Registration in each onboarded tenant's Azure portal to confirm permissions remain as expected.

Related¶

• External tenants (Azure AD B2C) - monitor App Registration credentials in Azure AD B2C tenants
• Secret Rotation - rotation mechanics for Key Vault secrets and App Registrations
• Key Vault Scan - how CertifyClouds scans your Azure estate