.. _oidc-okta-adminconsole: Okta (OIDC) - Web Console ========================= This guide provides configuration instructions for integrating Okta with Genian ZTNA, a network access control system, for authentication functionality. For administrator authentication, the Genian ZTNA Web Console page calls Okta authentication using the OIDC (OpenID Connect) protocol, Okta 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 Okta APP,OIDC 2.0,Integratable as of 2025.10 Prerequisites ------------- Purpose of Integration ---------------------- Genian ZTNA and Okta integration provides the following benefits: - No need to manage separate user databases for ZTNA and Okta authentication. - Users can authenticate to ZTNA using SSO with their Okta accounts. - Provides secure authentication through the OIDC standard protocol. Supported Features ------------------ Okta OIDC App 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 UserInfo Endpoint Integration Setup Method ------------------------ The Genian ZTNA and Okta 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: Okta Account Registration for Integration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Access https://www.okta.com/free-trial/ to apply for a trial account. - Select user information and country. #. Check the authentication confirmation email received at the applied email address. - An account information confirmation email with the subject 'Activate your Okta account' will be sent to the applied email address. #. Click the 'Activate Okta Account' button in the email to activate the account. - Perform initial password change for authentication and configure two-factor authentication. - Okta console access requires OTP 2-factor authentication and requires iPhone/Android OTP app installation and OTP registration. - Once OTP registration and login are complete, OIDC APP configuration for integration begins. Step 2: Adding and Configuring OIDC APP for Authentication Integration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Go to **Applications > Applications** in the menu. #. Click the **Create App Integration** button. #. Select **OIDC - OpenID Connect** in **Sign-in method**. #. Select **Web Application** in **Application type**. #. Click the **Next** button. #. Enter "Genian ZTNA" in **App integration name**. #. Verify that **Authorization Code** is selected in **Grant type**. #. Enter the ZTNA Policy Server's OIDC callback URL in **Sign-in redirect URIs** as shown in the example below: - e.g., https://test.genians.net/mc2/faces/oidc/oidcCallback.xhtml #. Enter the ZTNA Policy Server's main page URL in **Sign-out redirect URIs**: - e.g., https://test.genians.net/mc2 #. Select an appropriate assignment method in **Controlled access** section: - It is recommended to select **Limit access to selected groups** and specify ZTNA administrator groups. #. Click the **Save** button to create the app. #. Check and note the **Client ID** and **Client secret** from the **General** tab of the created app. - **Client ID** example: 0oa1a2b3c4d5e6f7g8h9 - **Client secret** can be viewed by clicking the eye icon next to **Client secret**. #. In Genian ZTNA **Web Console > Preferences > Environment Settings > Admin Console > OIDC Authentication > Identity Provider (IdP)**, copy and enter the following values from Okta: - **Provider Name** - Enter "Okta" - **Issuer** - Okta's **Org URL**. - **Client ID** - Okta's **Client ID**. - **Client Secret** - Okta's **Client secret**. - **Use Discovery** - Select "Off" (automatic endpoint discovery does not work) .. code:: json { "provider_name": "Okta", "issuer": "https://your-domain.okta.com", "redirect_uri_mc": "https://test.genians.net/mc2/faces/oidc/oidcCallback.xhtml", "scopes": "openid,profile,email,groups", "authorization_endpoint": "https://your-domain.okta.com/oauth2/v1/authorize", "token_endpoint": "https://your-domain.okta.com/oauth2/v1/token", "userinfo_endpoint": "https://your-domain.okta.com/oauth2/v1/userinfo", "jwks_uri": "https://your-domain.okta.com/oauth2/v1/keys", "end_session_endpoint": "https://your-domain.okta.com/oauth2/v1/logout", } - **Additional Parameters** (Optional) - You can enter Okta-specific parameters in JSON format. .. code:: json { "idp": "0oa1a2b3c4d5e6f7g8h9", "sessionToken": "...", "prompt": "login" } .. note:: **Additional Parameters** configures custom parameters to be included in the OIDC Authorization Request. **Okta Recommended Parameters:** - ``idp: "0oa1a2b3c4d5e6f7g8h9"`` - Redirect to specific Identity Provider (when using Okta Federation) - ``sessionToken: "..."`` - Authenticate using session token (when using Okta Authentication API) - ``prompt: "login"`` - Force re-authentication - ``prompt: "none"`` - Attempt authentication without user interaction (SSO) - ``login_hint: "user@example.com"`` - User email hint **OIDC Standard Parameters:** - ``ui_locales: "en-US"`` - UI language setting - ``max_age: "3600"`` - Maximum authentication validity time (seconds) - ``acr_values: "urn:okta:loa:2fa:any"`` - Authentication context class reference (require MFA) For more details, refer to https://developer.okta.com/docs/reference/api/oidc/#authorize. #. 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 **{given_name} {family_name}** for the name. - Enter **email** for the email. - OIDC Claims (given_name, family_name, email) items are already defined as standard in Okta. - Attributes other than standard claims can also be added using the **Custom Claims** menu. - In ZTNA UI's **JIT provisioning > Administrator Management Role**, click the add button to add a management role. - Please enter the name **_ADMINROLE_superAdmin** set in Okta's Groups Claims items. - To add other management roles, you need to create groups in Okta's **Directory > Groups** and set other role Groups through **Custom Claims**. - To use JIT provisioning functionality, you need to configure Group Claims. - The group name to assign administrators must include the _ADMINROLE_ prefix and roleId (superAdmin) like _ADMINROLE_superAdmin_ZTNA. +----------------------------+-----------------------------+ |Management Role |Value | +============================+=============================+ |superAdmin |_ADMINROLE_superAdmin_ZTNA | +----------------------------+-----------------------------+ #. Enter the text to display on the Okta 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. .. note:: Please ensure that the Client ID and Client Secret are entered correctly. Using incorrect values will prevent authentication to ZTNA through OIDC. Step 3: Adding and Assigning Accounts for Okta Authentication Integration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Skip to step 5 if users are already registered. 1. Go to **Directory > Groups** in the Okta console menu. 2. Click the **Add Group** button in the middle of the screen to create a group. - For JIT provisioning functionality, you need to create administrator Role Groups. (e.g., _ADMINROLE_superAdmin) +----------------------------+------------------------+ |ID |Description | +============================+========================+ |_ADMINROLE_superAdmin |Super Administrator | +----------------------------+------------------------+ |_ADMINROLE_auditor |Audit Administrator | +----------------------------+------------------------+ You can check all management roles provided by ZTNA in Preferences > User Authentication > Management Roles. 3. Go to **Directory > People** in the Okta console menu. 4. Click the **Add Person** button in the middle of the screen to add a user. - For users who need JIT provisioning, you need to select the Group created in step 2. .. note:: The Password field allows you to choose whether the administrator specifies the password during creation or whether the user changes it during their first login. 5. Go to **Application > Application** in the Okta console menu. 6. Click the gear icon to the right of the "Genian ZTNA" APP registered above and click **Assign to Users**. 7. In the popup screen, click the **Assign** button to the right of the account to be used for authentication integration through the APP to assign it to the APP. Step 4: OIDC Discovery and Advanced Configuration (Optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. **PKCE (Proof Key for Code Exchange)** security configuration is enabled by default. - This is a security feature that prevents Authorization Code hijacking. - Okta supports PKCE by default, so no additional configuration is required. #. **Custom Claims** configuration (if needed) - For JIT provisioning functionality, you need to configure administrator Role Groups. - Go to the **Sign On** tab of the Okta App. - Click **Edit** in the **OpenID Connect ID Token** section. - Set **Groups claim type** to "Filter". - Enter "groups" in **Groups claim name**. - Enter the following in **Groups claim filter**: **_ADMINROLE_superAdmin** Authentication Integration Testing Method ----------------------------------------- **Testing from Genian ZTNA Web Console Page (SP-initiated SSO)** #. Access the Genian ZTNA Web Console page. #. Click the **OIDC Login** button. #. On the authentication screen, click the authentication button ("Sign in with Okta") configured in Step 2 above. #. An Okta authentication page will be displayed in a new popup window where you enter username and password to authenticate. #. Upon successful authentication, JWT ID Token and Access Token are received, user information is extracted, and you are logged into ZTNA. .. note:: After setting up authentication integration, you must add the Okta 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. your-domain.okta.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 endpoint networks