.. _saml-msentraid-adminconsole: Microsoft Entra ID (SAML2.0) - Web Console =========================================== This guide provides configuration instructions for integrating Microsoft Entra ID with Genian ZTNA, a network access control system, for authentication functionality. For administrator authentication, the Genian ZTNA Web Console page calls Microsoft Entra ID authentication using the SAML2.0 protocol, Microsoft Entra ID verifies user authentication status, and proper SSO is achieved. Recommended Versions -------------------- .. csv-table:: :header: Product Name (Component),Version,Notes :class: longtable :widths: 30 30 40 Genian ZTNA (Policy Server),V6.0 or higher,Release version after 2022.05 Microsoft Entra ID,SAML2.0,Integratable as of 2025.10 Prerequisites ------------- - Microsoft Entra ID (formerly Azure AD) tenant - Microsoft Entra ID administrator privileges (Global Administrator or Application Administrator) - Genian ZTNA Web Console administrator privileges - Network connection (communication between Genian ZTNA ↔ Microsoft Entra ID) Purpose of Integration ---------------------- Genian ZTNA and Microsoft Entra ID integration provides the following benefits: - No need to manage separate user databases for ZTNA and Microsoft Entra ID authentication. - Administrators can authenticate to ZTNA using SSO with their Microsoft Entra ID accounts. Supported Features ------------------ Microsoft Entra ID SAML integration supports the following features: - SP-initiated SSO - IdP-initiated SSO - JIT (Just-In-Time) Provisioning - Signed Requests For more detailed information about these features, please visit https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso. Integration Setup Method ------------------------ The Genian ZTNA and Microsoft Entra ID configuration method covered in this guide provides only the essential items for integration. It is automatically applied after the initial one-time setup. Step 1: Create Microsoft Entra ID Enterprise Application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Access https://portal.azure.com and log in with your Microsoft account. #. Navigate to the **Microsoft Entra ID** service. #. Click **Enterprise applications** in the left menu. #. Click the **New application** button at the top of the screen. #. Click the **Create your own application** button. #. Enter app creation information. - **What's the name of your app?**: Enter "Genian ZTNA" (or your preferred name) - **What are you looking to do with your application?**: Select "Integrate any other application you don't find in the gallery (Non-gallery)" - Click the **Create** button. Step 2: Configure SAML Single Sign-On ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. On the **Overview** page of the created Enterprise Application, click the **Single sign-on** menu. #. Select the **SAML** method. #. Click the **Edit** button in the **Basic SAML Configuration** section. #. Enter the following information: - **Identifier (Entity ID)**: Enter the Base URL of the ZTNA Policy Server. - ex) \https://test.genians.net/mc2/faces/saml2/saml2Metadata.xhtml - **Reply URL (Assertion Consumer Service URL)**: Enter the automatically generated ACS URL for the ZTNA Policy Server Base URL. - You can find this value in the **SP ACS URL** field on the Genian ZTNA **Web Console > Preferences > Environment Settings > Admin Console > SAML2 Authentication** screen. - ex) \https://test.genians.net/mc2/faces/saml2/saml2Acs.xhtml - **Sign on URL**: Enter the Base URL of the ZTNA Policy Server. (Optional) - ex) \https://test.genians.net/mc2 #. Click the **Save** button. Step 3: Configure Attributes & Claims ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Click the **Edit** button in the **Attributes & Claims** section. #. Verify the default Claims provided: - **Unique User Identifier (Name ID)**: user.userprincipalname - **givenname**: user.givenname - **surname**: user.surname - **emailaddress**: user.mail - **name**: user.userprincipalname #. If using JIT provisioning functionality, configure Group Claims additionally: - Click the **Add a group claim** button. - In **Which groups associated with the user should be returned in the claim?**, select **Security groups** or **Groups assigned to the application**. - **Source attribute**: Select "Group ID" - In **Advanced options**, select **Filter groups** to filter groups (group name set in Step 8) that the user belongs to. - In **Advanced options**, check **Customize the name of the group claim** - **Name**: Enter the IdP attribute value to map with ZTNA's management role, e.g. _ADMINROLE_superAdmin - Click the **Save** button. .. note:: Group Claims names use the "_ADMINROLE_" prefix to map with ZTNA's management roles (superAdmin, auditor, etc.). Detailed settings are provided in Step 5. Step 4: Verify SAML Signing Certificate and IdP Information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Download the **Certificate (Base64)** from the **SAML Certificate** section. #. Open the downloaded certificate file in a text editor and copy its contents. #. Verify the following IdP information in the **Set up Genian ZTNA** section: - **Login URL** (used as IdP SSO URL) - **Microsoft Entra Identifier** (used as IdP Entity ID) - **Logout URL** (used as IdP SLO URL when using Single Logout) #. In Genian ZTNA **Web Console > Preferences > Environment Settings > Admin Console > SAML2 Authentication > IdP**, copy and enter the following values from Microsoft Entra ID: - **IdP SSO URL** - Microsoft Entra ID's **Login URL**. - **IdP Entity ID** - Microsoft Entra ID's **Microsoft Entra Identifier**. - **x509 Certificate** - Copy and paste the contents of the downloaded **Certificate (Base64)** file. - SAML Certificates section, download **Federation Metadata XML** file and upload using IdP Metadata upload feature. Step 5: Configure Genian ZTNA JIT Provisioning (Optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. To use JIT provisioning functionality, change **JIT provisioning** to 'On' in ZTNA. - In ZTNA UI's **JIT provisioning > Additional Information**, click the add button to set the administrator account's name and email. - For the Name column, enter the IdP attribute value **{http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname} {http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname}**. - For the Email column, enter the IdP attribute value **http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress**. - SAML Attributes (givenname, surname, emailaddress) items are already predefined in Microsoft Entra ID. - Additional attributes beyond the predefined ones can be added using the **Attributes & Claims** menu. - Microsoft Entra ID does not create a Claim if the Source attribute value is empty. Verify that the **Mail**, **First name**, and **Last name** values in the user profile are filled, or change the Source attribute to an existing attribute. - IdP attribute values must specify Claims names. The default is in namespace format (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname). - The namespace can be removed to use the value set in Name. - In ZTNA UI's **JIT provisioning > Administrator Management Role**, click the add button to add management roles. - Enter the IdP attribute value in the format **_ADMINROLE_{role id}** (e.g., _ADMINROLE_superAdmin). - To add other management roles, you must create additional Groups in Microsoft Entra ID and include them in the SAML Response through Group Claims settings. - Group Claims must be configured to use JIT provisioning functionality. - Configure Group Claims as described in Step 3. +----------------------------+-----------------------------+ |Management Role ID |IdP Attribute Value | +============================+=============================+ |superAdmin |_ADMINROLE_superAdmin | +----------------------------+-----------------------------+ |auditor |_ADMINROLE_auditor | +----------------------------+-----------------------------+ - You can check all management roles provided by ZTNA in Preferences > User Authentication > Management Roles. Step 6: Configure Single Logout (SLO) (Optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. To use Single Logout (SLO), turn **Single Logout(SLO)** setting to 'On' in ZTNA. - You must download ZTNA's **SP X.509 certificate** and upload it to Microsoft Entra ID. The SP's certificate is required to use the SLO functionality. - Click the **Edit** button in **Verification certificates (optional)** of the **SAML Signing Certificate** section in Microsoft Entra ID. - Check **Require verification certificates** and upload ZTNA's SP X.509 certificate. - In ZTNA's **IdP SLO URL** - Copy and paste Microsoft Entra ID's **Logout URL**. Step 7: Configure Signed Requests (Optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. To use Signed Requests, turn **Signed Requests** setting to 'On'. - Download ZTNA's **SP X.509 certificate** and upload it to the **SAML Signing Certificate** section in Microsoft Entra ID. The SP's certificate is required to use the Signed Requests functionality. - Click the **Edit** button in **Verification certificates (optional)** of the **SAML Signing Certificate** section in Microsoft Entra ID. - Check **Require verification certificates** and upload ZTNA's SP X.509 certificate. #. Enter the text to display on the Microsoft Entra ID authentication button in **Login Button Text** that will be shown on the Genian ZTNA Web Console authentication screen. #. Click the **Update** button at the bottom of the Genian ZTNA Web Console configuration screen. Step 8: Add and Assign Accounts for Microsoft Entra ID Authentication Integration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If users are already registered, skip to step 5 1. Navigate to **Groups** in the Microsoft Entra ID console menu. 2. Click the **New group** button at the top of the screen to create a group. - Administrator Role Groups must be created for JIT provisioning functionality. - **Group type**: Select "Security" - **Group name**: Enter a name representing the management role (e.g., "ZTNA Super Admin Group") - **Group description**: Enter group description - **Members**: Select administrator users to add - Click the **Create** button You can check all management roles provided by ZTNA in Preferences > User Authentication > Management Roles. 3. Navigate to **Users** in the Microsoft Entra ID console menu. 4. Click the **New user** button at the top of the screen to add a user. - Select **Create new user** - **User principal name**: Enter user account - **Display name**: Enter user name - **Password**: Set initial password - **Groups**: Select the Group created in step 2 - Click the **Create** button .. note:: The Password option allows you to choose whether the administrator should set the password during creation or require the user to change it on first login. 5. Navigate to **Enterprise applications** in the Microsoft Entra ID console menu. 6. Click the "Genian ZTNA" Application registered above. 7. Click **Users and groups** in the left menu. 8. Click the **Add user/group** button at the top of the screen. 9. Select **Users** or **Groups** to assign accounts or groups to be used for authentication integration through the APP. 10. Click the **Assign** button to complete the assignment. Authentication Integration Testing Method ------------------------------------------ **Using Application URL (IdP-initiated SSO)** #. Check the **User access URL** in the **Properties** menu of the Enterprise Application. #. You can log in to ZTNA through that link. **Testing from Genian ZTNA Web Console Page (SP-initiated SSO)** #. Access the Genian ZTNA Web Console page. #. Click the **SAML Login** button. #. Click the authentication button configured in Step 7 above on the authentication screen. #. A Microsoft Entra ID authentication page will be displayed in a new popup window, enter username and password to authenticate. #. Complete additional authentication if Multi-Factor Authentication (MFA) is configured. **Testing Single Logout (SLO)** #. Configure SLO functionality to be enabled. #. Authenticate using SSO functionality. #. Log out using the logout button at the top of the Web Console. #. If you are prompted to enter your Microsoft Entra ID account information when attempting SAML authentication again, SLO is working properly. .. note:: After setting up authentication integration, you must add the Microsoft Entra ID IdP domain to the control policy permissions so that the authentication integration window is displayed even in a blocked state. .. code:: bash 1. How to add permissions 2. Policy > Objects > Network 3. Select Action > Create 4. Enter basic information 5. Network Address > Select FQDN > Enter IdP domain (e.g. login.microsoftonline.com) 6. Click Create 7. Go to Permissions menu 8. Create permission using the created network object 9. Assign the created permission to the control policy that controls device network