Protecting Resources with the SiteMinder SAML 2.0 Authentication Scheme

CA SiteMinder supports SAML 2.0 federation both outbound to a Service Provider (SP) when acting as an Identity Provider (IdP) and inbound assertions from an IdP when acting as a SP. Similar to the way other authentication mechanism are handled, a SAML 2.0 Template authentication scheme is used to secure resources for inbound federation from an external IdP to SiteMinder acting as a SP. Several considerations are required before using the SAML 2.0 Template authentication scheme. Unlike other authentication schemes, if you access a resource protected by the SAML 2.0 Template directly with no SiteMinder session (SMSESSION) or no SAML 2.0 assertion, SiteMinder will throw a 500 error instead of automatically redirecting for authentication. Additionally, there is no easy mechanism to allow users to still use another authentication mechanism like forms authentication to access those protected resources. There are several ways to address these limitations, but it depends on what the requirements are for the solution. Will the inbound federation being solely IdP initiated? Do users need to access resources directly and then need to be redirected to the IdP for authentication? Do users need to access a resource directly and be authenticated either through federation or another mechanism like forms authentication? Is there a landing page or do users need to access specific resources within the application directly (deep links)? Understanding these requirements is key to identifying the appropriate approach. Several options for these requirements are outlined in this article.

IdP Initiated Federation

IdP initiated federation request are the most straightforward. The link to the SiteMinder secured resources at the IdP can be crafted such that the assertion is posted to SiteMinder on the initial request. SiteMinder will then process the assertion, establish a session and allow access to the resource if the assertion is valid and the user is authorized to access the resource. The user will then be redirected to the specific landing page specified in the authentication scheme or, if enabled, specified in the RelayState parameter sent to SiteMinder. The default landing page is specified in the Target parameter on the SSO tab of the SAML 2.0 Auth Scheme Properties dialog. To allow the IdP to specify a specific target for deep linking, check the Relay State Overrides Target checkbox.

Redirecting to the IdP When Users Directly Access Resources Protected

Handling the scenario where a user is going to directly access a resource adds a slight complication. As I mentioned above, without special handling SiteMinder throws a 500 error. In the case where there is no deep linking to a specific target, The authentication scheme’s Server Error URL can be used to redirect either for an authn request or over to the IdP. Since this is a static URL, though, the original target cannot be preserved. Click the Additional URL Configuration button on the authentication scheme Advanced tab. Check the Enable Server Error URL checkbox and specify the redirection URL.

If preserving the deep link is required, another approach is necessary. The easiest solution is to use an interim HTML Forms authentication scheme to contain the logic. When SiteMinder redirects for form authentication, the originally requested resource is maintained. This logic can be leveraged to perform the necessary redirect with a RelayState parameter on the URL. The approach I like to use for this is to use a customized FCC page with JavaScript for the redirection logic. The resource is then protected with the customized forms authentication scheme instead of the SAML 2.0 template. A second redirection page protected by the SAML 2.0 Template is used to then redirect back to the originally requested resource. While I would prefer to handle the redirection through an additional parameter on the query string, but I ran into an 80-character length limitation that SiteMinder has with the RelayState. So, a cookie-based approach will be used instead. The flow is as follows:

  1. The user accesses a protected resource without a SiteMinder session
  2. SiteMinder redirects the user to the custom FCC
  3. The custom FCC caches the TARGET into a cookie
  4. The custom FCC redirects the user to either the authn URL or the IdP URL
  5. The user is authenticated by the IdP and the assertion is posted back to SiteMinder
  6. The user is redirected to the SAML 2.0 Template authentication scheme target, which is the redirection page described above
  7. The redirection page reads the cookie, deletes it and then redirects the user back to the originally requested resource

Sample code for the interim FCC:

<script language="JavaScript" type="text/javascript">
var target = "$$target$$";
var HostServer = "https://server.with.redirection.page

/ //Use a JavaScript method to create the SMORIGTARGET cookie
setCookie('SMORIGTARGET',target,'','/',HostServer,'secure')
document.location.replace('https://URL.to.initiate.SAML.2.0.authentication');
</script>

Sample code for the redirection page (the code below is ASP, but any language will work):

<script language="JavaScript" type="text/javascript">
//Use JavaScript to get SMORIGTARGET Cookie
var OrigTarget = getCookie("SMORIGTARGET");
document.location.replace(OrigTarget);
</script>

Protecting a Resource Allowing Both Forms Authentication and SAML 2.0 Authentication

The mechanism for allowing this is similar to the interim FCC approach specified above. The difference is that the interim FCC allows the user to directly enter credentials and only performs the federation redirect based upon certain logic (e.g. a cookie that indicates the use wants to leverage federation).

Refer to the relevant SiteMinder documentation for detailed steps on how to configure federation, authentication schemes and other SiteMinder-related configuration.