Single Sign-On

Single Sign-on (SSO) occurs when a user logs in to one application and is then signed in to other applications automatically, regardless of the platform, technology, or domain the user is using. The user signs in only one time, hence the name of the feature (Single Sign-on).

For example, if you log in to a Google service such as Gmail, you are automatically authenticated to YouTube, Google Drive, Google Analytics, and other Google apps. Likewise, if you log out of your Gmail or other Google apps, you are automatically logged out of all the apps; this is known as Single Logout.

How it works with Epixel MLM Software

For the implementation of SSO service, the services connected to our system are considered as two types of services. ie; host and client services.

The service in which the user logs directly is called host service and the services which are logged from this host service is called the client service.

Workflow:-

  • Login

  1. user logs in to a service by using login credentials (host).

  2. an API session-id is created in the host service.

  3. when the user requests another service, a request is sent to the particular login endpoint of the requested service with a single time token.

  4. then using the received single time token and an apikey a request is sent to the host service to validate the request. after validating the request an API session-id and an access token are returned.

  5. in the client service using the access token user is authenticated. and an acknowledgment is sent to the host service. Logout

  • Logout

if a user requests log out from any of the services it will automatically log out the user from all services.

  1. Log out from the host service

    • a request with API session-id is sent to the logout end point of all the services which are logged in using the host service.

    • then the client service will destroy the session related to the API session-id.

  2. Log out from the client service

    • The API session id is passed to the host service.

    • then the host service will destroy all the sessions related to the API session-id.

    ​

Single Sign-On Service Request

put
​

β€Žhttps://<domain>/<sso prefix>/<version>/service-request/
This endpoint will return a unique login URL of the requested service. Normally this is an in-site ajax request.
Request
Response
Request
Body Parameters
service
required
string
service slug
Response
200: OK
HTTP/1.1 200 OK
Content-Type: application/json
​
Body:
{
"status_code": 200,
"errors": {},
"data": {
"url": "<unique user login url>"
}
}

Error Responses

Status Code

Error Type

Field

Description

400

Validation Error

service

This field is required.

400

Validation Error

service

This field may not be blank.

403

Permission Denied

​

Please login first to continue.

500

Server Error

​

Service request failed.

500

Server Error

​

No Service user found. Please contact admin.

500

Server Error

​

Service not registered. Please contact admin.

Single Sign-On External Service Request

post
​

β€Žβ€Žβ€Žβ€Žβ€Žβ€Žβ€Žβ€Žhttps://<domain>/<api prefix>/<version>/sso/service-request/
Requesting unique login url for another service from host service This API endpoint will return unique login url for the requested service
Request
Response
Request
Headers
apikey
required
string
apikey
Body Parameters
service
required
string
service slug
api_sid
required
string
api session id
Response
200: OK
HTTP/1.1 200 OK
Content-Type: application/json
​
Body:
{
"status_code": 200,
"errors": {},
"data": {
"url": "<unique user login url>"
}
​
}

Sample code

Node

var request = require('request');
var options = {
'method': 'POST',
'url': 'https://<domain>/<api prefix>/<version>/sso/service-request/',
'headers': {
'apikey': '<apikey>'
},
formData: {
'service': '<service slug>',
'api_sid': '<api session id>'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});

PHP

<?php
​
$curl = curl_init();
​
curl_setopt_array($curl, array(
CURLOPT_URL => "https://<domain>/<api prefix>/<version>/sso/service-request/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => array('service' => '<service slug>','api_sid' => '<api session id>'),
CURLOPT_HTTPHEADER => array(
"apikey: <apikey>"
),
));
​
$response = curl_exec($curl);
​
curl_close($curl);
echo $response;

Error Responses

Status Code

Error Type

Field

Description

400

Validation Error

service

This field is required.

400

Validation Error

api_sid

This field is required.

400

Validation Error

service

This field may not be blank.

400

Validation Error

api_sid

This field may not be blank.

404

No Session Found

​

No Logged-in session found with this api_sid.

500

No Service Found

​

Service not registered. Please contact admin.

Single Sign-On URL Token Verify

post
​

β€Žβ€Žhttps://<domain>/<api prefix>/<version>/sso/token-verify/
This endpoint will return an API session-id and an access token.
Request
Response
Request
Headers
apikey
required
string
apikey
Body Parameters
token
required
string
url token
Response
200: OK
HTTP/1.1 200 OK
Content-Type: application/json
​
Body:
{
"status_code": 200,
"errors": {},
"data": {
"api_sid": "<api session id>",
"auth_token": "<access token>"
}
}

Sample code

Node

var request = require('request');
var options = {
'method': 'POST',
'url': 'https://<domain>/<api prefix>/<version>/sso/token-verify/',
'headers': {
'apikey': '<api key>'
},
formData: {
'token': '<url token>'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});

PHP

<?php
​
$curl = curl_init();
​
curl_setopt_array($curl, array(
CURLOPT_URL => "https://<domain>/<api prefix>/<version>/sso/token-verify/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => array('token' => '<url token>'),
CURLOPT_HTTPHEADER => array(
"apikey: <api key>"
),
));
​
$response = curl_exec($curl);
​
curl_close($curl);
echo $response;

Error Responses

Status Code

Error Type

Field

Description

400

Validation Error

token

This field is required

400

Validation Error

token

This field may not be blank.

400

Validation Error

token

Invalid token.

500

Server Error

​

Token generation failed

Single Sign-On Login Acknowledgment

post
​

β€Žβ€Žβ€Žβ€Žβ€Žβ€Žβ€Žβ€Žβ€Žhttps://<domain>/<api prefix>/<version>/sso/login-acknowledgement/
This endpoint will acknowledge the host service.
Request
Response
Request
Path Parameters
required
string
apikey
Body Parameters
api_sid
required
string
api session id
service
required
string
service slug
Response
200: OK
HTTP/1.1 200 OK
Content-Type: application/json
​
Body:
{
"status_code": 200,
"errors": {},
"data": {}
}

Sample code

Node

var request = require('request');
var options = {
'method': 'POST',
'url': 'https://<domain>/<api prefix>/<version>/sso/login-acknowledgement/',
'headers': {
'apikey': '<api key>'
},
formData: {
'service': '<service slug>',
'api_sid': '<api session id>'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});

PHP

<?php
​
$curl = curl_init();
​
curl_setopt_array($curl, array(
CURLOPT_URL => "https://<domain>/<api prefix>/<version>/sso/login-acknowledgement/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => array('service' => '<service slug>','api_sid' => '<api session id>'),
CURLOPT_HTTPHEADER => array(
"apikey: <api key>"
),
));
​
$response = curl_exec($curl);
​
curl_close($curl);
echo $response;

Error Responses

Status Code

Error Type

Field

Description

400

Validation Error

service

This field is required

400

Validation Error

service

This field may not be blank.

400

Validation Error

api_sid

This field is required

400

Validation Error

api_sid

This field may not be blank.

401

Request Failed

​

Invalid service with api_id.

Single Sign-On User Logout

post
​

β€Žβ€Žhttps://<domain>/<api prefix>/<version>/sso/logout/
This API endpoint will destroy all sessions based on the api_sid.
Request
Response
Request
Headers
apikey
required
string
apikey
Body Parameters
api_sid
required
string
api session id
Response
200: OK
HTTP/1.1 200 OK
Content-Type: application/json
​
Body:
{
"status_code": 200,
"errors": {},
"data": {}
}

Sample code

Node

var request = require('request');
var options = {
'method': 'GET',
'url': 'https://<domain>/<api prefix>/<version>/sso/logout/',
'headers': {
'apikey': '<apikey>'
},
formData: {
'api_sid': '<api session id>'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});

PHP

<?php
​
$curl = curl_init();
​
curl_setopt_array($curl, array(
CURLOPT_URL => "https://<domain>/<api prefix>/<version>/sso/logout/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_POSTFIELDS => array('api_sid' => '<api session id>'),
CURLOPT_HTTPHEADER => array(
"apikey: <apikey>"
),
));
​
$response = curl_exec($curl);
​
curl_close($curl);
echo $response;

Error Responses

Status Code

Error Type

Field

Description

400

Validation Error

api_sid

This field is required

400

Validation Error

api_sid

This field may not be blank.

400

Validation Error

api_sid

Invalid api_sid.

​