Configuring SAML SSO with Forum Sentry - Sample Sentry Policies

Avatar
ForumSystemsSupport
Follow

Introduction

Security Assertion Markup Language, or SAML, provides numerous benefits to enterprises, organizations and governments. One of its greatest assets is Single Sign-On (SSO), which enables users to securely access multiple applications with a single set of credentials that are entered only once.

With SAML, users and organizations can conduct business faster and more efficiently by seamlessly accessing multiple applications on the same domain or on multiple domains.

Many Forum Sentry deployments utilize SAML to provide enterprise SSO. This How To Guide will outline how SAML SSO works with Forum Sentry and includes example Sentry configuration files (FSG) for review on your local Sentry instance. Instructions for testing these sample configurations are also included.

Before getting started, we strongly recommend reading the two attached SAML Whitepapers from Forum Systems. These whitepapers provide clear definitions for the key SAML terms (SP, IdP, etc...) and include diagrams outlining the two common SAML SSO flows.

  1. Introduction to SAML
  2. How to Implement Enterprise SAML SSO

For a video demonstration of a similar use case configuration, see:

Enterprise SAML SSO with Forum Sentry

 

Overview of SAML SSO Transaction Flow

For this use case, a single Sentry instance will be acting as both the SP (service provider) and IdP (Identity Provider).  This will be an example of an SP-Initiated SAML SSO use case. In many production deployments, the same Sentry would not be used as both an SP and IdP. Rather, there would be at least a pair of Sentry instances handling each operation.

As an SP, Sentry will be functioning as a reverse proxy for a web site enforcing various security requirements.

As an IdP, Sentry will be consuming basic authentication credentials from the User and generating a SAML token that is provided back to the SP to assert successful authentication.

The SAML SSO Web Browser profile utilizes automatic redirects to make the login process (which requires multiple hops) seamless to the end user.

This SAML SSO flow through Sentry is a 5 step process, as follows:

  1. The User attempts to access an application from the SP (Sentry HTML Policy).
  2. The User has not been authenticated and so Sentry redirects the User’s browser to the IdP (STS Policy) for authentication.
  3. The IdP challenges the User for credentials. The IdP validates the customer’s credentials.
  4. If the credentials are valid, the IdP creates a SAML token and redirects the User’s browser back to the SP.
  5. The SP inspects the SAML token and its contents. If valid, the User is granted access and a session cookie is established to enable the continued use of the SSO session for some duration of time without requiring re-authentication.

One of the primary benefits of this flow is that the SP never has access to the User's credentials (username and password). Only the IdP receives and processes the user's credentials. The IdP turns the username/password credentials into a SAML token, which once verified establishes the identity of the user at the SP. 

  SP_Initiated.png

 

Overview of Sample Sentry Configuration

The attached Sentry configuration files enable SAML SSO for a public web site (www.forumsys.com) using Forum Sentry.  The configurations were built for Sentry v8.3 and newer and include the following components in Sentry:

  1. HTML Policy - the SP policy to proxy traffic for a web site while enforcing authentication and security requirements
  2. STS Policy - the IdP policy to generate a SAML 2.0 token
  3. A PKCS Key Pair (public and private key) - US_DoD test key pair used for the digital signature of the SAML token
  4. XML Signature and XML Verification Policies - used for the digital signature of the SAML token
  5. Task List - applied to the HTML policy (SP) to initiate the SAML SSO flow and to validate the SAML token generated by the STS policy (IdP)
  6. Redirect Policy - applied to the root directory of the HTML policy to ensure a valid HTTP cookie is present in order to access the web site

Two Sentry Configuration Files Attached

The import password for each FSG file is "password" and both can be imported via the WebAdmin page System-->Configuration-->Import/Export screen under the GDM Import section.

I. HTML Policy "FS_SAML_SSO"

This HTML policy consists of 2 virtual directories (VD):

  1. Forum Systems Web Site - This VD at the root level ( / ) and is used to process the requests for the remote server "www.forumsys.com". This VD requires cookie authentication and if no cookie is provided, or if cookie auth fails, the browser is redirected to the /login directory.
  2. Login - The second VD ( /login ) is a service mode policy (no back-end) and is used to initiate the SAML SSO login process. This VD has the SAML SSO task list associated and will redirect the browser to the IdP (the STS policy) at idp.forumsys.com (you'll need a host entry for this). After the IdP authenticates the user and generates a SAML, it will redirect the browser back to this /login directory.  The same SAML SSO task list will consume the SAML.

If the SAML is validated successfully on the /login directory, an FSSESSION cookie is generated and the browser is redirected back to the / directory. The browser now provides the FSSESSION cookie when following the redirect.

The root VD consumes the FSSESSION cookie and allows the browser through to the remote site.

II. STS Policy "Sentry_STS_Policy"

This STS policy consists of a single virtual directory (VD):

STS - This VD requires basic authentication credentials which are validated against the Forum Systems online LDAP server. Once the credentials are validated, the SAML request is consumed and a corresponding SAML response is returned. The SAML settings can be configured on the STS tab of this policy.

Digital Signatures and XML Encryption

Both digital signatures and XML encryption are key components to a secure SAML SSO use case. With the attached configuration files, both digital signatures and XML encryption are used. These operations utilize keys, which need to be managed securely.

The SAML request is signed, and then verified by the STS. The SAML response is signed and encrypted by the STS policy, and then decrypted and verified by the task list.

 

Testing the Sample Sentry Configuration Files

The policies can be tested with a standard web browser. We recommend using either Chrome or Firefox browsers for two reasons. First, each has easy to use "dev tools" that are helpful for reviewing the transactions.  Secondly, with each browser it is fairly easy to disable JavaScript, which can be helpful to walk through the flow without the automatic redirects.

Important Testing Notes

If testing from same machine Sentry is installed on:

  1. Enter the Sentry listener IP (not www.forumsys.com) in the address bar of the browser
  2. Change the "login" redirect policy in Sentry to point to the Sentry listener IP rather than www.forumsys.com for both the enabled events

If testing from a different server:

  1. Add a local host file entry for www.forumsys.com that maps to the Sentry listener IP
  2. Add a local host file entry for idp.forumsys.com that maps to the Sentry STS policy listener IP

If testing from either the same machine or a different server:

  1. Add a local host file entry for idp.forumsys.com that maps to the Sentry STS policy listener IP

Browser Testing

If your browser has JavaScript enabled, the successful flow should be as follows:

  1. Access www.forumsys.com (or Sentry listener IP) in a browser
  2. Prompted for basic auth credentials - use the following credentials:  Username: newton  / Password: password
  3. Land on the Forum Systems web site

If your browser has JavaScript disabled, the successful flow should be as follows: 

  1. Access www.forumsys.com (or Sentry listener IP) in a browser
  2. Receive JavaScript warning, click continue
  3. Prompted for basic auth credentials - use the following credentials:  Username: newton  / Password: password
  4. Receive JavaScript warning, click continue
  5. Land on the Forum Systems web site

Additional Testing Notes

  1. It is recommended that you use your browser's dev tools (F12) to inspect the flow.  Look for the hidden redirects with the SAML request and SAML response, and look for the FSSESSION cookie being set and being used.
  2. Review the Sentry Access log to see all of the transactions for this flow.  It might help to reset the log first. You'll notice there are many transactions that occur after the initial SSO (to retrieve the different resources used on the site) and all are using HTTP Cookie authentication.
  3. Remove the cookie from your browser and test www.forumsys.com. You should be once again prompted for credentials from the STS policy.

To disable JavaScript in your browser

Chrome

  1. Go to settings
  2. Show Advanced Settings
  3. Privacy --> Content Settings
  4. Under the JavaScript section select "Do not allow any site to run JavaScript"

Firefox

  1. Go to about:config
  2. change javascript.enabled to false

Note that all of the graphics / media on www.forumsys.com will not work correctly with JavaScript disabled.

 

More Information

Passing Web Browser Traffic through Forum Sentry

Forum Systems Online LDAP Server

 

 

 

 

 

 

 

 

 

 

 

 

0 Comments

Article is closed for comments.