OIDC provider

Prev Next

This section explains how to configure AppGate ZTNA to work with  OpenID Connect (OIDC) identity providers (IdPs).

OAuth 2.0 is an IETF- specified framework used to build authorization and authentication protocols. OIDC is the third generation of OpenID and is based on this framework. OIDC uses standard TLS infrastructure, which is widley implemented across platforms, and JSON Web Token (JWT) data structures. Earlier versions—OAuth and OAuth 2.0—are not supported by AppGate ZTNA.

AppGate ZTNA and the OIDC implementation should interoperate with many IdPs.

As the Relying Party (RP), AppGate ZTNA supports single sign-on (SSO) authentication with OIDC IdPs such as ADFS, Okta, and Ping. OIDC can authenticate users who connect through the client and administrators who sign in to the admin UI.


Configuring your OIDC provider

Configure both AppGate ZTNA and your OIDC IdP so the settings match.

Application type

OIDC supports three application types: Web Application, Single-Page Application, and Native Application. AppGate ZTNA is a mixed-mode RP because it uses both browsers and native/mobile apps. Although the OIDC implementation is optimized for a single-page application, it can work with other application types if needed. Microsoft Entra includes a native application type called Mobile and Desktop Applications, which we recommend for the client redirect URI. For the admin UI, add a second platform using localhost redirects under a single-page application.

Redirect URIs

The redirect URIs are the URLs that can receive the OIDC response. The authentication request specifies which URI to use, so one OIDC configuration can support the client, Portal, and admin UI.

User authentication on the client

The client supports HTTP only:

Redirect URI = http://localhost:29001/oidc

User authentication to the Portal

Redirect URI = https://myportal.com/oidc

Administrator authentication on the admin UI

The Controller admin/API runs on port 8443:

Redirect URI = https://mycontroller.com:8443/ui/

Scope

Each IdP provides a list of supported scopes. To view it, go to https://myidp/.well-known/openid-configuration

List of supported scopes including openid, email, profile, and more.

Attributes

Group attributes are not part of the OIDC standard, so they are not always included in the token at sign-in. Group information can be useful when signing users in to AppGate ZTNA.

Each IdP adds attributes differently. In Microsoft Azure, open the OIDC app, go to Token configuration, and select + Add groups claim.

Instructions for adding optional claims in MS Azure.

Under Edit groups claim, select the group types, add them to the "ID token" in your preferred format, and save.


Configuring AppGate ZTNA for an OIDC provider

Issuer and Client ID

Get the Issuer and Client ID from your IdP configuration screens. In some cases, you may need to use https://myidp/.well-known/openid-configuration, where these values should be listed.

Scope

Scopes are groups of attributes that the IdP returns when the user authenticates.

There are several that have been defined in the OIDC standard:

  • openid. Required. Contains required claims for OIDC to operate correctly.

  • profile. Optional. User's default profile claims such as name and family_name.

  • email. Optional. User's email.

  • address. Optional. User's address.

  • phone. Optional. User's phone_number.

Each OIDC IdP can also define additional scopes, such as “groups” or “offline_access”.

Configure only scopes that your IdP supports. If you specify an unsupported scope, authentication fails.

Refresh token

A typical access token lifetime is 60 minutes. After it expires, the ser must reauthenticate. If you request the offline-access scope, the authorization exchange returns a refresh token. The client can use the refresh token locally to obtain a new access token at any time. Refresh tokens typically have a longer lifetime, such as 100 days.

After sign-in, AppGate ZTNA uses the initial access token to authenticate the user and then discards it, so the access token lifetime is less important. AppGate ZTNA uses its own claims token to determine when a user must reauthenticate. If the IdP provides a refresh token, the user does not need to interact with the browser when the client requires a new claims token because it can generate a new access token in the background.

User claims

The OIDC standard defines attributes that are always available. You can map a default set of user claims from these OIDC attributes:

  • sub mapped to claim userId (from scope openid)

  • preferred_username mapped to claim username (from scope profile)

  • given_name mapped to claim firstName (from scope profile)

  • family_name mapped to claim lastName (from scope profile)

  • email mapped to claim emails(array) (from scope email)

If you add extra attributes such as Azure group, also map them to a claim.


Special use cases for OIDC providers

In one use case, iOS users who authenticate with an external IdP must use Safari as the authentication browser. A standard external IdP configuration does not work for this scenario. Create a separate OIDC configuration specifically for end users on iOS devices.

In the IdP management console, set the redirect URI to appgate://localhost:29001/oidc.

NOTE

Configure iOS devices to use Safari as the default authentication browser. You can enforce this using an MDM tool such as JAMF or Intune.

After you configure OIDC integration and set up the client profile, Safari might show a blank page. You can close the window and start accessing remote applications.

Safari might also prompt you to confirm that you want to open the page. Safari may offer an option to not show this again. If you accept that option, the prompt should not appear on subsequent logins.