.. _oidc-msentraid: Microsoft Entra ID (OIDC) - CWP =============================== This guide provides configuration instructions for integrating Microsoft Entra ID (formerly Azure AD) with Genian ZTNA, a network access control system, for authentication functionality. Overview -------- Through OIDC APP integration between Genian ZTNA and Microsoft Entra ID solutions, user authentication can be performed via Microsoft Entra ID without the need to manage a separate Genian ZTNA user database. For user authentication, the Genian ZTNA CWP page calls Microsoft Entra ID authentication using the OIDC (OpenID Connect) 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 2025.10 Microsoft Entra ID,v2.0 Endpoint,Integratable as of 2025.10 Prerequisites ------------- - Microsoft Entra ID (formerly Azure AD) tenant - Microsoft Entra ID app registration permissions (Application Administrator or Global 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. - Users can authenticate to ZTNA using SSO with their Microsoft Entra ID accounts. - Provides secure user authentication through the OIDC standard protocol. - Provides integrated authentication environment with Microsoft 365 users. - Enables application of advanced security policies through Conditional Access. Supported Features ------------------ Microsoft Entra ID OIDC integration supports the following features: - Authorization Code Flow (standard OIDC authentication flow) - PKCE (Proof Key for Code Exchange) security enhancement - JIT (Just-In-Time) Provisioning - Access Token and ID Token validation - User information retrieval through Microsoft Graph API 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: Microsoft Entra ID App Registration (for CWP) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Access https://portal.azure.com and log in with your Microsoft account. #. Navigate to **Microsoft Entra ID** (formerly Azure Active Directory) service. #. Click **App registrations** in the left menu. #. Click the **New registration** button. #. Enter app registration information. - **Name**: Enter "Genian ZTNA CWP" - **Supported account types**: Select "Accounts in this organizational directory only" (Single tenant) - **Redirect URI**: Select "Web" and enter the following URL - https://test.genians.net/cwp2/faces/oidc/oidcCallback.xhtml - Click the **Register** button. #. Copy the following information from the **Overview** page of the registered app: - **Application (client) ID** example: 98765432-4321-4321-4321-210987654321 - **Directory (tenant) ID** example: 87654321-4321-4321-4321-210987654321 - Used when constructing Endpoint URLs. Step 2: Microsoft Entra ID App Authentication Settings (for CWP) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Click **Authentication** in the left menu of the registered app. #. Verify that the **Web** platform is added in **Platform configurations**. #. Verify that the following is correctly entered in **Redirect URIs**: - https://test.genians.net/cwp2/faces/oidc/oidcCallback.xhtml #. Add the following to **Logout URL**. (optional) - https://test.genians.net/cwp2/faces/login.xhtml #. Check the following in **Implicit grant and hybrid flows**: - **Access tokens** (optional) - **ID tokens** Check (required) #. In **Advanced settings**, configure the following: - **Treat client as public client** : "No" (default) - **Allow family and school accounts** : Configure as needed #. Click the **Save** button. Step 3: Microsoft Entra ID Client Secret Generation (for CWP) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Click **Certificates & secrets** in the left menu of the app. #. Click **New client secret** in the **Client secrets** tab. #. Enter client secret information. - **Description**: Enter "ZTNA CWP Secret" - **Expires**: Select "24 months" (recommended) - Click the **Add** button. #. Copy and save the **Value** of the generated **client secret** in a secure location. - **Client secret** example: 9z8Y7x6W5v4U3t2S1r0Q~p9O8n7M6l5K4j3I2h1G0f .. note:: The client secret value can only be viewed immediately after creation. It cannot be viewed again once you leave the page, so be sure to save it. Step 4: Microsoft Entra ID API Permissions Settings (for CWP) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Click **API permissions** in the left menu of the app. #. Click the **Add a permission** button. #. Select **Microsoft Graph**. #. Select **Delegated permissions**. #. Add the following permissions: - **openid** (default, required for OpenID connection) - **profile** (default, user profile information) - **email** (default, email address) - **User.Read** (user basic information retrieval) - **Directory.Read.All** (optional, for group information retrieval) #. Click the **Add permissions** button. #. Click the **Grant admin consent for {tenant name}** button. (Global Administrator permission required) #. Click **Yes** in the admin consent confirmation dialog. Step 5: Microsoft Entra ID User and Group Settings (for CWP) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Click **Users** in the left menu of Microsoft Entra ID. #. Verify users who will be granted CWP access. #. In the **Groups** menu, click **New group** to create a user group. (optional) - **Group type**: Select "Security" - **Group name**: Enter "ZTNA-Users" - **Group description**: Enter "ZTNA general user group" - **Members**: Add users - Click the **Create** button. #. Create an additional VIP user group. (optional) - **Group name**: Enter "ZTNA-VIP-Users" - **Group description**: Enter "ZTNA VIP user group" #. Navigate to **Enterprise applications**. #. Search for and select the created "Genian ZTNA CWP" app. #. In the **Users and groups** menu, click **Add user/group**. - Assign users or the ZTNA-Users group. Step 6: Genian ZTNA OIDC Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. In Genian ZTNA **Web Console > Preferences > User Authentication > Authentication Integration > OIDC Authentication Integration**, copy and enter the following values from Microsoft Entra ID: - **Provider Name** - Enter "Microsoft Entra ID" - **Issuer** - https://login.microsoftonline.com/{Directory(tenant) ID}/v2.0 - **Client ID** - Microsoft Entra ID's **Application (client) ID** - **Client Secret** - Microsoft Entra ID's **Client secret value** - **Scope** - Enter "openid profile email User.Read" - **Use Discovery** - Select "Off" (automatic endpoint discovery does not work) - You can check related Endpoint information by clicking Endpoints on the registered App screen. - You can check related Endpoint information by accessing the following URL: https://login.microsoftonline.com/{Directory(tenant) ID}/v2.0/.well-known/openid-configuration .. code:: json { "issuer": "https://login.microsoftonline.com/{Directory(tenant) ID}/v2.0", "authorization_endpoint": "https://login.microsoftonline.com/{Directory(tenant) ID}/oauth2/v2.0/authorize", "token_endpoint": "https://login.microsoftonline.com/{Directory(tenant) ID}/oauth2/v2.0/token", "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo", "jwks_uri": "https://login.microsoftonline.com/{Directory(tenant) ID}/discovery/v2.0/keys" } - **Additional Parameters** (Optional) - You can enter Microsoft-specific parameters in JSON format. .. code:: json { "domain_hint": "example.com", "prompt": "select_account" } .. note:: **Additional Parameters** configures custom parameters to be included in the OIDC Authorization Request. **Microsoft Recommended Parameters:** - ``domain_hint: "example.com"`` - Guide login to specific tenant - ``login_hint: "user@example.com"`` - User email hint - ``prompt: "select_account"`` - Display account selection screen - ``prompt: "login"`` - Always display login screen - ``prompt: "consent"`` - Display consent screen **OIDC Standard Parameters:** - ``ui_locales: "ko-KR"`` - UI language setting - ``max_age: "3600"`` - Maximum authentication validity time (seconds) For more details, refer to https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow. #. 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 user account's name and email. - Enter **name** for the name. - Enter **email** for the email. - OIDC Claims (name, email) items are already defined as standard in Microsoft Entra ID. #. Enter the text to display on the Microsoft Entra ID authentication button in **Login Button Text** that will be shown on the Genian ZTNA CWP authentication screen. - Example: "Sign in with Microsoft", "Microsoft Login" #. Click the **Update** button at the bottom of the Genian ZTNA Web Console configuration screen. .. note:: Please ensure that the Application ID and Client secret are entered correctly. Also verify that the Tenant ID is correctly included in the Issuer URL. Authentication Integration Testing Method ----------------------------------------- **Testing from Genian ZTNA Web Console (SP-initiated SSO)** #. Access the Web Console and click the **Test** button in **Preferences > User Authentication > Authentication Integration > Authentication Test**. #. In the popup window, select **OIDC** as the authentication information store. #. In the Provider selection screen, select the configured "Microsoft Entra ID" Provider. #. A Microsoft authentication page will be displayed in a new popup window. #. Enter Microsoft account username and password to authenticate. #. Complete two-factor authentication (MFA) if required. #. If the 'Authentication successful' message is displayed, the authentication integration was successful. **Testing from Genian ZTNA CWP Page (SP-initiated SSO)** #. Set the authentication method of the node policy's authentication policy to **OIDC**. #. Access the Genian ZTNA CWP page. #. Click the **Authentication** button on the CWP page. #. On the authentication screen, click the authentication button ("Sign in with Microsoft") configured in Step 6 above. #. A Microsoft authentication page will be displayed in a new popup window. #. Enter Microsoft account username and password to authenticate. #. Complete two-factor authentication (MFA) if required. #. Upon successful authentication, JWT ID Token and Access Token are received, user information is extracted, and you are logged into ZTNA CWP. .. note:: After setting up authentication integration, you must add the Microsoft 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 - login.microsoftonline.com - graph.microsoft.com (Microsoft Graph API) 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 endpoint networks