Skip to main content

Cloud

Onboard an Azure Cloud Subscription - Guided Setup

Learn how to onboard an Azure subscription using the guided setup if you cannot onboard it using the default setup described in Onboard an Azure Cloud subscription - default setup.

Note

If you don't have permissions to run the PowerShell script for Azure subscription onboarding, you will not be able to use the default setup.

  1. Review the prerequisites. See Prerequisites for Onboarding Azure.

  2. Use your Azure console to provide the required permissions. See Permissions for Onboarding Azure for a list of required permissions.

    To provide permissions in your Azure console, see the Microsoft website.

  3. Onboard your subscription using the guided setup. See Using the Guided Setup.

When you onboard an Azure subscription, the service principal allows Illumio Cloud to retrieve subscriptions and resources. After you create the Azure Entra ID application, set the required reader permissions at the subscription scope, and provide the client ID and client secret credentials, invoke the API using a PowerShell script. The credentials are required to communicate with your Azure subscription.

Using the Guided Setup

Connect to Azure with the Wizard

The steps you take in this first part of the Illumio onboarding wizard are mostly the same as described in Onboard an Azure Cloud subscription - default setup. The exception is that that if you choose to give Illumio Cloud more than read-only access, you must download the permissions as described in Step 4.

  1. If you are logging in for the first time, 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. Click +Add Azure at the top of the page.

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

    add-subscription.png

  4. Provide the following information about your Azure account:

    • Name: Specify a descriptive name for the account. This name appears in Cloud.

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

    • Subscription ID: Paste the subscription ID that you copied from Azure.

    • Onboarding toggle options:

      Onboarding Toggle Option

      Action

      Illumio has Read and Write access to ensure compliance: Yes

      To grant the Illumio Cross Account Role permission to view your Azure subscription resources and to apply policy to them.

      Illumio has Read and Write access to ensure compliance: No

      To provide the Illumio Cross Account Role read-only access.

    Note

    To view the permissions you are granting Illumio Cloud to your Azure subscription, click Download Permissions. This is required for you to onboard the subscription if you are unable to run the script, because you must manually provide the listed permissions.

Setup Access using the Wizard without the Script

  1. Select an existing service account or create a new one by clicking Add a new Service Account. You can use spaces, underscores, numbers, or other characters (such as !,@,#, and so on) for the account name. Make it something you can remember.

    new-service-acct-add.png

  2. If you created a new service account, click Download Credentials. They are needed for the callback API to return the Azure Entra ID app credentials back to Illumio Cloud.

    new-service-acct-secret.png

  3. Enter the ServiceAccountToken.

  4. Do not use the PowerShell script offered in the wizard because this onboarding method assumes you lack the permissions to run it. Instead, follow the steps below in Manually Create an Azure Entra ID App and Assign the Reader RBAC Role to create and register your Azure application.

    This gives Illumio Cloud your newly created Azure application registrations, client, client id, and client secret.

  5. Complete the fields.

    subscription-fields-filled-mar-3.png

  6. Review the details and click Save and Confirm.

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

Use these steps to create an Azure Entra ID App manually.

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

  2. Create the Azure Entra ID App registration as described on the Microsoft website. 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 on the Microsoft website.

  4. Once the Entra ID App and secret are created, assign the Reader RBAC role to the App at the subscription scope, as documented on the Microsoft website.

  5. Ensure that the role is assigned at the subscription scope and not the tenant scope.

  6. After you create the reader RBAC role, assign the API permissions for Illumio Cloud. You can see the permissions in the .txt file you downloaded from the wizard.

Run the Callback API to Illumio Cloud

After you connect to Azure and set up access, run the following PowerShell callback to the Illumio Cloud API in your Azure console to complete the subscription 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-WebRequest -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 subscription.

Set up and enable flow logs.

Grant Flow Log Access - Guided Setup

Run the following script in your Azure console to manually grant flow log access for your subscription. Note that "csTenantId" is the tenant ID and that "subscriptionId" is the subscription ID for Illumio Cloud.

#params for running the script
# to run the script use the command
# ./grant_flow.ps1 -serviceAccountKey <key> -serviceAccountToken <token> -csTenantId <cs_tenant_id> -subscriptionId <subscription_id> -storageAccount <storage_account1,storage_account2,...> -url <url>
# default url is https://cloud.illum.io
param(
    $serviceAccountKey = "",
    $serviceAccountToken = "",
    $csTenantId = "",
    $subscriptionId = "",
    [String[]]$storageAccounts,
    $url = "")
 
#check if the given inputs are valid
if ([string]::IsNullOrEmpty($serviceAccountKey) -or [string]::IsNullOrEmpty($serviceAccountToken)) {
    Write-Host "Service Account Token or Key cannot be empty" -ForegroundColor Red
    exit
}
 
if ([string]::IsNullOrEmpty($csTenantId)) {
    Write-Host "csTenantId cannot be empty" -ForegroundColor Red
    exit
}
 
if ([string]::IsNullOrEmpty($subscriptionId)) {
    Write-Host "subscriptionId cannot be empty" -ForegroundColor Red
    exit
}
 
 
if ($storageAccounts.Count -eq 0) {
    Write-Host "storage accounts list cannot be empty" -ForegroundColor Red
    exit
}
 
# Combine the key ID and token with a colon and base64 encode for the Authorization header
$authString = "$($serviceAccountKey):$($serviceAccountToken)"
$encodedAuthString = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($authString))
 
 
# Construct the headers with the encoded Authorization header
$headers = @{
    "X-Tenant-Id"   = $csTenantId;
    "Content-Type"  = "application/json";
    "Authorization" = "Basic $encodedAuthString";
}
 
# Construct the request body with the storage accounts
# list of storage accounts which has flow logs and for which access has been granted.
# the storage account names must be the entire namespace as shown in cloudsecure flow logs page.
# Eg: /subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<storage_account_name>
 
$body = @{
    "type"            = "AzureFlow";
    "subscription_id" = $subscriptionId; # subscription in which the storage accounts are present
    "destinations"     = $storageAccounts;
} | ConvertTo-Json -Depth 10
 
# Send the POST request
$endPoint = "/api/v1/integrations/cloud_credentials"
 
if ([string]::IsNullOrEmpty($url) ) {
    Write-Host "url is empty hence using default url https://cloud.illum.io" -ForegroundColor Yellow
    $url = "https://cloud.illum.io"
}
 
$url = $url + $endPoint
 
Write-Host "making API call to $($url)"
 
$response = Invoke-WebRequest -Uri $url -Method Post -Headers $headers -Body $body
 
# Output the response
if ($(response.StatusCode -eq 200)) {
    Write-Host "API call to cloudsecure successful"
} else {
    Write-Host "Error making API call to cloudsecure. Status code: $(response.StatusCode)"
}
What's Next after Onboarding your Subscription?

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

For the next steps after onboarding a subscription, 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 Service Account Principals

If you need to update your service account principals when they expire, see Update Service Principals for Onboarded Azure Subscriptions and Tenants.