SAML Identity Providers

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

AppGate ZTNA supports single sign-on authentication using SAML 2.0 IdPs such as ADFS, Okta, OneLogin, and Ping. SAML is used to authenticate users connecting through the client and administrators logging in to the Controller console.

Use the Identity Providers UI to configure SAML.

SAML authentication requirements

SAML Response -  AppGate ZTNA requirements

• The SAML response issued by the IdP must be a base64 encoded, XML assertion.

• Status code must be "urn:oasis:names:tc:SAML:2.0:status:Success".

• At least one assertion must be present in the response. It can be an encrypted assertion if there is a decryption key configured in the IdP.

• Only the first assertion will be validated and used. The rest will be discarded.

• Assertion.Subject.NameID must exist. The nameid-format depends on the SAML IdP: use <unspecified> if neither <transient> nor <persistent> work.

• The attribute NameID will be used for the username throughout the admin UI.

• The assertion must have an 'AuthnStatement'.

• The assertion must have an 'AttributeStatement'.

• The assertion must have audience defined under  .Assertion.Conditions.AudienceRestrictions[0].Audiences[0].AudienceURI  and the value must match the value of <Audience> entered in IdP configuration.

• The assertion must have an issuer tag (URL) and its value must match the value of <Issuer> entered in the IdP configuration.

• The assertion lifetime conditions 'NotBefore' and 'NotOnOrAfter' must be valid compared to the system time.

• The public certificate entered in the IdP configuration must have been used to create either the assertion signature in Response > Assertion > Signature > SignatureValue or the token signature in Response > Signature > SignatureValue

Configuring SAML as an external identity provider

The AppGate ZTNA settings and those of your SAML IdP need to be configured to work together.

Step 1. Configure your SAML identity provider

Single Sign-on URL (ACS URL)

The AssertionConsumerService (ACS) verifies the SAML response. The ACS URL depends on whether SAML is used by the full client, Portal, or admin UI. You may need to configure two or three separate SAML instances depending on your use case.

User authentication on the client

The client only supports HTTP POST binding. As long as the SAML IdP supports the use of http, then the client itself is the ACS:

ACS URL = http://127.0.0.1:29001/saml (use 127.0.0.1 since iOS does not understand localhost)

SAML IdP only supports secure TLS connections

There may be occasions in which the SAML IdP only supports secure TLS connections. In this case the ACS URL should be set to a redirection server that accepts https:// connections which then sends the response using http (redirecting to 127.0.0.1).

ACS URL = https://redirectserver.mycompany.com/saml

This server needs to have a web service listener (running on https://) which issues another redirect to http://127.0.0.1:29001/saml where the client is still listening. In an Apache server this might look like:

DocumentRoot /var/www/html/saml
Redirect 307 / "http://127.0.0.1:29001/saml"

User authentication to the Portal

The client in the Portal only supports HTTP POST binding. The Portal itself should be used as the ACS:

ACS URL = https://myportal.com/saml

The Portal acts as a redirection server, forwarding the ACS to the requesting client. This process is not constrained to the Portal itself so any client could have their ACS forwarded by the Portal. This means that instead of setting up two SAML IdPs (one for the client using 127.0.0.1 and one for the Portal using portal.com), you only need to set up one (or reconfigure your existing one). Your full client users must be able to access the Portal URL for this to work.

Administrator authentication on the admin UI

The Controller admin/API port 8443 supports HTTP POST binding and HTTP redirect binding. The following settings should be used:

ID/Audience

You will also need to configure one more thing between the systems which is a name or ID that is used to define the relationship we are configuring. This simply needs to be the same at both ends. This ensures the SAML message is for the specified service provider (the Controller).

• Enter a text string which will also be used when you configure AppGate ZTNA Audience.

Step 2. Capture initial IdP metadata

To configure AppGate ZTNA, you will need the following information from the IdP (Google is used in this example with the related AppGate ZTNA field name shown in brackets):

• SSO URL (Single-Sign-on URL)

• Entity ID (Issuer)

• Certificate (Public Certificate)

This can be captured in a single XML metadata file that can be downloaded from the SAML IdP configuration screen.

Step 3. Configure a new identity provider in AppGate ZTNA

Import metadata

• Go to the Identity > Identity Providers screen and click Add.

• In the dropdown that appears, select SAML as your identity provider type.

• Select the Use XML Metadata File button to upload the XML metadata obtained from the IdP:

  • Single Sign-On URL

  • Issuer

  • Public Certificate

Enter the audience

• Enter a text string for the Audience field in AppGate ZTNA.

Step 4. Define attributes

The Controller will capture attributes from the SAML response and map them to claims so that access decisions can be made based on policy and Condition criteria.

You may need to specify or add attributes from the user database to make them appear in the SAML attributes assertion. See SAML authentication requirements above. Then you will need to map these attributes across as AppGate ZTNA claims in the section Attributes Mapped to User Claims:

Client (and portal) authentication

Profiles that include a SAML identity provider (for authentication) will require the user to click Sign in with provider. Thereafter the client will initiate the SAML authentication request and use either an embedded browser or the default browser on the user's device to handle the SAML flow and session cookies.

The SAML response is picked up by the client and sent to the Controller, which checks the authentication, attribute, and authorization decision assertions. If authentication has been successful, the Controller uses the SAML attribute assertions to populate AppGate ZTNA user claims.

When configuring the identity provider, the AssertionConsumerService (ACS) URL will depend on whether the SAML response is to be sent over a secure connection (such as TLS) or to the Portal. See Configuring SAML as an external identity provider above.

User experience

Client sign-in. When a SAML-based profile has been chosen, the username and password screen won't appear. Once the user has clicked Sign in with provider, an embedded browser or the user's default browser will appear allowing the user to enter the credentials required by the SAML identity provider. Having done this, the browser will display the message Successfully authenticated with external provider and can be closed (or will close automatically in the case of a Portal user).

Claims token renewal. When the user's claims token expires, normally the client uses the cached username/password credentials to handle token renewal automatically. But since the user has authenticated using SAML, the client has no cached credentials to use. In this situation, the user will be prompted to re-authenticate or can have the browser automatically re-open in order to renew the token.

Password user interaction. The password user interaction is slightly altered when the user has authenticated using SAML (since a password may not be what is required by the identity provider). When SAML authentication is used, instead of being asked to type in a password, the user will be prompted to reauthenticate or can have the browser automatically re-open in order to renew the token.

Administrator authentication

A SAML identity provider can also be used to authenticate an administrator signing in to the admin UI.

On the sign-in screen, when a SAML identity provider is selected from the dropdown list, the username and password fields will vanish. Clicking Sign in with browser will redirect the user to the identity provider website to enter their credentials. The SAML response is handled by the Controller.

For more information about how to set up SAML, refer to Configure identity providers.