Configuring the Virtual Traffic Manager as a SAML Service Provider
SAML service provider functionality is not available as standard on all Virtual Traffic Manager configurations. For more information, or to obtain a license key upgrade, contact 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 Virtual 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 Virtual Traffic Manager
The Virtual Traffic Manager supports SAML version 2.0, and allows SP-initiated authentication only. Additionally, the Virtual Traffic Manager does not support encrypted SAML assertions.
The Virtual 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 Virtual 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 Virtual Traffic Manager accepts cryptographically signed responses based on certificates stored as part of the IDP definition. For more details, see Defining Identity Providers.
The Virtual 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 Virtual Traffic Manager cluster using the Virtual Traffic Manager’s existing session ticket mechanism. This facilitates the use of active-active Virtual 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 Virtual 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 Virtual Traffic Manager
The Virtual Traffic Manager can exchange SAML requests and responses with any compatible IDP. The Virtual 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 Virtual 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 Virtual Traffic Manager, see your IDP administrator.
This section details the configuration from the perspective of the Virtual Traffic Manager only.
Defining Identity Providers
The Virtual 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 Virtual 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 Virtual 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 Virtual 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.
Enhanced SSO virtual server handling to ensure SAML SP authentication remains available for the dedicated SSO virtual server when the global SSO feature is enabled, even if a standard SAML SP license is not present. Authentication settings are now automatically re-evaluated when SSO is enabled or disabled, or when the SSO port configuration changes.
Behavior:
- The SSO virtual server can use SAML SP authentication whenever SSO is enabled.
- Changes to SSO settings take effect immediately without requiring additional configuration changes or a restart.
- Existing SAML SP licensing restrictions continue to apply to all other virtual servers.
The following table lists the items requires for a SAML SP endpoint configuration:
Key | Description |
|---|---|
auth!type | The type of authentication the Virtual 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 Virtual Traffic Manager. SAML Service Provider: The Virtual 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 Virtual 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 Virtual 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 Virtual 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🇹🇨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🇹🇨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 Virtual 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 Virtual 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.
Single Sign-On (SSO) Settings
SSO is a user authentication process that allows users to access multiple applications or services with a single set of login credentials. Once authenticated, users are seamlessly granted access to others without the need to re-enter their credentials.
To enable SSO Login:
- Navigate System > Global Settings > SSO Settings.
- Select Yes to enable login using SSO. By default, this option is disabled. If disabled SSO login option is not displayed on the login page.
- Enter the TCP port that SSO login listens, Default port is 9990. If default port is busy, then use the next available port.
The virtual server must listen on the exact port defined in your SSO configuration (sso!port). If mismatch will cause SSO login to fail. After creating the virtual server, you need to set up a SAML Identity Provider and configure authentication for the virtual server using this Identity Provider.