Disclaimer: I am not a security expert. At @ThoughtWorks we believe security is in our DNA and therefore we vouch for security best practices for our clients. The result is developers, like me, implementing security features and learning quite a lot in the process. These are some of those learnings.

Intended Audience: Beginner

First, a brief explanation of SSO (single sign on).

Before you can understand SAML, you need to understand the context in which it operates, and that is SSO (single sign on) solutions. Whenever you have a single account that can sign you into other accounts, you are using a single sign on solution. For many people, the most familiar example is when you are prompted to log into a new application with your Facebook account. However, others may be more familiar with tools like Okta or Centrify which are identity management systems that allow individuals to access many different applications with just a single account, and are more relevant to company employees. Anywhere you have a single account that can authenticate you to use another application, you are using a single sign on service. But how do these new accounts talk to each other to figure out you are who you are? That’s where solutions such as SAML come in.

Centrify home screen after logging in. Once in, you can access any of these applications with the click of a button and without being required to log in separately to any of them.

SAML Itself

SAML is a single sign on protocol that allows applications to communicate with each other to determine whether a user is authenticated or not for applications managed by a single account. There are other protocols that exist such as OAUTH2. Whether or not SAML or OAUTH is an appropriate solution for different scenarios is out of the scope of this post. There are different versions of SAML but the new industry standard is SAML2.0 and therefore when I talk about SAML, I’m referring specifically to this version in this post.

SAML Terms

Before looking at the logic behind SAML solutions or the implementation, there are some basic terms to understand:

Identity Provider (IDP) : The server the user will ultimately authenticate with. It can be thought of as an authorization authority that holds the user’s credentials. As an example, when logging into an application with your Facebook credentials, Facebook is considered the IDP.

Service Provider (SP): The service or application that the user is trying to access. Slack or Github for example. This application doesn’t hold the job of authenticating the user but instead delegates it to the IDP.

Identity Management Service/Single Sign on Service: A service that provides integration with an IDP. This allows users to gain access to a service via a single account.

Client: The user that is sending a request to the SP.

The Logic behind SAML

The concepts behind a SAML flow are more easily understood than its implementation. There are two main user flows to grasp (both assume that the SP has existing knowledge of the IDP):

  1. A user is trying to login to a service provider but the identity provider maintains knowledge of the user’s account. The user has not been authenticated yet and first needs to authenticate with an identity provider in order to gain access to the service provider.
  2. A user has already authenticated with an identity provider and when trying to access a service provider, the user is granted access to the service provider immediately without having to authenticate with the IDP again.

To elaborate, I will start with the first scenario and use an example to explain. Slack will be the service provider, the application I want to gain access to, and Active Directory will be my IDP. A lot of times, you will have another layer, say Centrify or Okta, that sits between the SP and IDP to make identity management smoother. This identity management layer often abstracts communication between the SP and IDP. For simplicity, I will leave an identity management service out of the picture and assume that the SP communicates directly with the IDP service.

Say I want to log into Slack for the team I am currently working on. This Slack account has a specific URL associated with it and when I login, I should be able to see all my Slack channels. But Slack can be setup so that it doesn’t have to handle the authentication, in other words, you don’t need a username and password for Slack, you can authenticate with a single sign on account that manages all your other applications. When I access Slack, I will be redirected to in order to authenticate with the IDP. Once authenticated, I will be once again redirected to Slack, but this time, I am authenticated and can now see all my channels. The scenario would look something like this:

Now the diagram above leaves one question: How the heck does this all work?

Let’s Visit the Process Step by Step

  1. Before anything happens, Slack has already been configured to talk to an authorization server through SAML metadata a user must provide. Metadata can be generated or, in my experience, an identity management application can provide the SAML metadata that a user must import into the service provider. SAML metadata is an XML document that sits with the SP and tells the SP how to communicate with the SAML-enabled IDP. The XML doc contains mostly endpoints to the single sign on service or endpoints that tell the SP where to forward the client’s request for authentication.
  2. I visit the Slack URL. Slack reads the metadata it has to determine where to route my request. In this case, it is the URL of an IDP service.
  3. The IDP will authenticate me once I give it my credentials. It then generates a SAML token, the SAML token is then sent back to the service provider. A SAML token is an XML file that contains metadata about the token itself and the user who has just been authenticated. For example, it may contain information about what IDP issued the token. It also contains the user’s email, when the user was authenticated, and most importantly when the user’s token expires. The SAML token is sent back to the service provider and the service provider uses the token to continuously verify a user’s identity. As long as the token is not expired and has a valid signature, the user is allowed in. Once the SP detects the token is expired, the service provider is then aware that the user needs to repeat the process again to authenticate with the IDP.

Now if I close the browser and then reopen it to the same Slack URL as before, we will encounter the second scenario I gave above.

  1. I try to repeat the process above beginning with a visit to Slack URL
  2. Slack checks the SAML token it has and sees that it’s signature and expiration date are still valid. This means that I am still authenticated properly and don’t need to authenticate again.
  3. Slack gives me access immediately without redirecting me to an IDP.
This is the second flow I identified above. The client has already authenticated once, and since the token is valid, the client does not need to authenticate with the IDP again until the token becomes invalid.

So Why is SAML Important?

Why should you care? SAML makes security easier to accomplish for developers by abstracting the logic behind secure authentication. It also promotes single sign on authentication which benefits end users and developers in a variety of different ways such as:

  • Better User Experience. Having one account, simplifies what a user needs to know and keep track of. In the end, SSO prevents “password fatigue.”
  • Reduced Complexity. Companies can more easily manage what users can see what applications, as well as permission levels for each application (you may have “view only” while I can click around).
  • Security. SAML promotes single sign on so it leaves credentials with the more secured IDP rather than having credentials stored on individual applications. Additionally, communication between the IDP and SP is more secure due to the use of SAML tokens.
  • Standardized Interface. For software developers, SAML provides a standardization for SSO communication. This makes developing applications intended for SSO easier.

What’s Next?

I tried and tried to find an example of how to implement SAML or a tutorial online but was unsuccessful. I supposed I’ll have to be writing my own tutorial soon! Overall, I hoped this helped gain a better understand into how SAML Auth works, why we have it, and how it can help us in many ways.

Currently a developer @ Clubhouse. Previously a ThoughtWorker. Learning as I go.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store