This section explains how to configure AppGate ZTNA to work with OIDC identity providers (IdPs).
OAuth 2.0 is an IETF specified framework designed to support the development of authorization and authentication protocols. OpenID Connect (OIDC) is the third generation of OpenID to be based on this framework. OIDC uses the standard TLS infrastructure, which is universally implemented on most platforms as well as pJSON Web Token (JWT) data structures. The earlier versions, OAuth and OAuth 2.0, are not supported by AppGate ZTNA.
AppGate ZTNA and the OIDC implementation should provide great interoperability with many IdPs.
As the Relying Party (RP), AppGate ZTNA supports single sign-on authentication using OIDC IdPs such as ADFS, Okta, and Ping. OIDC can authenticate users connecting through the client and administrators logging in to the admin UI.
Use the Identity Providers UI to configure OIDC
Configuring your OIDC IDP
The AppGate ZTNA settings and those of your OIDC IdP need to be configured to work together.
Application type
OIDC supports three application types: Web Application, Single-Page Application, and Native Application. AppGate ZTNA is a mixed mode RP as we use both browsers and native/mobile apps. While the OIDC implementation has been optimized to work as a single-page application, it can work with other application types if required. Microsoft Entra has a type of native application called Mobile and Desktop Applications which we recommend for the client redirect URI; a second platform can then be added using localhost redirects under a single-page application for the admin UI.
Redirect URIs
The redirect URIs are a list of URLs where the OIDC response can be sent. The actual URI used is in the authentication request, so the same OIDC configuration can be used by the full client, Portal, or admin UI.
User Authentication on the client:
The client only supports HTTP:
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 is on port 8443:
Redirect URI = https://mycontroller.com:8443/ui/
Scope
Any IdP will have a list of supported scopes that you can view by going to https://myidp/.well-known/openid-configuration
Attributes
The group attribute is not included in the OIDC standard, so it is not always passed in the token when the user signs in. This is useful when signing users in to AppGate ZTNA.
Every IdP has a different way to add attributes. In MS Azure it would be done by going to Token configuration in the OIDC app and clicking + Add groups claim.
Under Edit groups claim, choose the group types and add them to the "ID token" with the format you prefer and save.
Configuring AppGate ZTNA
Issuer and Client ID
The Issuer and Client ID are taken from the IdP's configuration screens. In some cases you may need to look in https://myidp/.well-known/openid-configuration where these exact terms should be available.
Scope
Scopes are groups of attributes that will be provided 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, family_name, etc.
email. Optional. User's email.
address. Optional. User's address.
phone. Optional. User's phone_number.
Every OIDC IdP may add their own scopes, such as 'groups' or 'offline_access'.
The list defined should be a subset of the list of supported scopes. Undefined scopes will result in an authentication failure.
Refresh token
A typical access token might have a lifetime of 60 minutes. After this time the user is required to re-authenticate. The scope offline-access will return a refresh token in the authorization exchange. This can be used locally to obtain a new access token at any time. A refresh token will have a longer lifetime, such as 100 days.
The initial access token is used by AppGate ZTNA to authenticate the user and then discarded. The token lifetime is therefore somewhat irrelevant. AppGate ZTNA uses its own claims token to define when a user is required to re-authenticate. If there is a refresh token provided by the OIDC IdP, the user will not have to interact with the browser when the client requires a new claims token as a new access token can be generated in the background.
User claims
The OIDC standard defines a number of the standard attributes that will always be available. It is therefore possible to provide a default set of user claims mapped from the OIDC attributes. These are:
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 have added any extra attributes such as the Azure group (see above), then do not forget to map this to a claim.
Special use cases
There is a use case in which iOS users that authenticate with an external IdP require that Safari be used as the authentication browser. A standard external IdP configuration will not work in this specific use case. You must configure a new OIDC configuration specifically for use by end users on iOS devices.
When configuring the IdP, ensure the redirect URI is set to appgate://localhost:29001/oidc in the IdP’s management console.
NOTE
iOS devices must be configured to use Safari as the default authentication browser. You can enforce this using an MDM tool such as JAMF or Intune.
Once you have configured the OIDC integration and set up the client profile, the Safari browser may show a blank page. You can close that window and begin accessing remote applications.
You will also notice that the browser will prompt you and ask if you are sure you want to open the page. You may get the option from Safari to not show this again. Accepting that option should stop the message from appearing at subsequent logins.