SAML provider

Prev Next

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

AppGate ZTNA supports SAML 2.0 single sign-on (SSO) with IdPs such as ADFS, Okta, OneLogin, and Ping. Use SAML to authenticate users who connect through the client and administrators who sign in to the Controller console.


SAML authentication requirements

SAML Response -  AppGate ZTNA requirements

  • The IdP must issue a base64-encoded XML SAML assertion.

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

  • The response must include at least one assertion. Assertions can be encrypted if a decryption key is configured in the IdP.

  • Only the first assertion is validated and used. Any additional assertions are discarded.

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

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

  • The assertion must include an AuthnStatement.

  • The assertion must include an AttributeStatement.

  • The assertion must define an audience under .Assertion.Conditions.AudienceRestrictions[0].Audiences[0].AudienceURI. The value must match the Audience value in the IdP configuration.

  • The assertion must include an issuer tag (URL). Its value must match the Issuer value in the IdP configuration.

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

  • The public certificate entered in the IdP configuration must be 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 IdP

Configure AppGate ZTNA and your SAML IdP so their settings match.

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. Depending on your use case, you may need two or three separate SAML instances.

User authentication on the client

The client supports HTTP POST binding only. If the IdP supports HTTP, the client can act as 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

If the IdP supports secure TLS connections only, set the ACS URL to a redirection server that accepts https:// connections and then forwards the response over http to 127.0.0.1.

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

The redirection server must run a web service listener on https:// and issue a redirect to http://127.0.0.1:29001/saml, where the client is still listening. In Apache, this might look like:

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

User authentication to the Portal

The Portal client supports HTTP POST binding only. Use the Portal as the ACS:

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

The Portal acts as a redirection server and forwards the ACS response to the requesting client. This is not limited to Portal users; the Portal can forward ACS responses for any client. As a result, instead of configuring two SAML IdPs (one for the client using 127.0.0.1 and one for the Portal using portal.com), you can configure one IdP (or reconfigure an existing one). For this to work, full client users must be able to access the Portal URL.

Administrator authentication on the admin UI

The Controller admin/API port 8443 supports HTTP POST binding and HTTP redirect binding. Use these settings:

POST Binding

ACS URL = https://mycontroller.com:8443/admin/saml

Redirect Binding

ACS URL = https://mycontroller.com:8443/ui/sign-in.html

ID/Audience

You also need to configure an ID (name) that defines the relationship between the IdP and the service provider (the Controller). The value must match on both sides. This ensures the SAML message is intended for the specified service provider.

  • Enter a text string. Use the same value when you configure AppGate ZTNA Audience field.

Step 2. Capture initial IdP metadata

To configure AppGate ZTNA, gather the following information from the IdP. This example uses Google (the related AppGate ZTNA field name is shown in parentheses):

  • SSO URL (Single Sign-On URL)

  • Entity ID (Issuer)

  • Certificate (Public Certificate)

You can capture this information in a single XML metadata file that you download from the SAML IdP configuration screen.

Step 3. Configure a new IdP in AppGate ZTNA

Import metadata

  • Go to the Identity Providers (Identity > Identity Providers) page and click +Add.

  • In the drop-down that appears, select SAML as your IdP 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 captures attributes from the SAML response and maps them to claims so you can make access decisions based on policy and Condition criteria.

You may need to add attributes from the user database so they appear in the SAML attribute assertion. See SAML authentication requirements above. Then map those attributes to AppGate ZTNA claims in Attributes Mapped to User Claims.

Attributes mapped to user claims including groups, last name, first name, and username.


Client and portal authentication with a SAML provider

If a profile includes a SAML IdP, users must click Sign in with provider. The client then initiates the SAML authentication request and uses either an embedded browser or the device default browser to handle the SAML flow and session cookies.

The client receives the SAML response and sends it to the Controller, which validates the authentication, attribute, and authorization decision assertions. If authentication succeeds, the Controller uses the SAML attribute assertions to populate AppGate ZTNA user claims.

When configuring the IdP, the ACS URL depends on whether the SAML response is sent over a secure connection (such as TLS) or through the Portal. See Configuring SAML as an external identity provider above.

Client authentication with a SAML provider

  • Client sign-in. For a SAML-based profile, the username and password screen does not appear. After the user clicks Sign in with provider, an embedded browser or the device default browser opens so the user can enter the credentials required by the SAML IdP. After authentication, the browser displays Successfully authenticated with external provider and can be closed (or closes automatically for Portal users).

  • Claims token renewal. When the user’s claims token expires, the client typically renews it automatically using cached username/password credentials. With SAML authentication, the client has no cached credentials. In this case, the user is prompted to reauthenticate, or the browser can automatically reopen to renew the token.

  • Password user interaction. Password user interaction changes for SAML-authenticated users because the IdP might not require a password. Instead of prompting the user to enter a password, the client prompts the user to reauthenticate, or it can automatically reopen the browser to renew the token.

Administrator authentication with a SAML provider

You can also use a SAML IdP to authenticate administrators who sign in to the admin UI.

On the sign-in screen, select a SAML IdP from the drop-down list. The username and password fields are hidden. Click Sign in with browser to open the IdP website and authenticate. The Controller handles the SAML response.