Five things I learned about SAML from studying a realistic example

Five things I learned about SAML from studying a realistic example

I recently dug into execution traces of a saml-rails example app, looking for “points of interest” in the code. Here are five interesting things that I learned about SAML and how to integrate SAML into a realistic application.

Note: The code snippets in this post are edited a little bit for brevity. For full source, click through to the links.

1) The SAML auth request is complex

When a web site wants to login a user with SAML, it sends an HTTP request that contains a specially encoded auth parameter. The auth parameter is a base64 encoding of an XML document. It’s built using code that looks like this:

request_doc = create_authentication_xml_doc(settings)
base64_request = encode(request)
request_params = {"SAMLRequest" => base64_request}

The XML document contains a few required parameters, and many optional ones.

In a real-world scenario, learning more about all these parameters as you review the app requirements, SAML vendor doc, and the SAML spec is going to be important. Other resources confirm my intuition about the complexity of SAML configuration.

2. The user’s HTTP login request is redirected to the SAML provider

Once the base64-ed auth request is created in the previous step, the request is redirected to the SAML provider.

The encoded data is passed to the SAML provider as the SAMLRequest parameter. An example URL looks like this:

Needless to say, SSL is essential throughout the process.

3. The SAML response is verified using a certificate

The saml_callback response contains a fingerprint and digital signature. Your application (a “service provider” in SAML-speak) uses the certificate public key of the SAML identity provider to verify the login response.

4. Applications can dynamically create user records in response to SAML login

When a SAML response is received and verified, it’s expected that the application (“service provider”, remember?) will find-or-create a user record

5. The user id is stored in the session, as normal

Once the user record is created, the user id can be stored the in the session, like any other login flow. It’s good to know that this doesn’t change with SAML as compared to other, less complex forms of authentication.

On the user’s next request, the user id can be retrieved from the session. The user id is used to find the user record in the database, and the request continues.


Originally posted on