Skip to main content

Cloud

Onboard an Azure Cloud Tenant

This topic explains how to onboard an Azure tenant. Onboarding an Azure tenant allows you to connect all the subscriptions and resources under the tenant with Cloud. Running the PowerShell script for Azure Tenant onboarding creates a new Entra ID application with the tenant scope, although this can be done manually on the Azure Portal. This service principal allows Cloud to retrieve subscriptions and resources under the given tenant. After the Azure Entra ID application is created and the required Reader permission are set at the tenant scope, the PowerShell script automatically sends the necessary credentials (Client Id and Client Secret), although you can invoke the API via a PowerShell script to send them back to Cloud. These credentials are required to communicate with your Azure tenant.

Prerequisites

  • In Azure, you must copy the parent management group id (tenant id). It can be found under the Management Groups. You must provide it in the first step of the onboarding wizard.

  • The user onboarding the tenant must have Owner permissions or the User Access Administrator Role for assigning the Reader Role at the Tenant scope to complete the Azure Entra ID App registration

  • You must download the newly created Cloud Service Account or have access to the credentials of the existing Cloud Service Account

Onboard a Tenant

Connect to Azure with the Wizard

  1. If this is the first time you are logging in, click + Azure on the Onboarding page to onboard your first account.

  2. If you've already onboarded other accounts, choose Onboarding from the left navigation. The Onboarding page appears. Click +Add Azure at the top of the page.

  3. The Add Azure Cloud Tenant wizard starts and displays the first step: Connect to Azure

  4. Provide the following information about your Azure account:

    • Name: You specify a name for the account; this name is what will appear in Cloud. The name should be descriptive so that you can easily identify it in Cloud.

    • Tenant ID: Paste the parent management group ID that you copied from Azure.

    Note

    The wizard contains the following toggles:

    • A toggle to enable all member subscriptions along with the tenant. If you want to onboard only some subscriptions in the tenant, set this toggle to No. Then go to the Onboarding page to onboard those subscriptions individually.

    • A toggle to specify the type of access Cloud will have to your Azure tenant and the subscriptions in it. Choose Yes to grant the Illumio Cross Account Role permission to view your Azure tenant resources and to apply policy to them. Choose No to provide the Illumio Cross Account Role read-only access. To view the permissions you are granting Cloud to your Azure tenant, click Download Permissions.

The wizard advances to step two: Set up Access

Setup Access with the Wizard

Use the following steps to set up access.

  1. Select a service account that you want to use or create a new one. Make sure to download the credentials, as they will be needed for the callback API to return the Azure Entra ID app credentials back to Cloud.

  2. Enter the ServiceAccountToken in the appropriate field.

  3. The Set up Access step includes a field containing a PowerShell command to run the illumio-init.ps1 script in Azure. Illumio securely hosts the script so that it can run during the onboarding process. Run the PowerShell command in the Azure portal. This creates a new Entra ID application with the tenant scope, using the tenant ID you entered in the first step of the wizard.

  4. Ensure that all fields are completed like that shown in the following screen capture.

    azure-tenant-setup-fields.png

  5. In the Confirm and Save part of the wizard, review the details and click Save and Confirm.

Manually Create an Azure Entra ID App and Assign the Reader RBAC Role

If you did not use the PowerShell command as described above, use the following steps to perform the necessary work manually.

  1. In a new browser window, open your Azure portal.

  2. Create the Azure Entra ID App registration as mentioned in the step here: https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#register-an-application-with-microsoft-entra-id-and-create-a-service-principal. Skip the redirect Uniform Resource Identifier (URI) in this step.

  3. Once the Entra ID App registration is created, create a new client secret as documented in these steps: https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret

  4. Once the Entra ID App and secret are created, assign the Reader RBAC role to the App at the tenant scope: https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#assign-a-role-to-the-application

  5. Ensure that the role is assigned at the tenant scope and not at the subscription scope, as documented in the above steps.

Run the Callback API Call to Cloud

After you connect to Azure and set up access, run the PowerShell callback to the Cloud API to complete the tenant onboarding. If the callback is successful, no output is printed.

Note

The following code is just a reference PowerShell script, so update it according to your environment, but ensure that the subscription ID is empty.

# Set your service account key ID, token, and client secret
$serviceAccountKeyId = "<YourServiceAccountKeyId>"
$serviceAccountToken = "<YourServiceAccountToken>"
$clientSecret = "<YourClientSecret>" # The actual client secret to be encoded

# Combine the key ID and token with a colon and base64 encode for the Authorization header
$authString = "$($serviceAccountKeyId):$($serviceAccountToken)"
$encodedAuthString = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($authString))

# Base64 encode the client secret separately
$encodedClientSecret = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($clientSecret))

# Construct the headers with the encoded Authorization header
$headers = @{   
  "X-Tenant-Id"  = "<CloudsecureTenantId>"  
  "Content-Type"  = "application/json"  
  "Authorization" = "Basic $encodedAuthString"
} 

# Construct the request body with the encoded client secret
$body = @{  
  "type"            = "AzureRole" 
  "client_id"       = "<ClientId>"   
  "client_secret"   = $encodedClientSecret  # Use the base64 encoded client secret 
  "subscription_id" = "<SubscriptionId>" # remove this and use azure_tenant_id if onboarding the entire tenant. 
  "azure_tenant_id" = "<AzureTenantId>" # both azure tenant id and subscription_id should be present for subscription onboarding.
} | ConvertTo-Json -Depth 10 

# Send the POST request
$response = Invoke-RestMethod -Uri 'https://cloud.illum.io/api/v1/integrations/cloud_credentials' -Method Post -Headers $headers -Body $body 

# Output the response
Write-Host $response
What's Next?

When finished, the Onboarding page opens and displays a new row for that tenant.

For the next steps after onboarding a tenant, see After Onboarding Cloud Accounts and Setting Up and Enabling Flow Logs and What to Do Next after Onboarding your Cloud Accounts.

Caveats

After tenant onboarding is complete, it will show a list of subscriptions. If a subscription belonging to a tenant is onboarded before the tenant onboarding, it will not show in the tenant's list of subscriptions. If you wish to see a subscription that you onboarded prior to the tenant onboarding, you need to delete the onboarded subscription. Upon tenant onboarding, it will automatically sync and onboard the subscription.

It is possible that you may someday need to update your service account principals due to expiry or other issues. If you need to update your service account principals after onboarding, see Update Service Principals for Onboarded Azure Subscriptions and Tenants.