Many enterprises utilize Forum Sentry for SAML SSO. There are two primary methods of SAML SSO: Service Provider Initiated (SP-Initiated) and Identity Provider Initiated (IdP-Initiated). SP-Initiated SSO is the more common use case of the two scenarios and it occurs when a user attempts to access the Service Provider directly.
This article will focus on IdP-Initiated SAML SSO and includes a sample Sentry STS policy (FSG file - v8.3) that can be used for IdP-Initiated SAML SSO.
IdP-Initiated is a less common SSO use case because it may require the User to already be authenticated with the Identity Provider. Typically, this is the case with mobile devices where a User can be authenticated by accessing their phone. The figure below summarizes how IdP-Initiated SSO works.
Overview of Sample Sentry Configuration
The attached Sentry configuration file enables IdP-Initiated SAML SSO using Forum Sentry. This is just a sample configuration for a simple IdP-initiated flow. There are many options that can be controlled within the STS policy and with task list processing for more complex use cases.
The flow is as follows:
- User access a login form page via User Agent (web browser).
- User enters credentials and submits form credentials are posted to Sentry STS Policy (IdP).
- Sentry STS Policy consumes form post credentials and then:
- validates the credentials against an online LDAP server
- if incorrect issues a 401
- if correct begins the STS processing
- a SAML 2.0 token is generated
- the SAML token is signed
- the token is encoded and built into a web form as the value of the SAMLResponse parameter
- the form is returned to the browser
- decodes the SAMLResponse
- verifies the signature that was applied by the Sentry STS Policy
- verifies the SAML Issuer
- identifies the User through the NameID or possibly an Attribute value
- collects additional information about the User via Attribute values (optional)
- generates security context (e.g. HTTP Session Cookie) for User to allow for subsequent access without providing credentials (SSO)
NOTE - The Service Provider (SP) in this sample (www.forumsys.com) is not actually consuming the SAML generated by the Sentry STS policy. It is ignoring the POST and redirecting to the products page of the website.
Importing the Sentry STS Policy
The Sentry STS Policy (FSG file) can be imported on the System-->Configuration-->Import/Export page of the WebAdmin interface, under the GDM Import section at the bottom of the page.
Import Password: password
Sentry FSG File Details
The attached configuration file was built in Sentry version 8.3.408 and can be imported into Sentry version 8.3 or newer (i.e. v8.5). The configuration cannot be imported into 8.1, 8.0, or 7.3. This configuration includes the following policy objects, each of which will be created when the FSG file is imported.
- STS Policy - the IdP policy to consume the form post credentials and generate a signed SAML 2.0 token
- PKCS Key Pair (public and private key) - US_DoD test key pair used for the digital signature of the SAML token and SSL on the HTTPS Listener policy
- Signature Policy - used for the digital signature of the SAML token
- HTTPS Listener Policy - Using device IP on port 8443, listener for traffic to the STS policy
- SSL Termination Policy - using the US_DoD test key pair, allows TLS versions 1.2, 1.1 and 1.0.
- LDAP Policy - Connects Sentry to the Forum Systems Online LDAP Server
- User ACL - Associates the LDAP policy to the STS policy
Alternative Flow - User Already Identified Prior to Accessing the IdP (sample not included)
Many SAML SSO IdP-Initiated use cases call for the User to already be authenticated when they access the IdP. Then the IdP simply redirects them to the SP. This is possible with Forum Sentry as well. The flow is outlined as follows:
- Have the login page post (form post) to a Sentry HTML policy which consumes the credentials and validates against the user repository, then sets an HTTP Session Cookie (FSSESSION) for the user and redirects to a landing page behind Sentry - which is requiring cookie authentication.
- The landing page could have links to various Service Providers that support SAML SSO. The links should point to Sentry STS Policies not the services directly.
- When the User clicks a link to access a service, the browser is sent to the IdP (the Sentry STS policy), with the FSSESSION cookie.
- The cookie is consumed by the STS Policy to identify the user. Upon successful authentication a SAML token is generated, and the browser is redirected to the SP. A failed auth could return the browser to the login or landing page.
Testing the Sentry STS Policy
Once the Sentry STS policy has been imported, it can be tested by posting the user credentials into the Virtual URI for the STS policy.
SOAPSonar or other Client Applications
Testing of the STS policy can be done using SOAPSonar. REST client browser add-ons that allow posting URL encoded data may also work.
Using a tool such as SOAPSonar allows the tester to easily review the data returned from Sentry as it won't automatically redirect to the service provider. This can be very helpful testing if the use case does not involve a web browser. The image below shows a SOAPSonar test case configured to test the attached Sentry STS policy, with a valid response. The SOAPSonar project file is attached (SSP file). The important settings are marked in Red, as is the SAML Response returned by Sentry.
- Change the Request URI to point to your local Sentry STS Policy
- The SAML Response value is Base64 encoded
- Decode the SAML it to see the XML SAML response
- The full response is what is returned to a browser
- The form action parameter tells the browser where to send the SAML Response
Attached to this article is a very simple web form (HTML file) that can be modified, launched with a browser, and used to submit the user credentials into Sentry.
To test with the attached form follow the steps below:
- Modify form action in the HTML source to point your Sentry STS policy virtual directory (figure 1)
- Open the HTML in a browser
- Enter the user credentials and click submit (figure 2), the credentials are newton : password
- The browser should be automatically redirected to www.forumsys.com.
- Check the dev tools to see the flow, and note the SAMLResponse parameter that is returned by Sentry and posted to the SP - this is the SAML the SP will consume
- Check the Sentry System log (at DEBUG) to view the transaction, the log will show both the XML SAML as well as the form returned to the browser with the encoded SAML
Review attached PDFs for general introduction to SAML SSO