API Single Sign-On

Owned by Jonathan Tew
Last updated: Jul 16, 2021
3 min read

Introduction

This tutorial will explain how to use the REST SDK to perform a single sign-on integration. Developers interested in this tutorial are those that are building internal applications, what their users to login via UltraCart, and then have their permissions listed to that of their UltraCart user.

Pre-requisites

The Single Sign-on endpoint is available in SDK versions 3.3 or higher. Make sure to upgrade your SDK to the minimum required version before attempting to follow this SDK.

Your authorized application will need the Single Sign-on write permission in order to perform these operations.

Starting the Single Sign-on Process

The first step is to call the ssoAuthorize API function. This function will require you to specify two parameters:

  • Redirect URI - the URL that you want the customer’s browser returned to after authentication

  • State - a parameter value that you make up. We recommend a UUID that you then store in the user’s session so that you can compare when the user’s browser is redirected back.

The function will return two values:

  • Login URL - this is the URL you should redirect the user’s browser to. It will begin the login process.

  • Expiration - the expiration after which this single sign on must be completed.

So call ssoAuthorize and send the customer’s browser the login URL as a redirect.

Handling the Return

After the customer authorizes the single sign-on, UltraCart will redirect the customer’s browser back to the URL that you specified. On the URL there were be two parameters:

  • code

  • state

The first thing you should do is verify that the state returned in the parameter matches the state that you originally passed in to the ssoAuthorize call.

Next, take the code value and call ssoToken API. This will exact your access code for a longer lived simple key. When calling ssoToken you will pass the parameters:

  • grant_type = simple_key

  • code = the value you received back as a URL parameter

This function will return two values:

  • simple_key - this is the key that you will then use to make SDK API calls on behalf of the user.

  • expiration_dts - the expiration of the key

At this point you will shift to using the simple_key to make API calls on behalf of the user. Your API calls will be limited to the permissions of their user.

Protect the Simple Key

The simple key is a critical piece of information. You should protect it all cost!

 

Obtaining the User that You’re Signed Into

After they authenticate, you’ll often want to know which user logged in. To obtain that information you will want to call the getSsoSessionUser API call.

This API call will return a User object that provides all the details of the user including which permissions they have. You can consult this object to decide on which features of your application you want to expose to the user.

Signing Out

We also provide an ssoSessionRevoke API that will expire the user’s session. We recommend that you have a logout button on your application that turns avoid and expires the session using this API.