EMS Single Sign-On (SSO)

Developer Integration Guide

1. Introduction

Welcome to the EMS SSO service. This guide will walk you through the process of integrating our authentication system into your web application. Our system uses a standard OAuth 2.0-like redirect flow, making it secure and straightforward to implement.

2. Authentication Flow

The authentication process is a simple redirect-based flow:

  1. Your application redirects the user to the EMS SSO login page with your unique client_id.
  2. The user logs in with their EMS credentials and approves your application's request for access.
  3. The EMS SSO server redirects the user back to a pre-configured Callback URL on your site, providing a short-lived access token.
  4. Your application's callback page receives the token, stores it securely (e.g., in sessionStorage), and redirects the user to a protected area of your site.
  5. Your application can then use this token to fetch the authenticated user's profile information from our API.

3. Getting Started: Your Credentials

Prerequisite: Before you can begin integration, you must register your application with us to receive your credentials.

To get started, you will need to provide us with the following information:

Once we have registered your application, we will provide you with your unique Client ID. You will need this for the integration.

4. Implementation Guide

Step 1: Create the Login Link

On your application's login page, create a link or button that directs the user to the EMS SSO server. The URL must be constructed with the following query parameters:

Parameter Description
client_id Required. The unique Client ID provided to you by the EMS admin.
redirect_uri Required. The URL-encoded version of the Callback URL you registered with us. This must be an exact match.

Step 2: Create the Callback Page

This is a temporary page in your application that handles the response from the SSO server. Its only job is to capture the token from the URL, save it, and redirect the user.

Important: The URL of this page must exactly match the redirect_uri you provided during setup.

Create a file (e.g., callback.html) with the following content:

<!DOCTYPE html>
<html>
<head>
    <title>Authenticating...</title>
    <script>
        window.onload = () => {
            const params = new URLSearchParams(window.location.search);
            const token = params.get('token');
            const error = params.get('error');

            if (token) {
                // Success! Store the token in session storage.
                sessionStorage.setItem('ems_token', token);
                // Redirect to your app's main protected page.
                window.location.href = '/dashboard.html'; 
            } else {
                // Handle login failure or denial.
                console.error('SSO Error:', error || 'Authentication failed');
                // Redirect to the login page with an error message.
                window.location.href = '/index.html?error=login_failed';
            }
        };
    </script>
</head>
<body>
    <p>Please wait, we are securely logging you in...</p>
</body>
</html>

Step 3: Fetching User Data from a Protected Page

On any page that requires authentication, first check for the token in sessionStorage. If it exists, you can make an authenticated request to our API to get the user's details.

The request must include the token in the Authorization header.

Step 4: Handling Logout

To log a user out, simply remove the token from sessionStorage and redirect them to your public-facing home or login page.

function logout() {
    sessionStorage.removeItem('ems_token');
    window.location.href = '/index.html';
}

5. API Reference

Authentication Endpoint

This is the endpoint where you redirect users for login.

User Profile Endpoint

Use this endpoint to retrieve the authenticated user's information.