Skip to main content

Getting Started with the Illumio Console

Configuring Microsoft Entra ID (Azure AD) for Illumio Console

The following topics describe how to configure Microsoft Entra ID (Azure AD) for Illumio Console.

Prerequisites

Before you begin configuring Microsoft Entra ID, make sure that you have entered an email address, a first name, and a last name in your user profile within your Entra ID instance. These fields cannot be empty.

Registering Illumio Console as an Application in Microsoft Entra ID

Use this procedure to configure Microsoft Entra ID (formerly known as Microsoft Azure Active Directory) as an external identity provider (IdP) in the Illumio Console's Okta instance using the OIDC protocol.

  1. Log into Entra ID (Azure AD).

  2. In the left navigation panel, click App registrations.

  3. On the App Registrations page, click New registration. 

  4. On the Register an application page:

    1. In the Name field, enter a name for your Illumio Console instance, such as "MyCorp on Illumio". 

    2. For Supported account types, select Accounts in this organizational directory only (Single tenant) .

    3. Under Redirect URI, choose Single-page application (SPA) and enter the URI to Illumio Console: https://console.illum.io.

  5. Click Register.

Confirming App Registration, Entering a Redirect URI, and Enabling Tokens

After you have registered Illumio Console as an application in Entra ID, verify that it displays, add a redirect URI, and enable tokens.

  1. On the App registrations page, click your application name (for example,"MyCorp on Illumio") to see more details.

  2. On your application details page, click Authentication.

  3. Confirm that you have entered the proper Redirect URI, and correct it if needed.

  4. Under Implicit grant and hybrid flows, enable the ID tokens setting.

Obtaining the Client ID and Tenant ID and Updating the Manifest

The next step in configuring Entra ID for Illumio Console is to obtain the Client ID and Tenant ID and to update the manifest.

  1. On the details page for your Illumio Console application, click Settings.

  2. Copy the Client ID setting shown there. You will use this as the Client ID setting when completing your OIDC authentication in the Illumio Console.

  3. Copy the Directory (tenant) ID shown there. This ID will be used as the basis for the Issuer URL setting when completing your OIDC authentication in the Illumio Console, where you will enter the URL in the form: https://-login.microsoftonline.com/tenant_ID/v2.0.

  4. Click Manifest, and on this page use the editor to update the following JSON entries to these values: 

    "acceptMappedClaims": true
"accessTokenAcceptedVersion": 2

    Instead of accessTokenAcceptedVersion you might see requestedAccessTokenVersion. Whichever entry is in your manifest, ensure that this entry is set to 2.

Configuring Tokens in Microsoft Entra ID

The next step in the process of configuring Microsoft Entra ID for Illumio Console is to configure tokens.

  1. Click Token configuration and do the following:

    1. Select ID Token.

    2. Click Add optional claim, and enable email or upn in the list of claims. If it is available, also enable the Turn on Microsoft Graph email permission option.

    3. Click Add.

  2. On the Token configuration page, confirm that either email or upn is listed under the Claim column with ID as the Token type.

  3. In the left navigation pane, click API permissions.

    Note

    You enabled API permissions for email and profile in Step 1.b, when you enabled Microsoft Graph email permission.

  4. Click Microsoft Graph under the API/Permissions name column, and enable the openid permission.

    The email and profile permissions should be enabled already.

  5. Click Add.

Setting Up Custom Claim Mapping

The next step in the process of configuring Microsoft Entra ID for Illumio Console is to set up custom claims mapping.

  1. From the Entra ID Home page, click Enterprise applications.

  2. From the list of your applications, click the name of your new Illumio Console application (for example, "MyCorp on Illumio").

  3. In the details page for your Illumio Console application, click Properties, and ensure that the Assignment required? option is set to Yes. This setting ensures that when a user logs in, the user is assigned to the target Entra ID application.

  4. Click Single sign-on from the left navigation. On the OIDC-based Sign-on page, under the Attributes and Claims section, click Edit.

  5. On the Attributes & Claims page, click + Add new claim.

  6. On the Manage claim page, enter a new claim for firstName:

    1. Enter firstName in the Name field.

    2. Set the Source value to Attribute.

    3. In Source attribute, select user.givenname for the firstName claim.

      Important

      This value must match exactly.

    4. Leave all other options as the default values or as unspecified.

    5. Click Save .

  7. Enter a new claim for lastName:

    1. Enter lastName in the Name field.

    2. Set the Source value to Attribute.

    3. In Source attribute, select user.surname for the lastName claim.

      Important

      This value must match exactly.

    4. Leave all other options as the default values or as unspecified.

    5. Click Save.

  8. The next time you log into the Illumio Console, a Microsoft window requests that you grant permission. Click Accept.

Adding Users to Entra ID and Registering Users to an Application

  1. Within the Azure portal, enter "users" in the search field and select the Users option with an icon.

  2. Click + New user to add a new user and select Create new user from the + New user drop-down list.

  3. Enter values in the User principal name and Display name fields.

    Note

    The value in the Mail nickname field is derived from the User principal name field and the Password field is prepopulated with a password.

    config-entra-id-create-new-user.png

  4. Click Review + create and then click Create.

  5. Navigate to Enterprise applications and click on your application.

  6. Click Users and groups in the left navigation pane and then click + Add user/group.

  7. Search for the user or users you want to add, select the user or users, and click Select.

    config-entra-id-register-user-to-app.png

  8. Click Assign to assign the user to the Illumio Console application.

Adding Roles and Groups to an Entra ID Application

Use the following procedure to create a role for your Entra ID application that maps to a user role in Illumio Console.

  1. Log in to the Entra ID (Azure) account for your Enterprise application.

  2. From Home on the left navigation pane, go to the application page of your enterprise application for Illumio Console.

  3. Under Manage, click App roles.

  4. On the App roles page, click the Create app role link (near the plus sign).

  5. On the Create app role pane, do the following:

    1. Enter a name in the Display name field.

    2. For Allowed member types, select Users/Groups

    3. Make a note of the information in the Value field, because you will enter this value as the Claim value when you add an external group in Illumio Console,

    4. Enter a description in the Description field.

    5. Check the Do you want to enable this app role? check box to enable the app role.

Adding and Configuring an External Group in Entra ID

  1. Within Entra ID, navigate to Groups and click New Group.

  2. Enter the group name and add owners and members that you want to include in the group.

  3. Navigate to the Application page of your OIDC app. In the left pane, select Manage and then select App Roles.

  4. Add a display name, select the users and groups, add a description, and add a value. The value will appear in the JSON web token.

  5. Enable the app role.

  6. Within your OIDC app, navigate to the Enterprise Application page and select Users and Groups from the left pane.

  7. Click Add user/group and search for your group name.

  8. Click Select a role. You will see the App Role that you created previously. Select the role and add the assignment to the Group.

  9. After you add the assignment to the group, it should display in the grid. Adding the group means that the users in the group will inherit access to the OIDC application.

  10. From the left pane, select Single sign-on.

  11. Click the edit icon in the Attributes & Groups pane and add a new claim.

    1. In the Name field, enter groupNames.

    2. Set the source attribute value to user.assignedroles.

    3. Set the type to JWT (JSON web token).

Adding a Groups Claim to Entra ID

  1. Within Entra ID, click Manage in the left navigation pane and then click Single sign-on.

  2. In the Attributes & Claims section, click Edit.

  3. Click + Add new claim, and add a new claim with the following values:

    1. In the Name field, enter groupNames.

    2. For the Source option, select Attribute.

    3. Select user.assignedroles from the Source attribute drop-down list.

      Important

      This value must match exactly.

    4. Set the Type to JSON Web Token.

Adding Permissions to an External Group

  1. Log in to the Entra ID (Azure) account for your Enterprise application.

  2. Click Security > Permissions in the left navigation pane.

  3. At the Permissions page, click Grant admin consent for <your_ilo_org>, where <your_ilo_org> is the name of your Illumio Console organization.

  4. At the sign in prompt, enter your login credentials.

  5. At the Permissions page, click the Application registration link.

  6. At the API permissions page, under the Configured permissions heading you should see a green checkmark next to "Grant admin consent for <your_ilo_org>," which confirms the admin consent was activated.

Adding External Groups in Illumio Console

  1. Within Illumio Console, navigate to Access, select the External Groups tab, and click Add.

  2. Fill out the following fields:

    1. In the Name field, enter the name of the external group. This name must exactly match the group name that you entered in Entra ID.

    2. In the Claim field, enter the value that matches the groupNames attribute set in the IdP.

    3. Select a role from the Roles drop-down list and click Save.