API Reference
Log In
API Reference

Single Sign On (SSO) Integration

Single sign-on (SSO) is a session and user authentication service that permits a user to use one set of login credentials -- for example, a username and password -- to access multiple applications. borderless™ allows SSO to be used by Partner accounts in order for users to get authenticated using the Partner's application credentials to avoid the creation of multiple credentials and have a direct authentication integration for a seamless user experience.

Open Authorization (OAuth) is the framework that enables an end user's account information to be used by third-party services, such as Google, without exposing the user's password.

OAuth acts as an intermediary on behalf of the end user by providing borderless™ with an access token that authorizes specific account information to be shared. When a user attempts to access borderless™ application from the Partner, borderless™ sends a request to the Partner for authentication. borderless™ then verifies the authentication and logs the user in.

📘

Note:

To enable Single Sign-On (SSO) functionality, it is imperative to initiate a discussion with your dedicated account manager and incorporate it as part of the comprehensive solution in the Partner flow. This ensures a seamless integration tailored to your specific requirements.

Login Workflow

The goal of the login workflow is to allow a user previously configured at the Partner platform to log in into borderless™ with their credentials. This is accomplished in the following steps

  1. borderless™ redirects the user browser to the Partner application and authentication endpoint ( example: /authenticate).
  2. The user inserts his credentials and logs in on the Partner platform.
  3. The browser is redirected back to borderless™ according to the redirect url that would be defined during the first API call.
  4. borderless™ requests and receives an access token ( example: /tokens).
  5. borderless™ uses the access token to query information about the user ( example: /users).
  6. borderless™ receives information about the user and logs him in according to your rules.

SSO Must Be Configured On Partner First

For borderless™ to utilize Single Sign On, the Partner account must have SSO already configured and enabled. If you utilize a third party login such as Auth0 or others, these endpoints might already be created and thus need to be shared with borderless™. Here are a few endpoints that are required for borderless™ to complete an SSO integration:

Create Client id and Client Secret for borderless™

This solution follows the OAuth2 authorization code workflow (https://tools.ietf.org/html/rfc6749#page-8) and in order to successfully integrate borderless™, borderless™ will need credentials such as client id and client secret. Please generate and share those keys with your account manager or solution integration manager.

Create Auth Endpoint For borderless™ to Redirect User & Authenticate

Partner must have an endpoint to redirect users for authentication. Whenever a user needs to be authenticated into borderless, it should start a Login Workflow. In order to do that, borderless™ only needs to redirect the user to the Partner authentication endpoint (example: GET - /authenticate) passing a few parameters in the request string such as the client id of borderless™ (client_id), the URL to redirect the user back to borderless™ after a successful workflow (redirect_url) and some other mandatory parameters (scope=openid, response_type=code) for OAuth2. borderless™ will share the (redirect_url) with the Partner to configure on their end.

Create Endpoint to Request Access Token

After the Partner has successfully authenticated the user, it will redirect the browser back to borderless - more specifically to the URL borderless provided with the redirect_url parameter. With the redirect borderless will receive a parameter code in the query string. When the user is back to borderless, borderless will request an access token in order to perform further calls to query user information. This can be done by performing a server-to-server call to the Token endpoint (example: POST - /tokens), passing the value of the code parameter received in conjunction with the same request_uri sent on the first redirect, the client id and client secret for borderless™ and some mandatory parameters (grant_type=authorization_code, scope=openid) for OAuth2.

Create Endpoint To Request User Information

After the Partner has successfully authenticated the user and borderless™ acquired an access_token, this token can be used to query user information at the dedicated user endpoint (example: GET - /users). borderless™ receives information such as name, email address, username, role, etc. Then the user is logged in to borderless using the correct parameters.

Logout Workflow

The goal of the logout workflow is to safely log out the user in your application and also make sure that borderless™ is aware that the user has logged out. A correct logout workflow should consist of:

  1. The user desires to log out from borderless™ (by clicking on a "Logout" link for example).
  2. borderless logs his user session out from the borderless™ session
  3. borderless™ then redirects the browser to the logout endpoint (example: /logout) passing the url from borderless™ to redirect the user back after a logout (example: post_logout_redirect_uri).
  4. The Partner logs the user out

Create A Logout Endpoint

When an user wants to logout from borderless™, borderless™ first clears the user local session in the local server, and then redirect the browser to the logout endpoint (example: GET /logout). borderless™ would add the parameter post_logout_redirect_uri indicating to which URL should the user be redirected in borderless™ after logout.

Session Tracking FAQ

The session tracking workflow allows borderless™ to check if the user is still remotely logged in - which means it still has a valid session with the Partner and has still not logged out of borderless™. Whenever a user logs out, borderless™ will receive a notification and can act upon it. After performing any specific action, borderless™ starts a new Login Workflow in case the user wants to log in again.