diff --git a/content/demystifying-saml/index.md b/content/demystifying-saml/index.md
index 6d6e406e..94641646 100644
--- a/content/demystifying-saml/index.md
+++ b/content/demystifying-saml/index.md
@@ -1,111 +1,213 @@
---
title: "Demystifying SAML: A Comprehensive Guide"
-date: "2024-01-16"
+date: "2024-08-20"
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."
cover: "demystifying-saml.png"
category: "featured"
-author: "Michiel Mulders"
+author: "Connor Peshek"
---
+## Table of Contents
-
+- [Introduction](#introduction)
+- [What is Single Sign-On (SSO)?](#what-is-single-sign-on-sso)
+- [How Does SAML Authentication Work?](#how-does-saml-authentication-work)
+- [The Benefits Of SAML Authentication](#the-benefits-of-saml-authentication)
+- [What Is The Difference Between SAML and SSO?](#what-is-the-difference-between-saml-and-sso)
+- [When To Choose SAML For Your Security Protocol](#when-to-choose-saml-for-your-security-protocol)
+- [Implementing SAML Authentication](#implementing-saml-authentication)
+- [Wrapping up](#wrapping-up)
-SAML or the Security Assertion Markup Language was created in November 2002 to address the growing need for federated identity enabling users to access multiple applications and domains across multiple identity management systems.
+## Introduction
-The standard quickly gained traction among companies looking to streamline application interoperability, increase security without sacrificing end-user usability.
+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.
-In this article we aim to demystify SAML by breaking down it's inner workings and benefits.
+## What is Single Sign-On (SSO)?
-## Understanding SAML: The Basics
+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.
-SAML, or Security Assertion Markup Language, is an open standard that enables secure, cross-domain communication for authentication and authorization. It lets users log in once and access multiple applications and services without repeatedly entering login credentials.
+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.
+## How Does SAML Authentication Work?
-### Step 1: Initiate the flow
+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.
-The SAML flow starts with a user attempting to access a service or application (SP). They are redirected to a centralized authentication system called the identity provider.
+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.
-### Step 2: Issuing an Assertion
-Once the idP has verified the credentials, it returns an assertion to the service provider. An assertion is like a digital certificate from the identity provider that contains information about the user, such as their identity and the access rights or roles they have.
+## The Benefits Of SAML Authentication
-### Step 3: Validation
-Finally, the service provider receives the assertion and determines if the user should get access and what resources they can access based on their roles.
+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.
+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.
-In short, SAML provides users with fast and seamless access to services without prompting for an email, username, or password. They only need to log in once to access a plentitude of applications or services that are connected to the same identity provider.
+## What Is The Difference Between SAML and SSO?
-## How SAML works: Under the hood
+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.
-Let's dive one level deeper into SAML and how the XML-based standard works.
+## When To Choose SAML For Your Security Protocol
-Below is an example of a SAML authentication request sent from a service provider to an identity provider, requesting to authenticate a user.
+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.
-```xml
-
- https://myService/metadata.php
-
-
- urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
-
-
+## Implementing SAML Authentication
-```
+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.
+
+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.
+
+Let's get started.
+
+### Microsoft Entra ID
+
+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](https://entra.microsoft.com/) and select **Enterprise Applications** on the left side.
+
+
+
+Click on **New application** at the top of the page.
+
+
+
+Then click on **Create your own application** at the top. Input your application name, select **Integrate any other application you don't find in the gallery (Non-gallery)** and click **Create**.
+
+
+
+Now that our application is created, we need to set up Single Sign-On. Select **Single Sign-On** from the sidebar and choose the **SAML** option.
+
+
+
+Click the **Edit** button in the Basic SAML Configuration.
+
+
+
+And add the following values to your application:
-Let's break down this request.
-- **`samlp:AuthnRequest`**: This root element of the XML request indicates the start of a SAML protocol message.
-- Attributes of `samlp:AuthnRequest`:
- - `ID`: Unique identifier to distinguish it from other requests
- - `Version`: Specifies which version of the SAML standard we want to use. The latest version is 2.0.
- - `ProviderName`: Identifies the service provider sending the request, here labeled as “SP authHeroes”.
- - `IssueInstant`: Datetime to timestamp when the request was sent.
- - `Destination`: Lists the identity provider’s SSO service where the request is being sent.
- - `ProtocolBinding`: Specifies the protocol to be used for the identity provider’s response. In this case, we want to use a HTTPS POST request.
- - `AssertionConsumerServiceURL`: Specifies the URL where the service provider expects a response from the identity provider.
-- **`saml:Issuer`**: Lists a URL containing metadata to uniquely identify the service provider.
-- **`samlp:NameIDPolicy`**: The service provider and identity provider can agree upon an identifier for the user’s account. In this case, the email address represents the user who’s being authenticated. If omitted, any type of identifier can be used.
+- **Entity ID** - `https://saml.boxyhq.com`
+- **Reply URL** - `http://localhost:5225/api/oauth/saml`
-This is a basic example of an authentication request a service provider can send to an identity provider. To prove authenticity, you can expand an authentication request with many more attributes like signatures or certificates.
+Then click **Save** at the top.
-In total, the SAML 2.0 specification consists of 86 pages of technical details. If you want to look up specific elements or give it a read, you can find it under [docs.oasis-open.org](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf).
+
+Scroll down to section 3 and download the Federation Metadata XML—we'll need this later to upload into SAML Jackson.
-## Understanding the SAML Workflow
+Click **Users and groups** on the sidebar and then **Add user/group** at the top of the page.
-To better understand the SAML workflow, let’s set the stage with Alice wanting to request a Google Drive resource. Alice is an employee of company X and logs in to their employee identity provider. Now, Alice can access various applications like Expensify, Google Drive, or Asana.
+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.
-When Alice selects the file she wants to open via Google Drive in the dashboard, she can immediately access it. But how? Let’s explore the SAML workflow to understand better why Alice can access the resource directly from her company dashboard.
+
-**Step 1: User Access Request**
-It all starts with the Alice wanting to access a Google Drive resource.
+### Prepare SuperTokens
-**Step 2: Redirect to Identity Provider**
-If Alice is not authenticated, the login request is forwarded to the identity provider. This request uses the SAML request format, as seen in the example in the previous section.
+In order to set up SuperTokens, we need to download our quickstart which contains the front-end and back-end SDK along with the SuperTokens core, which manages user and session state for SuperTokens. Since SAML is commonly used for corporate integrations, we'll make this project a multitenant project.
-**Step 3: Authentication at Identity Provider**
-The identity provider will check if Alice is logged in or not. If not, Alice has to log in first. Once logged in, the identity provider will return Alice’s identity and authorization level for Google Drive (service).
+First, download the SuperTokens core and run it using Docker:
-**Step 4: Assertion Transfer to Service Provider**
-Do you remember the `AssertionConsumerServiceURL` field in our sample authentication request? The assertion is returned to Google Drive, listed at the `AssertionConsumerServiceURL`. This digital certificate contains the user’s information, authentication level, and roles.
+```bash
+docker run -p 3567:3567 -d registry.supertokens.io/supertokens/supertokens-postgresql:9.1.2
+```
+
+### Connect SuperTokens to local core
+
+To connect your project to your locally running core, head to the `backend/config.ts` and change the connectionURI to `http://localhost:3567`.
+
+```ts
+import supertokens from "supertokens-node";
+
+supertokens.init({
+ supertokens: {
+ connectionURI: "http://localhost:3567",
+ // only required for production
+ apiKey: "",
+ },
+ appInfo: {
+ apiDomain: "...",
+ appName: "...",
+ websiteDomain: "...",
+ },
+ recipeList: [],
+});
+```
+
+Now that we've configured our project, we can start setting up SAML Jackson.
-**Step 5: Service Provider Validates Assertion**
-Once Google Drive has received the assertion request, it will validate if the request came from a trusted identity provider based on the attached keys and signatures. Using this information, a service provider can check the authenticity of the assertion.
+### Start the SAML Jackson service
-**Step 6: Grant Access to the User**
-Now that Google Drive is sure that they can trust the identity provider and the request hasn’t been tampered with, Alice is granted access. Google Drive determines whether Alice can view the file based on the returned authorization level, role, or attributes.
+Run the following command to download and run the SAML Jackson docker container:
+```bash
+docker run \
+ -p 5225:5225 \
+ -e JACKSON_API_KEYS="secret" \
+ -e DB_ENGINE="mem" \
+ -e NEXTAUTH_SECRET="super-secret" \
+ -e NEXTAUTH_ADMIN_CREDENTIALS="admin@company.com:secretpassword" \
+ -d boxyhq/jackson
+```
+
+This will start the SAML Jackson server on `http://localhost:5225`.
-## SAML: The Benefits
-Let’s list the benefits of using SAML for authentication:
+### Add your XML to Boxxy SAML
-- **Enhanced security**: By centralizing authentication, you are reducing the attack vector. Additionally, organizations don’t have to store user passwords, which decreases their liabilities.
-- **Scalability**: Service providers can decide to quickly add new services to their offering, using the same login system. There’s no need for significant changes when adding more services.
-- **Improved user experience**: Users can log in faster and can avoid password fatigue.
-- **Improved compliance and reporting**: Auditing user access requests and activities across multiple services is more straightforward.
+Run the following command to configure SAML Jackson with your downloaded xml, replacing the encodedRawData with a base64 encoded copy of your XML file.
+
+```bash
+curl --location --request POST 'http://localhost:5225/api/v1/saml/config' \
+--header 'Authorization: Api-Key secret' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'encodedRawMetadata=' \
+--data-urlencode 'defaultRedirectUrl=http://localhost:3000/auth/callback/saml-jackson' \
+--data-urlencode 'redirectUrl=["http://localhost:3000/*"]' \
+--data-urlencode "tenant=tenant1" \
+--data-urlencode 'product=supertokens' \
+--data-urlencode 'name=supertokens-config' \
+--data-urlencode 'description=SuperTokens + BOXYHQ SAML config'
+```
+
+It will output a client id and client secret; save those for the following steps.
+
+### Add and configure SuperTokens tenants
+
+Run the following command to add a tenant to SuperTokens that supports SSO:
+
+```bash
+curl --location --request PUT 'http://localhost:3567/recipe/multitenancy/tenant' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "tenantId": "tenant1",
+ "emailPasswordEnabled": false,
+ "thirdPartyEnabled": true,
+ "passwordlessEnabled": false
+}'
+```
+
+### Add boxy-saml login to tenant1
+
+Now run the following command to connect your SSO integration with SAML Jackson. The API key is only required for production.
+
+```bash
+curl --location --request PUT 'http://localhost:3567/tenant1/recipe/multitenancy/config/thirdparty' \
+--header 'api-key: ' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "config": {
+ "thirdPartyId": "boxy-saml",
+ "name": "SAML Login",
+ "clients": [
+ {
+ "clientId": "",
+ "clientSecret": "",
+ "additionalConfig": {
+ "boxyURL": "http://localhost:5225"
+ }
+ }
+ ]
+ }
+}'
+```
+### Test the application
-## SAML vs OAuth 2.0
+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.
-Both SAML and OAuth allow users to access multiple applications with a single sign on, but, the difference is that OAuth is easier to use and also gives an access token that can be used to call APIs on the identity provider to read/write on the user's behalf. SAML does not have this ability but tends to be the ideal choice for secure access to sensitive data in organizations such as healthcare or government due to the baked in encryption. OAuth relies on SSL/TLS protocols for security. You can learn more about [SAML vs OAuth here](https://supertokens.com/blog/saml-vs-oauth).
+## Wrapping up
-## Conclusion
-SAML's flexibility and scalability make it an ideal choice for organizations of all sizes. Whether it's streamlining access to multiple applications or ensuring secure authentication, SAML is a versatile authentication protocol that can be employed in various use cases. In short, SAML offers a more secure, efficient, and interconnected digital future.
+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!
\ No newline at end of file
diff --git a/content/demystifying-saml/ms-entra--setup-1.png b/content/demystifying-saml/ms-entra--setup-1.png
new file mode 100644
index 00000000..225c0092
Binary files /dev/null and b/content/demystifying-saml/ms-entra--setup-1.png differ
diff --git a/content/demystifying-saml/ms-entra-setup-2.png b/content/demystifying-saml/ms-entra-setup-2.png
new file mode 100644
index 00000000..b3220548
Binary files /dev/null and b/content/demystifying-saml/ms-entra-setup-2.png differ
diff --git a/content/demystifying-saml/ms-entra-setup-3.png b/content/demystifying-saml/ms-entra-setup-3.png
new file mode 100644
index 00000000..f75c927d
Binary files /dev/null and b/content/demystifying-saml/ms-entra-setup-3.png differ
diff --git a/content/demystifying-saml/ms-entra-setup-4.png b/content/demystifying-saml/ms-entra-setup-4.png
new file mode 100644
index 00000000..ccdd2c6e
Binary files /dev/null and b/content/demystifying-saml/ms-entra-setup-4.png differ
diff --git a/content/demystifying-saml/ms-entra-setup-5.png b/content/demystifying-saml/ms-entra-setup-5.png
new file mode 100644
index 00000000..147a9a39
Binary files /dev/null and b/content/demystifying-saml/ms-entra-setup-5.png differ
diff --git a/content/demystifying-saml/ms-entra-setup-6.png b/content/demystifying-saml/ms-entra-setup-6.png
new file mode 100644
index 00000000..89caaeaf
Binary files /dev/null and b/content/demystifying-saml/ms-entra-setup-6.png differ
diff --git a/content/demystifying-saml/ms-entra-setup-7.png b/content/demystifying-saml/ms-entra-setup-7.png
new file mode 100644
index 00000000..81de6c42
Binary files /dev/null and b/content/demystifying-saml/ms-entra-setup-7.png differ