Skip to main content

Overview

Learn how SAML facilitates secure information exchange between authentication servers and client applications.

SAML, or Security Assertion Markup Language, is an open protocol that exchanges information between the auth server and the client application. Some identity providers require OAuth 2.0 for user login, some require SAML, and some can work with both.

How it works?​

Your SAML identity provider has a metadata file (.xml) that you or your end users need to upload to the SAML client.

The .xml metadata file contains (amongst other things):

  • A unique entity ID that you must keep private. The SAML provider uses this to identify your application.
  • A public certificate that verifies the signature attached to the incoming SAML response. This ensures the response is coming from the expected Identity Provider.
  • Information about where to redirect the end user to when they click on the login button in your application. This URL is to a website controlled by the SAML provider and asks the end user for their credentials.

Add SAML login with SuperTokens​

SuperTokens is not a SAML client. This means that you have to use a third-party solution along with SuperTokens to integrate with a SAML provider. The way this works is that the third-party solution acts as an OAuth 2.0 provider to SuperTokens, and a SAML client to the SAML provider:

Flowchart explaining integration of a `SAML` provider with SuperTokens using a third-party solution

BoxyHQ​

BoxyHQ is a commercial open-source company that has a product called "SAML Jackson" which helps integrate SAML providers into your application.

SAML Jackson is a perfect fit with SuperTokens because:

  • It's an OAuth provider and a SAML client. This fits with the architecture.
  • For self hosted, it supports PostgreSQL and MySQL amongst other databases. Self hosted SuperTokens supports PostgreSQL and MySQL as well.

SAML Jackson provides an HTTP service that you can host yourself or let BoxyHQ manage. The HTTP service uses NodeJS, and is embeddable within your NodeJS backend. However, because SuperTokens supports multiple backends, the focus is on deploying SAML Jackson as a microservice.

Flowchart of integrating a `SAML` provider with SuperTokens using `SAML` Jackson ( BoxyHQ )
  1. The user clicks on the login button and redirects to SAML Jackson's microservice at http://localhost:5225/api/oauth/authorize
  2. SAML Jackson redirects the user to the SAML provider's login page where the user needs to enter their credentials
  3. After successfully authenticating the user, the SAML provider redirects the user to SAML Jackson. Step (2) and (3) follow the SAML protocol.
  4. SAML Jackson redirects the user to the frontend app on the configured callback URL. The callback URL contains the one-time use auth code.
  5. SuperTokens' frontend SDK passes the one-time use auth code to your app's backend.
  6. SuperTokens' backend SDK verifies the auth code by querying SAML Jackson. On success, SAML Jackson returns the end user's information and access token.
  7. SuperTokens' backend SDK creates a new user in the core associated with the end user's email. New session tokens are also created
  8. A SuperTokens' session establishes between your app's backend and frontend - logging in the user.
Example App

An example app on GitHub with SuperTokens + SAML Jackson, for React and NodeJS express apps, is available. This uses mocksaml.com as a SAML provider