Single Sign On Integration Guide

User login

Authenticate swiftly and securely with your trusted identity provider. Experience a seamless login process, bypassing the need to remember another set of credentials. Enjoy the enhanced security provided by your identity provider’s robust authentication measures. This is the convenience and security of Single Sign-On.

---

How it works

---

1. Initiate authorization

This step occurs in the user’s browser.

• Initiate Authorization: Your application redirects the user’s browser to the identity provider’s authorization endpoint (/v2/authorize).
• User Login: The user enters their credentials and logs in on the identity provider’s page.
• Return to Application: Post successful login, the user’s browser is redirected back to your application. This redirect URL is predefined during the initial authorization call.

Show request parameters

Parameter	Mandatory	Format	Comment
client_id	Yes	AN	OAuth client ID, an attribute of an OAUTH_APP user on Open Payment Platform.
redirect_uri	Yes	AN	URL to redirect user after successful authorization. Must be URL-encoded.
scope	Yes	AN	Scope for accessing data. Currently, “openid” is mandatory.
response_type	Yes	AN	Type of OAuth2 workflow to execute. Currently, “code” is mandatory.
state	No	AN	Optional parameter to prevent CSRF. Same value sent by the redirect will be returned back to the client application.

Sample request:

2. Acquire access token

This step is handled by your application’s server.

• Acquire Access Token: Your application makes a request to the identity provider’s token endpoint (/v2/token) and receives an access token.

Show request parameters

Header	Mandatory	Format	Comment
Authorization	Yes	AN	Follows HTTP Basic authentication. Formatted as "Basic " + base64.encode(clientId + ‘:’ + clientSecret).
Parameter	Mandatory	Format	Comment
code	Yes	AN	One-time use code passed by authentication.
grant_type	Yes	AN	Grant type for the token request. Currently accepts ‘authorization_code’ only.
redirect_uri	Yes	AN	Redirect URL from the first redirect.
scope	Yes	AN	Token scope. Currently accepts ‘openid’ only.

Show response parameters

Attribute	Format	Comment
access_token	AN256	This is the key that permits an application to make further requests on behalf of a user.
expires_in	N	Specifies the lifespan of the access token in seconds.
token_type	AN	Specifies the OAuth2 token type. Currently, it’s ‘bearer’.
scope	AN	Defines the scope of the access. At present, it’s set to ‘openid’ only.

Sample request:

3. Retrieve user information

This step is also handled by your application’s server.

• Retrieve User Information: Your application uses the access token to query the identity provider’s user information endpoint (/v2/userinfo).
• User Login Confirmation: Based on the received information and your application’s rules, decide whether to grant the user access.

Show request parameters

Header	Mandatory	Format	Comment
Authorization	Yes	AN256	Contains the bearer token for authorization. It’s formatted as "bearer " + access_token.

Show response parameters

Parameter	Format	Comment
sub	AN32	Unique key identifying the subject, same as “id”.
id	AN32	The system’s contact id.
name	AN35	Contact’s name.
preferred_username	AN256	Contact’s username.
email	AN128	Contact’s email.
attached_to	ARRAY	List of user’s attachment levels, represented as paths: Root: "/" Psp: "/pspName" Division: "/pspName/divisionName" Merchant: "/pspName/divisionName/merchantName" Channel: "/pspName/divisionName/merchantName/channelName"
role	AN256	User’s role, which can be one of several predefined roles such as: Account Access Accounting Global Administrator Analysis Callcentre Callcentre Restricted Operator

Sample request:

Session Tracker

Experience the power of real-time session tracking in Single Sign-On (SSO). Our session tracker keeps you informed about the user’s active status in the Authentication Manager and any logout actions from connected applications. Upon logout, your application receives an instant alert, enabling swift response. Post-action, your application is ready to initiate a new Login Workflow, ensuring a smooth transition for potential user re-login. Discover enhanced control and fluid user management with our session tracker in SSO.

Here’s the swift workflow:

• User logs into your application via the Login Workflow.
• User navigates to a different application, like the Open Payment Platform.
• User logs out, activating the Logout workflow on the visited application.
• User accesses an internal page in your application. The Session Tracker JavaScript Snippet promptly alerts your application about the session change.
• Your application swiftly terminates the local user session and readies a new Login Workflow.

---

How it works

---

1. Responding to logout events

Your application can receive notifications about changes in the user’s remote session (on the Authentication Manager) by embedding a JavaScript Snippet on each page of your application. This allows your application to take action, such as terminating the local user session and initiating a new Login Workflow.
Please add the following JavaScript code to each page of your application that needs to respond to remote logout events:

Sample:

<script type="text/javascript">
(function(w, d, o, u, r, a, m)  {
	w[r] = w[r] ||
		function() {
			(w[r].q = w[r].q || []).push(arguments);
	};
	a = d.createElement(o),
	m = d.getElementsByTagName(o)[0];
	a.async = 1;
	a.src = u;
	m.parentNode.insertBefore(a, m);
})(window, document, 'script', 'https://eu-test.oppwa.com/sso/sessionTracker/oasm.js', '_OASM');
 
//put your client id instead of {your_client_id}
_OASM('client_id', '{your_client_id}');
 
//callback for whenever the session status is different than expected
_OASM('on_change', function(){
	//remove user session locally
	//start a new Login Workflow
});
</script>
		

2. Verifying user login status (individual check)

After integrating the above script into your page, your application can perform individual checks to see if the user has remotely logged out. If the remote login status of the user is not as expected (‘logged_in’), your application will be notified via the function defined by _OASM('on_change').

Sample:

_OASM('check', 'logged_in');

3. Verifying User Login Status (polling)

Your application can also set up a polling mechanism that continually verifies at set intervals if the user has logged out.

Sample:

// Set the interval (in milliseconds) at which your application should verify if the user has logged out.
_OASM('poll', {state:'logged_in', interval: 10000});
		

User logout

Authenticate swiftly and securely with your trusted identity provider. Experience a seamless login process, bypassing the need to remember another set of credentials. Enjoy the enhanced security provided by your identity provider’s robust authentication measures. This is the convenience and security of Single Sign-On.

---

How it works

---

1. Terminate session

Redirect the user to the identity provider’s page to initiate the authorization process.

Sample request: