SAML (Web SSO) Authentication

The HTTP and HTTPS protocols in EFT provide the SAML 2.0 Web SSO profile with HTTP POST binding and corresponding user interface controls for enabling and configuring SAML for achieving Single Sign On (SSO) for Web-based authentication. Web SSO support in EFT is limited to LDAP, ODBC, and Globalscape-authenticated Sites; Web SSO is disabled and unavailable for AD-authenticated Sites.

The Web SSO feature in EFT does not support "just in time" (JIT) provisioning of user accounts. Instead, EFT relies on accounts already provisioned in EFT. When a positive mapping of identify assertions to existing user accounts cannot be made, Web SSO authentication will fail or revert to normal authentication and request login credentials. (See Web SSO Error Handling).

EFT is the Service Provider, and is limited to requesting, and processing of replies to a request, that an Identity Provider authenticate a principal (subject) and return a corresponding authentication assertion.

(Scroll down for detailed information about configuring SAML.)

To enable SAML (Web SSO) authentication

  1. In the administration interface, connect to EFT and click the Server tab.

  2. On the Server tab, click the Site you want to configure.

  3. In the right pane, click the General tab.

  4. Click SAML (WebSSO), then click Configure, then provide the details needed to configure SAML.

    1. Service Provider:

      • Entity ID - The default is the host name value specified for the EFT Site being configured, e.g., MySite. Any string value can be provided, up 255 characters, including UTF-8 encoded characters.

      • Reserved Path - The base address followed by the SSO path, e.g., [hostaddress]/sp/samlv2/sso.

    2. Identity Provider:

      • Entity ID - The Identity Provider's host name

      • POST URL - The Identity Provider's POST URL or endpoint that EFT should bind to.

      • Public Key - Certificate path to be used for verifying the server's identity

    3. Username:

      • Location in assertion - Specify whether the username is stored as NameID or Attribute.

      • Attribute name - If Attribute is specified for location, provide the Attribute name.

      • Identifier format - Select the list box and click the format identifier from the list:

        • Unspecified

        • Email Address

        • X.509 Subject Name

        • Windows Domain Qualified Name

        • Kerberos Principal Name

        • Entity Identifier

        • URI Reference

        • Basic

  5. Click OK. Turn on "Trace" for SAMLSSO logger in logging.cfg.

Web SSO Error Handling

When Web SSO is enabled for a Site, and if the Persist username and password credentials for use in Event Rule context variables check box is selected, EFT displays a WARNING prompt. The "persist credentials" feature will not work for accounts that login via Web Single Sign-on (SSO), because there will be no credentials to persist. Instead, you would have to manually specify those credentials for each rule. If you leave the persist credentials feature enabled (or if was already enabled), then EFT will use an empty (NULL) password. (Some users will be able to login normally (if desired), thus the "persist credentials" feature *could* work in those cases, which is why it isn't automatically disabled when SSO is enabled.)

If an error occurs during SSO authentication, EFT will do one of the following:

SAML Scope

EFT follows the reference implementation for SAML 2 according to http://docs.oasis-open.org/security/saml/v2.0/ with the following constraints in place.

  1. SAML 2.0 only: No support for SAML 1.1 or earlier.

  2. Web Profile only: No support for thick client access using SSO.

  3. POST binding only: EFT is limited to HTTP's POST method for binding to the IdP endpoint.

  4. Auth assertions only: EFT as a Service Provider (SP) is limited to requesting that the identity provider (IdP) authenticate a user principal (subject) and processing of the IdP authentication assertion.

  5. Limited identity management providers: EFT's Web SSO support for identifying authorized users (for subsequent authorization and home directory assignment) is limited to LDAP, ODBC, and Globalscape (EFT’s built-in) authentication providers, and thus will be disabled and unavailable for native AD authentication (as native AD will authenticate the user, thus obviating the need for SAML); however, LDAP sync against an AD will be allowed for confirming the user’s identity).

  6. No JIT: EFT's Web SSO feature does not support just in time (JIT) provisioning of user accounts, instead relying on accounts already being provisioned in EFT (via one of the above supported identity providers), failing authentication outright or reverting back to normal authentication methods (request login credentials) when a positive mapping of identify assertions to existing user accounts cannot be made, subject to admin configuration option to this effect.

  7. No credentials persistence: When Web SSO is enabled for an EFT Site, and if under Site > Security tab the Persist username and password credentials for use in Event Rule context variables is toggled on (checked) by the administrator, EFT will not be able to persist credentials to its event rules (as there are none).

  8. No logout redirect: EFT does not provide support for a logout redirect URL or support the Single Logout Protocol (3.7 in SAML Core 2.0 spec). Instead when the user logs out (from the WTC) EFT will expire their EFT web session and place them on the main logon page, e.g. the WTC logon page. Users can click on the SSO login button or navigate to the SSO reserved path to re-POST to the IdP all over again.

SSO Process

  1. If SAML is enabled and a connection is made to the SAML reserved path or the SSO button is clicked on the WTC login page, EFT will perform a POST binding to the predefined IdP. See above for configuration of these options.

  2. EFT subsequently communicates its Entity ID (see above) and will verify the issuer's Entity ID upon receiving an assertion from the IdP.

  3. The IdP, if configured with EFT’s information (including certificate info) will validate EFT’s request message signature and process the request POSTed by EFT.

  4. The IdP will next authenticate the user directly using whatever mechanism it was configured to use for authentication (cert, user+pass, 2FA, other), or forward the request upstream to another IdP, or rely on a cached session. Whichever the case, the IdP should authenticate a user it trusts and return a response containing an assertion to EFT.

  5. EFT will validate the IdP’s response message signature, if signed, using the IdP’s pre-configured public key. If the response signature is valid it will read the assertion. If not valid, EFT will deny the claim and return an error. IdP response message signatures are optional.

  6. EFT will also validate the assertion signature using the IdP’s pre-configured public key. If the assertion signature is present and valid, EFT will perform a username lookup, otherwise it will return an error. Assertion message signatures are required.

  7. EFT will also decrypt the assertion if encrypted. If decryption using the EFT site’s private key succeeds, EFT will proceed to perform username lookup, or if decryption fails, EFT will deny the claim and return an error. Encryption of assertions within the IdP response is optional.

  8. EFT will then check and validate the following claims made in the assertion:

    1. NotBefore - Claim isn’t valid prior to the time specified (see clock skew).

    2. NotOnOrAfter - Claim is not valid on/after time specified (see clock skew).

    3. OneTimeUse - Don’t cache and reuse claim.

    4. AuthzDecisionStatement - if Deny or Indeterminate as Decision Type then reject claim

    5. StatusCode - Reject if anything other than status:Success

  9. If EFT cannot evaluate, parse, or understand a sub-element or attribute of the Conditions element then the entire assertion is considered invalid. This is to adhere to SAML 2 protocol.

  10. EFT will next look up the user identity in the claim (see above) and attempt to match that username to an existing account in EFT (obtained via directory services called to LDAP, ODBC, or Globalscape authentication provider). If EFT finds an exact match then it knows that the user exists in EFT, where to place that user (their home folder), and what permissions to give that user. In a future version EFT may support Just In Time (JIT) provisioning of users along with assertion claims relating to authorization (access controls) in addition to authentication. If no match occurs, or there is ambiguity, then EFT will reject the claim.

  11. If rejected, the user will see an error and be redirected to the logon page (where they can enter their credentials), or if the SAML reserved path was set as the root path (e.g. “/”), then they will be redirected to the logout page (otherwise it would result in an endless loop of authentication attempts). "Failed to find, unambiguously match assertion subject to existing and enabled account."

  12. EFT includes a predefined IdPSP time offset skew of 180,000 milliseconds (3 minutes) for claim validity in either direction, along with an advanced override (via the Windows registry), where the admin can specify smaller or larger values, capped internally at unsigned INT (0 to 4,294,967,295) ms. This allows for case where IdP and SP's clocks are not in sync and the assertion has a time window that either causes the user not to be able login until some point in the future, or causes their claim to expire prior to being able to login with regard to the service provider.

Registry Advanced Settings

WebSSO uses the following Advanced Properties residing in the registry in HKEY_LOCAL_MACHINE\SOFTWARE\GlobalSCAPE Inc.\EFT Server 7.3:

Name Description Values Default
SAMLSSOClockSkewToleranceInMs WebSSO Clock skew tolerance in milliseconds 0 to 4294967295 180000
SAMLSSOSignatureAlgo Specifies the SAML signature algorithm to use XML Security signature algorithm URI or suitable abbreviation (e.g., rsa-sha256, http://www.w3.org/2001/04/xmldsig-more#rsa-sha384, etc.) rsa-sha256
SAMLSSODigestAlgo Specifies the SAML digest algorithm to use XML Security digest algorithm URI or suitable abbreviation (e.g., sha256, >http://www.w3.org/2001/04/xmlenc#sha512, etc.) sha256

Tools for Debugging SAML Communications

When setting up and testing SAML communications between the SP (EFT) and your IdP, you may need to review assertions, especially if authentication is failing for some reason. There are two ways you can do this:

  1. In EFT’s logging.cfg file, uncomment Trace logging for log4cplus.logger.SAMLSSO. Then perform any test communications (attempt to establish a session), and finally, open EFT.log and review the trace log output.

  2. In Google Chrome, there is a developer tool add-in called SAML Message Decoder that will permit you to easily sniff SAML requests and responses made to the IdP, that occur when the user clicks the SSO Login button on WTC’s home page, or if navigating to the SSO reserved path.

Validate Username Regex

EFT must be configured so that it can extract the username from the assertion, so it can attempt a match of the pre-defined user accounts in EFT you pulled down from LDAP or other authentication manager. If EFT cannot find a match, it will be because the user does not exist in its username store, or you’ve misconfigured the username regex matching and EFT is failing or improperly parsing the username from within the assertion. You can attempt to do the following to ensure proper regex mapping:

  1. Configure your IdP (such as Shibboleth) to return the user attribute mail in the format of username@domain.com

  2. Configure your IdP and EFT to match on the username attribute value of “mail”.

  3. Under the “Parse the username using the regular expression” field to grab everything to the left of the @ field: ^(.*)@.*

  4. Ensure there is an EFT user that matches on the username, without the email address, e.g. “username”.

  5. Attempt to login with that user. If it fails, refer to the debugging section above.

  6. There are several online tools that can aid you in creating and testing out your regex expressions: https://regex101.com/

Generate SP Metadata File

Identity Providers (IdPs) needs a way to know which Service Providers (SPs) they can trust. IdPs are informed of trusted SPs either via manual configuration or by importing the SP’s information using a metadata file, which is an XML formatted file that contains all of the relevant SP information (public key, Entity ID, etc.). At this time, EFT does not produce the metadata automatically, nor can it import the IdP’s metadata (thus requiring that you manually configure EFT’s SAML settings in EFT); however there are tools, including an online tool and one provided by ADFS that you can use to generate a metadata file from EFT’s SAML configuration that you can then import into your IdP of choice.

Prerequisites:

  1. Ensure that SAML / Web SSO is enabled in EFT.

  2. Ensure that you have enabled HTTPS in EFT

  3. Ensure that you have already created an SSL certificate in EFT

Generate Metadata Using SAML Tool’s Metadata Generator

  1. Run the tool from https://www.samltool.com/sp_metadata.php and use the settings described below.

  2. EntityId—Enter the value in EFT’s Entity ID field under Web SSO config.

  3. Attribute Consume Service Endpoint (HTTP-POST)—Enter the combined values from under Entity ID and Reserved Path, e.g. https://[domain]/sp/samlv2/sso

  4. Single Logout Service Endpoint (HTTP-REDIRECT)—Leave blank.

  5. SP X.509 cert block—Browse to EFT’s configuration path (the default is C:\ProgramData\Globalscape\EFT Enterprise\ ), open the SSL certificate public key that you created for HTTPS, and copy the key blob into that field. This should look like a long string of numbers and characters.

  6. NameID Format—Leave as is or change to desired value.

  7. AuthnRequestSigned—Change to True if desired, as EFT always signs its request.

  8. WantAssertionsSigned—Set to true, for greater security. EFT supports both.

  9. All the other fields are optional.

  10. Click BUILD SP METADATA.

  11. Copy the metadata into a text file and name it appropriately, e.g. eft_saml_metadata.xml.

  12. Import your metadata into your IdP.

Configuration Tips for IdPs

The following links offer guidance for configuring EFT to work with several different IdPs. Please note that these represent moment-in-time evaluation of interoperability between EFT and various 3rd party systems. These systems are subject to change. As such, these links should be considered as general guidance, and should not be relied on as definitive instructions on how to connect with these IdPs. For the latest and most up-to-date instructions you should consult the relevant documentation offered by these vendors.

Related Topics