Onboard an Azure Cloud tenant

Onboard an Azure Cloud tenant - default setup

Learn how to onboard an Azure tenant. Onboarding an Azure tenant allows you to connect all the subscriptions and resources under the tenant with Illumio Segmentation for the 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 Segmentation for the 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 Segmentation for the Cloud. These credentials are required to communicate with your Azure tenant.

Review the prerequisites. See Prerequisites for Onboarding Azure.
Onboarding a tenant with the wizard automatically provides the required permissions. See Permissions for Onboarding Azure for the list of required permissions.
Onboard your tenant using the default setup. See Onboard a Tenant with Illumio.

Onboard a tenant with Illumio

If this is the first time logging in to Illumio Segmentation for the Cloud, 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 Illumio Segmentation for the Cloud upon onboarding. Use a descriptive name so that you can easily identify it.
Tenant ID: Paste this ID that you copied from Azure. The tenant ID is also known as the parent management group ID.

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. To view the permissions you are granting Illumio Segmentation for the Cloud to your Azure subscription, click Download Permissions.
Illumio has Read and Write access to ensure compliance: No	To provide the Illumio Cross Account Role read-only access, choose this option. To view the permissions you are granting Illumio Segmentation for the Cloud to your Azure subscription, click Download Permissions.

The wizard advances to step two: 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 Segmentation for the 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.
In summary, the PowerShell command does the following:
- Creates an application registration called "Illumio-CloudSecure-Access"
- Creates a custom role called "Illumio Network Security Administrator"
- Assigns the application registration the role of "Storage Blob Data Reader"
- Gives Illumio Segmentation for the Cloud your newly created application registrations, client, client id, and client secret
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 Segmentation for the Cloud

After you connect to Azure and set up access, run the PowerShell callback to the Illumio Segmentation for 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 Azure 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 in your CSP environment.
To enable flow logs, see Grant flow log access to your CSPs.

What's next after you onboard your tenant?

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

For the next steps after onboarding a tenant, set up and enable flow logs. See Onboarding Azure. Once you set up and enable flow logs, see After onboarding your accounts.

If you originally set the permissions to read only, and wish to change them to read and write, see Change Azure permissions from read to read and write.

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