{ "componentChunkName": "component---src-pages-blog-markdown-remark-fields-slug-js", "path": "/blog/demystifying-saml", "result": {"data":{"markdownRemark":{"html":"

Table of Contents

\n\n

Introduction

\n

SAML, the Security Assertion Markup Language, is a protocol released in 2000 to give people a way to authenticate themselves across domains. The XML standard had just been released a couple of years before and was a popular way to send data across the internet, so the idea was to make a protocol to send a variation of XML that could authenticate a user called a SAML assertion. Now, if a user needed to verify themselves across domains, they could log into one location and be verified at any other location that has a trust with that service.

\n

What is Single Sign-On (SSO)?

\n

Single Sign-on is a process where a user can authenticate themselves with an Identity Provider (IdP) and log into any other eligible Service Provider (SP) without re-entering their password. It’s the main goal that SAML sets out to accomplish. But if that’s unclear, let’s give a real-world example.

\n

Let’s pretend you’re a janitor in an office. You’ve got one of those massive key loops with hundreds of keys on them. Every time you go to open a door, you have to search through your massive key loop to find the right key for the right door. It’s an absolute headache. But your boss (Identity Provider) wants to help out, so they implement keycard readers at every door. Now instead of managing a bunch of keys (passwords) for every door (Service Provider), you have a single keycard (SAML assertion) that you can scan at every door for access.

\n

How Does SAML Authentication Work?

\n

SAML works by having a user log in at an Identity Provider who generates a SAML assertion for the user. Then the user’s browser forwards the SAML assertion to the Service Provider to authenticate them. SAML SSO can be done with either an IdP initiated flow or an SP initiated flow. In an IdP initiated flow, the Identity Provider redirects you to the Service Provider after you’ve already been logged in, and you can access the Service Provider’s application. With an SP flow, a user starts the login process at the Service Provider and is redirected to the Identity Provider to log in. After logging in, they are redirected back to the Service Provider to use the application.

\n

Before either process happens for a user, the Identity Provider and Service Provider need to agree on a SAML configuration stating how the user data will be sent over. This is configured through the Identity Provider. The IdP must also give a copy of its public key to the Service Provider. Both the public key and configuration are bundled into an XML Metadata file that must be given to the Service Provider for SAML SSO to work. This process is called establishing a trust relationship.

\n

The Benefits Of SAML Authentication

\n

SAML authentication allows people to not have to manage multiple passwords for multiple programs. It’s useful inside large organizations that need to handle many employees as well. They can configure what applications people have access to through what’s called an Identity Access Management (IAM) platform. This allows an organization to easily provision and remove employee access in one location. A common IAM integration for SAML is Microsoft Entra ID, a cloud-based alternative to Microsoft’s Active Directory product.

\n

For an example of how this works, let’s say you started a new job at SuperWorkers. SuperWorkers will need to give you access to tools like Gsuite, Slack, and Salesforce. To make this process simple, SuperWorkers has put all of your information, such as your email address and what applications you are allowed to access, in Entra ID. Now they can configure Entra ID as an Identity Provider for the services you need to access, like Gsuite, Slack, and Salesforce, and you can log into Microsoft and access all of your services. If you ever need access to new platforms, they can change your permissions in Entra ID, and if you ever need to be offboarded, they can simply remove you from Entra ID instead of individually offboarding you from each platform.

\n

What Is The Difference Between SAML and SSO?

\n

Single Sign-on is a way to authenticate at one location and be authenticated at multiple other services, as we discussed earlier. SAML is a way to implement that process. There are other ways to implement SSO, such as OpenID Connect. Although they are different technologies, you can think of SSO as an umbrella of technologies that SAML falls under.

\n

When To Choose SAML For Your Security Protocol

\n

SAML is usually the main choice for large organizations who are using an IAM platform. If you’re building a service that caters to large organizations (B2B), it’s recommended to have an ability to allow Single Sign-on through SAML, as it’s common in that space. Otherwise, it’s much more common to use a service like OpenID Connect to handle SSO, especially in the B2C space.

\n

Implementing SAML Authentication

\n

It’s possible to implement SAML authentication in Supertokens, our authentication platform. SuperTokens has a front-end and back-end SDK that makes integration simple and a core for managing user state.

\n

We’re going to walk through implementing SAML authentication using Microsoft’s Entra ID as the Identity provider. However, you can integrate with any SAML Identity Provider when using SuperTokens. We handle SAML integrations with Boxy HQ’s SAML Jackson product, which converts a SAML SSO flow to plug into an OAuth/OpenID Connect platform.

\n

Let’s get started.

\n

Microsoft Entra ID

\n

In order to integrate the SAML SSO flow, we first need to register an application with Entra ID. Head to the Microsoft Entra ID dashboard and select Enterprise Applications on the left side.

\n

\n \n \n \n \n

\n

Click the Edit button in the Basic SAML Configuration.

\n

\n \n \n \n \n

\n

And add the following values to your application:

\n\n

Then click Save at the top.

\n

\n \n \n \n \n

\n

Scroll down to section 3 and download the Federation Metadata XML—we’ll need this later to upload into SAML Jackson.

\n

Click Users and groups on the sidebar and then Add user/group at the top of the page.

\n

Select None Selected then click your username and click Select. Then click the Assign button to add yourself as a user for this app. If a user is not assigned to the app in Entra ID, then they won’t be able to use SSO to log in.

\n

\n \n ' \\\n--data-urlencode 'defaultRedirectUrl=http://localhost:3000/auth/callback/saml-jackson' \\\n--data-urlencode 'redirectUrl=["http://localhost:3000/*"]' \\\n--data-urlencode "tenant=tenant1" \\\n--data-urlencode 'product=supertokens' \\\n--data-urlencode 'name=supertokens-config' \\\n--data-urlencode 'description=SuperTokens + BOXYHQ SAML config'`, `29171190742701203000`)\"\n >\n \n \n \n \n

curl --location --request POST 'http://localhost:5225/api/v1/saml/config' \\\n--header 'Authorization: Api-Key secret' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'encodedRawMetadata=<BASE_64_XML>' \\\n--data-urlencode 'defaultRedirectUrl=http://localhost:3000/auth/callback/saml-jackson' \\\n--data-urlencode 'redirectUrl=[\"http://localhost:3000/*\"]' \\\n--data-urlencode \"tenant=tenant1\" \\\n--data-urlencode 'product=supertokens' \\\n--data-urlencode 'name=supertokens-config' \\\n--data-urlencode 'description=SuperTokens + BOXYHQ SAML config'
\n

It will output a client id and client secret; save those for the following steps.

\n

Add and configure SuperTokens tenants

\n

Run the following command to add a tenant to SuperTokens that supports SSO:

\n\n \n \n \n \n
curl --location --request PUT 'http://localhost:3567/recipe/multitenancy/tenant' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"tenantId\": \"tenant1\",\n    \"emailPasswordEnabled\": false,\n    \"thirdPartyEnabled\": true,\n    \"passwordlessEnabled\": false\n}'
\n

Add boxy-saml login to tenant1

\n

Now run the following command to connect your SSO integration with SAML Jackson. The API key is only required for production.

\n' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n "config": {\n "thirdPartyId": "boxy-saml",\n "name": "SAML Login",\n "clients": [\n {\n "clientId": "",\n "clientSecret": "",\n "additionalConfig": {\n "boxyURL": "http://localhost:5225"\n }\n }\n ]\n }\n}'`, `83778195575611970000`)\"\n >\n \n \n \n \n
curl --location --request PUT 'http://localhost:3567/tenant1/recipe/multitenancy/config/thirdparty' \\\n--header 'api-key: <API_KEY>' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n  \"config\": {\n    \"thirdPartyId\": \"boxy-saml\",\n    \"name\": \"SAML Login\",\n    \"clients\": [\n      {\n        \"clientId\": \"<ClientID from curling to Boxxy HQ>\",\n        \"clientSecret\": \"<ClientSecret from curling to Boxxy HQ>\",\n        \"additionalConfig\": {\n          \"boxyURL\": \"http://localhost:5225\"\n        }\n      }\n    ]\n  }\n}'
\n

Test the application

\n

Run npm run start to start the application. Go to http://localhost:3000 in your browser, select tenant 1, and log in with SAML. Once you log in, you’ll be able to see the success screen with your user ID.

\n

Wrapping up

\n

Although other alternatives for SSO exist, SAML is still a common SSO option for large companies tying into IAM platforms. It may be an older technology than alternatives like OpenID Connect, but that in no way makes it an invalid option. If you’re building an application in the B2B space, try building your application with SuperTokens!

","frontmatter":{"date":"August 20, 2024","title":"Demystifying SAML: A Comprehensive Guide","cover":"demystifying-saml.png","author":"Connor Peshek","description":"SAML is an authentication standard created to address the growing need of federated identity. In this blog we go over what SAML is and what makes it special."},"fields":{"slug":"/demystifying-saml/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"f7701607-f3d9-5b83-b13f-b3ed8205d21d","fields__slug":"/demystifying-saml/","__params":{"fields__slug":"demystifying-saml"}}}, "staticQueryHashes": []}