This blog post is going to be about how to implement a simple SSO application using ColdFusion SAML.

To know more about SAML in general, go through the OASIS SAML documentation: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html

There are 3 entities involved in any SSO scenario

1. Principal – The principal is a usually a user requesting some sort of service from an application
2. Service Provider – This could be any application(web/CF) that provides one/multiple services to users, but they first need to be authenticated to avail these services
3. Identity Provider – The Identity Provider acts as an instrument of trust. The user is authenticated to the Identity Provider. The Service Provider contacts the Identity Provider to know the authentication and authorization state of the user.

Prerequisite

Before you use the SAML features, make sure the module is installed by running ColdFusion Package Manager.

Navigate to “<instance_home>/bin” and run “cfpm.bat/cfpm.sh”. You can then type in the command “install saml” to install the SAML module and make use of it’s features.

Metadata Exchange

The first step in developing a SAML application is to exchange metadata between the providers. This acts as a handshake between your ColdFusion application (Service Provider) and the Identity Provider. Exchange of metadata is necessary for messages to be encrypted, decrypted and validated as messages from untrusted/malicious parties should be rejected.

1. Service Provider Configuration

Firstly, let’s add the configuration of our ColdFusion application (SP). This can be done from the ColdFusion Administrator as seen below:

Once you have created a configuration for your Service Provider in ColdFusion, you will need to configure some relevant details in your identity Provider. You can export the SP configuration from the ColdFusion Administrator and upload it to your Identity Provider(if it supports that), or you might need to enter it manually while creating the Identity Provider configuration.

2. Identity Provider Configuration

For the Identity Provider, we are going to be using Okta. After setting up your developer account in Okta, you can start creating your SAML application there. You can follow the guide available here: https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm

Let’s review some of the configuration details:

As you can see, the Single sign on URL is nothing but the ACS URL we created earlier in the SP configuration. The Audience URL is the SP entity Id. In case you are using encryption in your application, you can upload the public key in the ‘Show Advanced Settings’ section.

Once the application setup is done, OKTA will establish the metadata for this application in an XML format like

https://dev-538790.okta.com/app/exk5hk9p0wmMqRjbt357/sso/saml/metadata . This metadata needs to be imported back into ColdFusion as it contains the information regarding the login/logout endpoints for Okta, the binding to be used and the signing public key to verify the authenticity of messages from the IdP. If encryption is being used, the encryption public key will also be found in the metadata.

SSO Requests

Now that the IdP and SP know each other and their respective configurations, we can start initiating SSO workflows. In order to do this, we simply need to call InitSAMLAuthRequest function

<cfset config = {

idp = {name = “testidp”},

sp = {name = “testsp”},

relayState = “cart”

}>

<cfset InitSAMLAuthRequest(config)>

Calling the InitSAMLAuthRequest function prepares the SAML Request according to the contract between the IdP and SP, and sends it to the IdP.

Once you authenticate, the IdP then responds with a set of assertions which include your identity as well as roles/grants that may have been configured for the given user. These can be extracted using the ProcessSAMLResponse function below:

<cfset response = ProcessSAMLResponse(“testidp”,”testsp”)>

<cfdump var = “#response#”>

You can now do a CFLOGIN to create a local session, based on the details received from the IdP.

SLO Requests

Single Logout requests are pretty much the same as SSO requests. We simply need to call the InitSAMLLogoutRequest function with the details we have received during login like sessionindex, nameId and nameIdFormat. These are dependent upon the IdP which sometimes also require the nameIdQualifier and spNameIdQualifier fields.

<cfset config = {

idp = {name = “testidp”},

sp = {name = “testsp”},

sessionindex = “#response.SESSIONINDEX#”,

nameId = “#response.NAMEID#”,

nameIdFormat = “#response.NAMEIDFORMAT#”

}>

<cfset InitSAMLLogoutRequest(config)>

You will be redirected to the IdP which will try to process your Logout Request. The response returned from the IdP will contain a Boolean value which tells us whether the logout at the IdP was successful or not. This can be extracted using the same ProcessSAMLResponse function.

<cfset response = ProcessSAMLResponse(“testidp”,”testsp”)>

<cfdump var = “#response#”>

If the logout was successful, we can perform a local logout for the corresponding user using a CFLogout if we had created such a session earlier. If the logout was unsuccessful, the IdP logs need to be checked to see the reason for the incorrect logout.