Onboard an Azure Cloud Tenant

Onboard an Azure Cloud Tenant - Default Setup

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 Illumio 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 Illumio 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 Illumio Cloud. These credentials are required to communicate with your Azure tenant.

Review the prerequisites. See Prerequisites for Onboarding Azure.
Onboard your tenant using the guided setup. See Onboard a Tenant.

Onboard a Tenant

Connect to Azure with the Wizard

If this is the first time you are logging in, click + Azure on the Onboarding page to onboard your first account.
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.
The Add Azure Cloud Tenant wizard starts and displays the first step: Connect to Azure

Provide the following information about your Azure account:

Name: Specify a name for the account; this name is what appears in Cloud upon onboarding. Use a descriptive name so that you can easily identify it in Illumio Cloud.
Tenant ID: Paste the parent management group ID that you copied from Azure.

Onboarding toggle options:

Onboarding Toggle Option	Action
Onboard all subscriptions in the tenant: Yes	To onboard all member subscriptions along with the tenant, select this option.
Onboard all subscriptions in the tenant: No	To onboard only some subscriptions in the tenant, choose this option. Select those necessary for Illumio visibility and protection. Then go to the Onboarding page to onboard those subscriptions individually.
Illumio has Read and Write access to ensure compliance: Yes	To grant the Illumio Cross Account Role permission to view your Azure tenant resources and to apply policy to them, choose this option.
Illumio has Read and Write access to ensure compliance: No	To provide the Illumio Cross Account Role read-only access, choose this option.

The wizard advances to step two: Set up Access

Setup Access with the Wizard

Use the following steps to set up access.

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 Illumio Cloud.
Enter the ServiceAccountToken in the appropriate field.
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.
Ensure that all fields are completed like that shown in the following screen capture.
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.

In a new browser window, open your Azure portal.
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.
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
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
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 Illumio 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 (Web_request.ps1), 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

Set up and Enable Flow Logs after Onboarding

The Onboarding page opens and displays a new row for that tenant.

Now you set up and enable flow logs.

To set up flow logs before enabling them, see Set up Flow Logs.
To enable flow logs, see Grant Flow Log Access to Your CSPs.

What's Next?

The Onboarding page opens and displays a new row for that tenant.

For the next steps after onboarding a tenant, see Azure Onboarding Workflow and After Onboarding your Accounts.

Updating your Tenant

After tenant onboarding is complete, it shows a list of subscriptions. If a subscription belonging to a tenant is onboarded before the tenant onboarding, it does not show in the tenant's list of subscriptions. To see a subscription that you onboarded prior to the tenant onboarding, you must delete the onboarded subscription. Upon tenant onboarding, it automatically syncs and onboards the subscription.
You may someday need to update your service account principals due to expiry or other issues. If you must update your service account principals after onboarding, see Update Service Principals for Onboarded Azure Subscriptions and Tenants.

Cloud