Configuring the Traffic Manager as a SAML Service Provider

SAML service provider functionality is not available as standard on all Traffic Manager configurations. For more information, or to obtain a license key upgrade, contact Pulse Secure Technical Support.

SAML (Security Assertion Markup Language) is an open-standard XML-based message framework, used to exchange information concerning the authentication and authorization of user agents attempting to access an organization’s web services.

SAML deployments typically involve two participant types:

•Service Providers (SPs): provide the resources to be protected

•Identity Provider (IDPs): perform the authentication and authorization checks required by your resources

An organization can deploy a secure SAML-based IDP to handle a range of authentication scenarios, from simple back-end LDAP directory services credentials-checking, through to highly complex security arrangements involving multi-factor authentication for many services across an enterprise.

The Traffic Manager has the ability to function as a SAML SP to control access to your back-end web applications. Access is only permitted when a valid SAML token is presented by the requesting user agent, who has in turn obtained the token from a defined IDP.

The SAML Message Exchange

In a typical scenario, a user’s browser connects to an SP in an attempt to access a particular service. The SP is configured to obtain prior validation, and thus redirects the browser to the IDP. The IDP then checks the identity of the user against its own records, and obtains verification that the user has appropriate privileges for the desired service. If successful, the IDP returns the browser to the SP with a SAML assertion that the user is legitimate. The SAML exchange is between the SP and IDP through the user agent, and as such your back-end services are completely insulated from, and unaware of, the security negotiation that takes place.

An IDP can provide authentication for multiple back-end services - commonly known as a Single Sign-on (SSO) service. Equally, an organization could employ multiple IDPs, one for each service.

Furthermore, an IDP does not necessarily need to reside in the same network as an SP. It needs only to be contactable by the user agent (typically a user’s web browser). An SP must be aware of an IDP, and vice versa, through shared SAML configuration details, but they never directly communicate. SAML messages are carried by the user agent.

SAML and the Traffic Manager

The Traffic Manager supports SAML version 2.0, and allows SP-initiated authentication only. Additionally, the Traffic Manager does not support encrypted SAML assertions.

The Traffic Manager can be configured as a SAML Service Provider (SAML SP) to control access to an HTTP(S) service, and should be compatible with any SAML IDP that implements the same standard.

SAML itself has many usages (profiles) requiring various different SAML protocols with bindings to other generic network protocols. The Traffic Manager implements the "Web SSO" profile, with HTTP-Redirect and HTTP-POST bindings used for authentication request and response, respectively.

To ensure the SAML response is trusted, the Traffic Manager accepts cryptographically signed responses based on certificates stored as part of the IDP definition. For more details, see Defining Identity Providers.

The Traffic Manager also maintains user session information where a SAML assertion is received from an IDP. Session data contains the identity of a logged-in user, the time that they (most recently) authenticated, and the time the SAML authentication token expires. This ensures that re-authentication can be requested when the session has timed out.

No session state is stored server-side; instead, a session cookie is created at the client side, encrypted and signed using a secret key shared across the Traffic Manager cluster using the Traffic Manager’s existing session ticket mechanism. This facilitates the use of active-active Traffic Manager configurations, in that the authentication session is shared between active cluster members. To configure session cookie behavior, use the settings described in Configuring a Virtual Server to use an IDP. For more information on session tickets, see SSL Encryption.

The Traffic Manager includes a TrafficScript function, “http.auth.getAuthenticatedUser()”, to return the name identifier of the authenticated user (in a format determined by the IDP, but typically an email address or similar). This user data could then be forwarded to the back-end service as part of, for example, an HTTP request header.

Configuring your Traffic Manager

The Traffic Manager can exchange SAML requests and responses with any compatible IDP. The Traffic Manager requires certain IDP-derived details as part of it’s SAML configuration, and must also provide the IDP with specific configuration items in return. To operate successfully, your SAML configuration must match on both the Traffic Manager (as the SP) and your IDP.

Configuration of your IDP varies according to the actual IDP platform used, and as such is out of scope for this document. For further information on how to configure your IDP to exchange authentication messages with the Traffic Manager, see your IDP administrator.

This section details the configuration from the perspective of the Traffic Manager only.

Defining Identity Providers

The Traffic Manager stores IDP records in the SAML Catalog. Each IDP can then be used by one or more virtual servers to add remote authentication to the services they handle. To access your IDP definitions, click Catalogs > SAML Catalogs > Trusted Identity Providers Catalog.

The following table lists the configuration items requires for an IDP definition:

Key	Description
Name	The name of the trusted identity provider
Entity ID	The identifier that the trusted identity provider sends in the “Issuer” field of the SAML assertion to identify itself.
URL	The URL to which the Traffic Manager should send SAML authentication requests.
add_zlib_header	The SAML standard uses the DEFLATE Compressed Data Format, as described in RFC 1951. Set to “No” if the identify provider adheres to this standard. Set to “Yes” if the identity provider does not adhere to this standard, and instead requires the use of the ZLib format.
strict_verify	Set to “Yes” to force the Traffic Manager to reject SAML responses where the Conditions element contains unknown attributes, or has unknown or missing elements. Set to “No” to disable strict verification, where compatibility issues might be expected.
Certificate	A PEM-encoded X.509 certificate containing the public key that the Traffic Manager should use to verify the integrity of received SAML assertions.

Contact your IDP administrator for suitable values when setting up a new IDP record.

Configuring a Virtual Server to use an IDP

To apply authentication control to your service, configure the applicable virtual server as a SAML Service Provider endpoint. Click Services > Virtual Servers > Edit > Authentication.

The following table lists the items requires for a SAML SP endpoint configuration:

Key	Description
auth!type	The type of authentication the Traffic Manager should use for requests handled by this virtual server. Some types of authentication are protocol-specific; for example, apply only to an HTTP virtual server. Select one of the following supported authentication types: None: No additional authentication is required by the Traffic Manager. SAML Service Provider: The Traffic Manager requires that a valid SAML assertion is presented in order to access this virtual server. This option is available only for HTTP virtual servers.
auth!verbose	Displays detailed messages concerning virtual server authentication in the error log.
auth!session!cookie_name	The name of the cookie used to store the authentication session token.
auth!session!cookie_attributes	The attributes of the cookie used to store the authentication session token. The configured attributes are appended to the cookie unaltered. The default attributes prevent access to the cookie by client-side APIs such as Javascript and apply a strict same site policy.
auth!session!timeout	The number of seconds of inactivity on a session after which the user must re-authenticate with the IDP. Re-authenticating might only mean that the IDP issues a new token; if the user has a valid session with the IDP, they might or might not need to re-authenticate at this point, depending upon the configured SSO policy.
auth!saml!sp_entity_id	A string identifier used by the IDP to determine which SAML SP redirected a user agent for authentication. Use a unique URL, related to the virtual server, but not referencing any actual resources on the back-end service. The URL used here is processed internally by the Traffic Manager and requests sent to it are not forwarded to the back-end, hence any resources residing at this URL become unavailable. If an “Audience” field is present in the SAML assertion, it must match this value. Your IDP administrator might ask you to provide this value in a configuration field called “Audience”.
auth!saml!sp_acs_url	The URL of the SAML assertion consumer service. In other words, the URL at which the Traffic Manager should handle SAML assertions. Use a unique HTTPS URL (especially in a live-service production environment) that does not refer to any actual resources on the back-end service. The URL used here is processed internally by the Traffic Manager and requests sent to it are not forwarded to the back-end, hence any resources residing at this URL become unavailable. If a “Recipient” field is present in the SAML assertion, it must match this value. Your IDP administrator might ask you to provide this value in a configuration field called “Recipient”.
auth!saml!idp	The name of the trusted IDP to which SAML authentication requests are sent, and from which SAML assertions should be trusted.
auth!saml!time_tolerance	The time tolerance, in seconds, for authentication checks. When checking time-stamps and expiry dates against the current time on the system, allow this much time tolerance. For example, if a SAML response contains a “NotOnOrAfter” that is 4 seconds in the past according to the local time, and the tolerance is set to 5 seconds, the response is still accepted. This setting helps prevent a lack of clock synchronization from resulting in rejection of SAML responses.
auth!saml!nameid_format	The format of the name identifier to request and expect from the identity provider. The following options are available: none: No specific format identifier is used in the SAML authentication request, and any string format is allowed in the subject of the SAML assertion. unspecified: The format identifier “urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified” is sent in the SAML authentication request, and any string format is allowed in the subject of the SAML assertion. emailAddress: The format identifier “urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress” is sent in the SAML authentication request, and the subject of the SAML assertion must be an email address.

Troubleshooting SAML Authentication

SAML authentication typically fails at one of two points:

•The handover from the SP to the IDP

•The handover back from the IDP to the SP

In the first case, the authentication attempt usually results in an error page sent by the IDP. In the second case, the error page is sent by the SP. To obtain greater detail in the message exchange observed by the Traffic Manager, enable the virtual server setting auth!verbose. Additionally, the following can be useful in diagnosing problems:

•The error page, in particular if its generated by the IDP

•A Technical Support Report (TSR) from the Traffic Manager

•The IDP metadata, if the IDP supports downloading it

•A SAML logger web browser extension, if available, to capture the SAML exchange

ATTENTION
Information obtained using these methods should not contain any cryptographic secrets or end user passwords. In some cases, a SAML trace might contain the name identifier for an end user (typically an e-mail address) that is passed from the IDP to the SP. Your organizational security policy should dictate the confidentiality level applied to such data.