Single Sign On

You may extend your Mason Auth feature to include Single Sign On (SSO) capability, or compliment your existing authentication implementation using Mason to add SSO.

Getting Started

Mason supports any SAML 2.0 Identity Provider. These docs use Okta as an example, but the steps are similar for any provider.

How It Works

Mason SSO allows you to provide SSO functionality to your users while still using the typical username and password authentication scheme. Mason communicates with your chosen Identity Provider (IdP) and reports a successful authentication request to your backend.

Your user navigates to your authentication URL, and is presented with a Mason feature including an SSO button. When clicked, she will be redirected to your IdP to provide her credentials. On successful authentication, your IdP will send an authentication assertion to Mason; we will validate it and inform your application that she has successfully authenticated.


  • Identity Provider (IdP) - a service that authenticates users and asserts that authentication has occurred; in this guide, Okta

  • Service Provider (SP) - a system that receives the authentication assertion from the IdP; Mason will proxy this on your behalf

  • IdP SSO URL - the destination where your users should be redirected to to authenticate with your IdP; you'll find this in your IdP setup instructions

  • Identity Provider Issuer - Identifies your IdP via URI (Uniform Resource Identifier).

  • X 509 Certificate - a public certificate provided by your IdP that allows Mason to verify that the authentication claims are authentic; you'll find this in your IdP setup instructions

  • SSO Success Callback - a URL Mason will call upon successful authentication with your IdP, you must implement this on your backend

Integration and Setup

In order to use Mason SSO, you must have an account with an IdP provider. If you don't have one, you can create an Okta free trial here. Follow the instructions to add your application as an SP, and use as your Single sign on URL.

You provide four pieces of information from your IdP to correctly configure your Mason SSO integration

  1. IdP SSO URL

  2. Identity Provider Issuer

  3. X 509 Certificate

  4. SSO Success Callback (you may leave this blank if you don't have one yet)

Follow the steps below to add SSO to your Mason Login feature in the Mason Builder.

  1. Create a Mason Login feature and configure it to work with your authentication API. If you are handling username/password based authentication yourself, you should remove the form from the Login feature

  2. Open the Integrations panel in the left toolbar of the Mason Builder

  3. In the SSO section, add the fields listed above

  4. Add a new Button to the feature canvas and click on it to select it

  5. In the right toolbar panel, enter your desired text, and change the When Clicked value to Handle SSO

  6. Save, Publish, and Export your feature

  7. Embed the Mason feature in your application where you want your users to authenticate

Server-side Validation

Your user has provided her credentials to your IdP, and Mason has validated that the user has successfully authenticated. Now, we need to inform your system so you can mark the user as authenticated, and set any cookies or sessions your system requires.

Mason will send a server to server POST request to the URL you provided as the SSO Success Callback containing the following JSON payload in the request body:


To handle this request, your system should first validate that the verificationToken parameter matches your Mason Verification Token - this allows you to be sure the request originates from Mason. If it does, it should save the nonce on the user's account for later retrieval. Your system must respond with a 2xx HTTP response.

Client-side Validation

Your system has received the nonce from Mason and responded with a 2xx, and Mason has redirected your user back to your authentication URL (where your feature is embedded). The Mason feature will now send a POST request to your authentication API endpoint containing the following JSON payload in the request body:


To handle this request, your system should retrieve the user with matching id, and validate that the nonce that was previously saved matches the nonce in the request body. The nonce should be invalidated at this point.

If the nonce matches, you may consider your user successfully authenticated, and respond with an HTTP status 2xx and any desired JSON response body. If it does not, you should respond with an HTTP 4xx or 5xx.

Upon receipt of a 2xx status, your Mason feature will call the didReceiveData callback, if you've provided one. This callback will receive the response body as an argument, so you can make any client-side state changes necessary to finalize the authentication process. You should dispatch a redirect here if required.