Skip to main content

Getting Started with the Illumio Console

Set Up SAML Single Sign-On Between Microsoft Entra ID and Illumio Console

This guide walks through creating and configuring a SAML 2.0 SSO application in Microsoft Entra ID (formerly Azure AD) so it can authenticate users into Illumio Console.

Prerequisites

Before you begin, gather the following SP details from your Illumio Console tenant SAML settings:

  • SP Entity ID / Issuer URL — The Issuer (EntityID) is your application's unique SAML entity ID. In most deployments Illumio recommends using the base URL of your Illumio Console login (e.g. https://console.illum.io or for a subdomain https://<subdomain>.illumio.ai). Copy the value your Illumio Console SAML settings show into Entra exactly, character-for-character.

  • ACS (Assertion Consumer Service) URL — where the IdP posts the SAMLResponse

    Example: https://console.illum.io/login/acs

    Subdomain example: https://<subdomain>.illumio.ai/login/acs

    For IdP-initiated login: If you want users to launch Illumio Console from the Entra My Apps portal (IdP-initiated), the SAMLResponse arrives with no tenant context, so the ACS URL must identify your tenant. Append your tenant ID to the ACS URL:https://console.illum.io/login/acs/<tenant-id>

    If you only use SP-initiated login (users start from the Illumio Console login page), the base ACS URL without the tenant ID is sufficient.

  • NameID format — email address (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

You also need an Entra ID role that can create and manage enterprise applications (e.g. Cloud Application Administrator or Global Administrator).

Step 1: Create the Enterprise Application in Entra ID

  1. Sign in to the Microsoft Entra admin center (entra.microsoft.com) or the Azure portal.

  2. Go to Identity → Applications → Enterprise applications.

  3. Click New application.

  4. Click Create your own application.

  5. Enter a name (e.g. Illumio Console), select Integrate any other application you don't find in the gallery (Non-gallery), then click Create.

Step 2: Start SAML Single Sign-On Setup

  1. Open the newly created application.

  2. In the left menu, select Single sign-on.

  3. Choose SAML as the single sign-on method.

Step 3: Basic SAML Configuration

In the Basic SAML Configuration section, click Edit and set:

Field

Value

Identifier (Entity ID)

Enter the Entity ID exactly as shown in your Illumio Console SAML settings (Settings → Authentication → SAML).

This value is an opaque identifier — it must match the Entity ID set in Illumio Console exactly, character-for-character. Copy it from your Illumio Console SAML settings rather than typing it by hand.

Example: https://console.illum.io

Subdomain Example: https://<subdomain>.illumio.ai

Reply URL (Assertion Consumer Service URL)

Example: https://console.illum.io/login/acs

Subdomain Example: https://<subdomain>.illumio.ai/login/acs

Sign on URL (optional)

Your Illumio Console login URL, if using SP-initiated login

Save the Basic SAML Configuration. The NameID is delivered as email in the next step.

Step 4: Attributes & Claims (Profile Attributes)

Warning

Email is required. Illumio Console validates the user based on the email received from the SAML assertion. Without it, authentication fails.

In the Attributes & Claims section, click Edit.

Required NameID (email)

  1. Edit the Unique User Identifier (Name ID) claim.

  2. Set Name identifier format to Email address.

  3. Set Source attribute to user.mail (or user.userprincipalname if mail is not populated).

Additional claims

Add the following claims. Entra ID emits claims with a namespace by default; set simple claim names (no namespace) so they match what Illumio Console expects:

Claim name

Source attribute

email

user.mail

firstName

user.givenname

lastName

user.surname

For each added claim, clear the Namespace field so the assertion attribute name is exactly email, firstName, and lastName.

The resulting assertion contains an <AttributeStatement> with these attributes.

Example:

<saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
  <saml2:AttributeValue xsi:type="xs:string">[email protected]</saml2:AttributeValue>
</saml2:Attribute>
Step 5: Verify SAML Certificates

Verify that the token signing certificate is active and has not expired.

  1. In Entra ID, click Edit for the token signing certificate.

  2. Set Signing Option to Sign SAML assertion.

  3. Set Signing Algorithm to SHA-256.

  4. Click Save.

    Warning

    Do not create or import a certificate on this page.

Require signed SAML requests (Optional)

To require Entra ID to verify signed SAML requests:

  1. In Illumio Console, open the SAML authentication settings and turn on Sign SAML Request.

  2. Click Download Certificate.

    The certificate downloads with a .crt extension.

  3. In Entra ID, click Edit for Verification certificates (optional) in the SAML Certificates section.

  4. Turn on Require verification certificates.

  5. Upload the certificate downloaded from Illumio Console.

    If Entra ID does not accept the file, rename the extension to .cer without converting the file.

After you enable this setting, Entra ID rejects unsigned sign-in requests. If you later rotate the certificate in Illumio Console, upload the new certificate to Entra ID. Otherwise, sign-in fails.

Before publishing, verify that Entra ID accepts a .crt file after its extension is renamed to .cer. Renaming works only when the file already uses PEM or DER encoding.

Step 6: Group Claim

Warning

A group claim is required to manage users from Entra ID. Illumio Console uses the external groups delivered in the assertion to create roles/permissions inheritance from your IdP groups.

In the Attributes & Claims section, click Add a group claim.

  1. Select which groups are returned — All groups, Security groups, or Groups assigned to the application (recommended to limit the assertion size).

  2. Under Advanced options, set Customize the name of the group claim and enter groups (Illumio Console also accepts User.MemberOf). Clear the namespace.

    The resulting assertion includes a group attribute with one <AttributeValue> per group:

    <saml2:Attribute Name="groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
  <saml2:AttributeValue xsi:type="xs:string">Everyone</saml2:AttributeValue>
  <saml2:AttributeValue xsi:type="xs:string">SAML-Illumio-Admin</saml2:AttributeValue>
</saml2:Attribute>
Step 7: Retrieve IdP Metadata and Certificate

From the Single sign-on page, collect the following values to configure Illumio Console:

Entra ID Field

Illumio Console Setting

Login URL (SAML Certificates section / Set up section)

Remote Login URL

Logout URL

Logout Landing URL

Certificate (Base64) — download and paste the X.509 signing cert

Identity Provider Certificate

Microsoft Entra Identifier

IdP Issuer / Entity ID

Alternatively, download the App Federation Metadata XML from the SAML Certificates section, which contains the SSO URL, issuer, and certificate in one file.

Step 8: Assign Users and Groups

  1. In the application, go to Users and groups.

  2. Click Add user/group and assign the users and/or groups that should be able to sign in to Illumio Console.

  3. If your group claim in Step 5: Group Claim is set to Groups assigned to the application, ensure the groups you want delivered in the assertion are assigned here.

Verification

After configuration, initiate a login to Illumio Console. Confirm the SAML assertion contains:

  • A NameID in email format.

  • An email attribute matching the user.

  • A groups (or User.MemberOf) attribute listing the user's Entra ID groups.

Illumio Console validates the email, then applies role/permission inheritance from the delivered groups.