Single Sign-On¶

Target Audience: Developers

Introduction¶

The default Single Sign-On (SSO) system that Payway offers is based on a third party cookie and is usually implemented by consuming the Payway JS-API. This solution is now slowly being obsoleted by the works of browser vendors around the world in their fight against tracking cookies and other intrusions into user privacy.

As a way to provide SSO services in the future Payway is offering a new and improved SSO system. This new system does not rely on third-party cookies and does not supply a Javascript library for client-side implementation.

These two systems, Single Sign-On v1 (SSO1) and Single Sign-On v2 (SSO2) are completely different systems and can not operate side by side. SSO1 will be obsoleted and replaced by SSO2 once all active integrations have changed to leverage the new SSO2 system.

Requirements and limitations¶

SSO2 is only avaliable for web clients.
Before switching to SSO2-integration you must contact Adeprimo to have the Payway Client Portal (PCP) and Payway Admin Portal (PAP) switched over to SSO2.
You can not have SSO between SSO1 and SSO2 sessions.
To use a API-client for SSO2 purposes you must set it as a SSO2-client in the PAP.
User must allow cookies in their web browser.

Abbreviations¶

Abbreviation	Full name	Description
SSO1	Single Sign-On v1	Refers to the old legacy Payway JS-API SSO system.
SSO2	Single Sign-On v2	The new SSO system.

Single Sign-On 2 Web Site Integration¶

Integrating your web site to leverage SSO2 requires it to support 4 different operations:

Operation	Description
Identify	Used to identify the current user to see if they are currently known and/or logged into the SSO system. Also used to aquire a new SSO session.
Authenticate	Used to authenticate and sign a user into a SSO session.
Session Status	Check the current status of a known SSO session.
Logout	Terminate a known SSO session and logout the user.

All information exchanged between the SSO2 system and your web site is transmitted in JSON Web Tokens (JWT) that are signed and encoded. The JWT is signed using your API Clients secret, both ways, which enables both your web site and Payway to verify that the token has not been tampered with and that it originates from the correct sender, in possession of the shared secret. For details about creating, signing, verifying, encoding and decoding JWT please read more on JWT.io.

The web site must also implement a landing page for the Identify-operation.

Session¶

The Payway SSO2 system keeps track of a users' session between the users' User-Agent (UA) and the SSO2 system. This means that a user can have more than one session active at the same time by using multiple UA:s and multiple devices.

The session have 3 possible states:

Anon - A session is established between the SSO2 system and the users' UA, but there is no known user logged into the session.
LoggedIn - A session is established between the SSO2 system the users' UA and there is an authenticated and known user logged into the session.
Terminated - A session that is no longer valid, the user has terminated it by logging out of the SSO2 system.

Session Token¶

All operations that are part of the SSO2 system will respond with a JWT-token describing the current session status: The Session Token (ST). You should store the relevant information about the session state in your web sites local session, but never in a way that exposes it to the browser, like in a cookie.

Example Session Token¶

{
  "alg": "HS256",
  "typ": "JWT
}
{
    "nbf": 1605097320,
    "exp": 1605183720,
    "iat": 1605097320,
    "iss": "pw-sso",
    "aud": "<Your client ID>",
    "sid": "<Session ID>",
    "sts": "<Session Status>",
    "at": "<Authorization Ticket>",
    "err": "<Error Code>",
    "ems": "<Error Message>"
}

Claim	Description
iss	Will always be issued by "pw-sso".
aud	The client_id of the API-client the token was issued for.
sid	The session ID, a unique identifier for the SSO2 session.
sts	Session state, can be "anon", "loggedin" or "terminated"
at	Authorization Ticket. If this token is a response to either the Identify-operation or the Authenticate-operation this field can contain a token that you can exchange for a access token by calling the access token endpoint on the authorization server.
err	If something went wrong this field will hold an error code to help figure out the problem.
ems	If something went wrong this field can hold an error message to help figure out the problem.

General error codes¶

If errors are occurring the claim err will contain error codes that can help you identify what is wrong. The general error codes are:

Error code	Description
invalid_token	Validation of the JWT token, supplied in your call, failed.
session_not_found	The session could not be found. Either the session_id is not correct or the session has been pruned due to inactivity.

Operations¶

Identify¶

Description¶

The Identify-operation is used when you have no Session Token in your current local session, or when the Session Token that you do have is in the state terminated. The purpose of the operation is to give you a Session Token representing the current session status between the users UA and the SSO2 system. This is a redirect operation, meaning that you will redirect the users' UA to the SSO2 system for identification and then they will arrive back at your web sites landing page, as configured on the API-user in the PAP.

When the users' UA is redirected to your landing page it will carry along a Session Token and a return URI in the query string, enabling you to capture the Session Token, log the user into your local session and then redirect them to their final destination.

You must identify the user when:

You have no Session Token
The current Session has been terminated. In this case the identification process will create a new anon Session for the user.

Overview - No SSO session¶

Identify

(A) The user browses to the web site. The web site has no knowledge about the user in its local session and determines that it has to identify the user to see if it is already logged into the SSO2 system. This is done by redirecting the user to the SSO2 systems identify-endpoint.
(B) The users' UA is redirected to the SSO2 systems identify-endpoint which can not find a SSO session for the current user. The SSO2 system creates a new anonymous SSO session and redirects the users' UA to the web sites landing page.
(C) The users' UA arrive at the web sites landing page with details about the new SSO session and which URI to forward the user to. The web site persists the SSO session details in its local session but the user is not logged in. The landing page redirects the users' UA to the supplied return URI.
(D) The users' UA arrives back on the page where the identify-operation started.

Overview - Existing SSO session¶

Identify

(A) The user browses to the web site. The web site has no knowledge about the user in its local session and determines that it has to identify the user to see if it is already logged into the SSO2 system. This is done by redirecting the user to the SSO2 systems identify-endpoint.
(B) The users UA is redirected to the SSO2 systems identify-endpoint which identifies the user as having a SSO session and being logged in already. The SSO2 system redirects the users' UA to the web sites landing page.
(C) The users' UA arrive at the web sites landing page with details about the SSO session being logged in already. The landing page exchanges the supplied Authentication Ticket for an access token, calls the Payway API to figure out what user this is and logs it into the local session. The landing page redirects the users' UA to the supplied return URI.
(D) The users' UA arrives back on the page where the identify-operation started, now being logged in and able to access locked content.

Redirect to Identify¶

When redirecting to the Identify endpoint the web site should supply two query string parameters:

Param	Description
t	Encoded JWT-token.
r	The return URI where the user should end up at the end of the Identify-operation, often the current URI.

Optional parameters:

Param	Description
debug_url	Optional override of redirect uri, not available in production environment.

Example redirect URI:

https://payway-sso-stage.azurewebsites.net/identify
?t=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJjaWQiOiI8WW91ciBBUEktY2xp
ZW50IElEPiIsIm5iZiI6MTYwNTA5NzMyMCwiZXhwIjoxNjA1MTgzNzIwLCJpYXQiO
jE2MDUwOTczMjAsImlzcyI6IjxZb3VyIG9yZ2FuaXNhdGlvbiBJRD4iLCJhdWQiOi
Jwdy1zc28ifQ.FTo5eUlacFWpFri6sDNJ4NGMSSAUUpFicy-yjyp5fW0
&r=https%3A%2F%2Fmy-website.com

The decoded JWT-token looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
{
    "cid": "<Your API-client ID>",
    "nbf": 1605097320,
    "exp": 1605183720,
    "iat": 1605097320,
    "iss": "<Your organisation ID>",
    "aud": "pw-sso"
}

The Claims in the JWT-token:

Claim	Type	Description
cid	string	"Client ID", Your API-client ID
nbf	int(epoch)	"Not before", this should be the epoch timestamp of when this token is created.
exp	int(epoch)	"Expires", this should be the epoch timestamp for 10 seconds after token was created.
iat	int(epoch)	"Issued At", this should be the epoch timestamp of when this token is created.
iss	string	"Issuer", this should be your Payway Organisation ID.
aud	string	"Audience", this should always be "pw-sso".

You sign the token with the secret related to the API-client that you use.

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/identify
Production	https://sso.worldoftulo.com/identify

Authenticate¶

Description¶

The Authenticate-operation is used when authenticating and signing a user into a SSO session. When you have a SSO session that is in state "anon" you can authenticate the user and have them signed into that specific session.

This is a server-to-server operation and you supply the user with the login form on your own web site. When the user submits his/her credentials to your server through your login form you create an authentication JWT and submit it to the SSO2-systems authenticate endpoint.

Do not persist or log the users' credentials on your web site server! Make sure to obfuscate these credentials in any logs you might have and double check to make sure that the authenticate JWT is not logged in any web server logs as well!

You call the authenticate endpoint when:

You have a SSO session with state "anon"
You want to login the user into the SSO session

Overview¶

Authenticate

(A) The user is not logged in and has gone through the Identify-operation so there is an "anon" SSO session. The user clicks the login-button and gets the login form.
(B) The user submits his credentials from the login form to the web site backend. An authenticate JWT is created and posted to the SSO2-systems authenticate-endpoint. A Session token is returned describing the result of the authenticate operation.
(C) The Authentication ticket from the newly returned Session token is traded for an access token. The access token is used to call the Payway API to figure out what user this is. The user is then logged into the local session and the new Session Token is persisted in the local session.

Request¶

The request to the authenticate-endpoint is a server-to-server operation. You create a HTTP POST-request with a JSON payload containing the encoded JWT. You sign the token with the secret related to the API-client that you use.

Param	Description
t	Encoded JWT-token.

Example authenticate request:

curl --request POST \
  --url https://payway-sso-stage.azurewebsites.net/authenticate \
  --header 'content-type: application/json' \
  --data '{
    "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiI1ZjhkNDM5MWJkZjkyODExYTE3ZTc3ZTIiLCJzaWQiOiIzNjEzMGMzNy0yYTE1LWViMTEtOWZiNC0yODE4Nzg3MmRmYTciLCJ1c3IiOiJleGFtcGxlQHVzZXIuY29tIiwicHdkIjoic2VjcmV0X3Bhc3N3b3JkIiwiaXBhIjoiMTI3LjAuMC4xIiwidWFzIjoiTW96aWxsYS81LjAgKFdpbmRvd3MgTlQgMTAuMDsgV2luNjQ7IHg2NCkgQXBwbGVXZWJLaXQvNTM3LjM2IChLSFRNTCwgbGlrZSBHZWNrbykgQ2hyb21lLzg2LjAuNDI0MC4xMTEgU2FmYXJpLzUzNy4zNiIsIm5iZiI6MTYwMzQ1NTc5MywiZXhwIjoxNjAzNTQyMTkzLCJpYXQiOjE2MDM0NTU3OTMsImlzcyI6Im15X29yZ2FuaXNhdGlvbiIsImF1ZCI6InB3LXNzbyJ9.YiK7rfwhzJjF_Ddcjv1hs0AnCy2fCN_GcTmAr7Kvoco"
}'

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "cid": "5f8d4391bdf92811a17e77e2",
  "sid": "36130c37-2a15-eb11-9fb4-28187872dfa7",
  "usr": "example@user.com",
  "pwd": "secret_password",
  "ipa": "127.0.0.1",
  "uas": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36",
  "nbf": 1603455793,
  "exp": 1603542193,
  "iat": 1603455793,
  "iss": "my_organisation",
  "aud": "pw-sso"
}

Claim	Type	Description
cid	string	"Client ID", Your API-client ID
sid	string	"Session ID", the SSO session unique identifier.
usr	string	"Username", the username that the user submitted.
pwd	string	"Password", the password that the user submitted. This can be the users password or a OTP.
ipa	string	"IP Adress", the users' IP adress.
uas	string	"User-Agent string", The users' User-Agent String.
nbf	int(epoch)	"Not before", this should be the epoch timestamp of when this token is created.
exp	int(epoch)	"Expires", this should be the epoch timestamp for 10 seconds after token was created.
iat	int(epoch)	"Issued At", this should be the epoch timestamp of when this token is created.
iss	string	"Issuer", this should be your Payway Organisation ID.
aud	string	"Audience", this should always be "pw-sso".

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/authenticate
Production	https://sso.worldoftulo.com/authenticate

Response¶

The response from the authenticate request is a JSON payload containing an encoded JWT Session Token.

Example authenticate response:

{
  "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHMiOiJsb2dnZWRpbiIsInNpZCI6IjM2MTMwYzM3LTJhMTUtZWIxMS05ZmI0LTI4MTg3ODcyZGZhNyIsImF0IjoiNzQxYjljMjA5ZmFjYWUzZDZlOWZmMzQzM2RlOGRjMWNhMjUxMjQwMmI3OTFlODkxNTQxMTU0YWZkNTQzOGMwMiIsImVyciI6bnVsbCwiZnJmIjotMSwicmFhIjotMSwibmJmIjoxNjAzNDU4ODU3LCJleHAiOjE2MDM0NTg4NjcsImlhdCI6MTYwMzQ1ODg1NywiaXNzIjoicHctc3NvIiwiYXVkIjoiNWY4ZDQzOTFiZGY5MjgxMWExN2U3N2UyIn0.bw6NmvfYcuXIessiYDPs-lTEW7XTJiisxW05LyA3vTE"
}

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "sts": "loggedin",
  "sid": "36130c37-2a15-eb11-9fb4-28187872dfa7",
  "at": "741b9c209facae3d6e9ff3433de8dc1ca2512402b791e891541154afd5438c02",
  "err": null,
  "frf": -1,
  "raa": -1,
  "nbf": 1603458857,
  "exp": 1603458867,
  "iat": 1603458857,
  "iss": "pw-sso",
  "aud": "5f8d4391bdf92811a17e77e2"
}

Claim	Description
sts	Session state, can be "anon", "loggedin" or "terminated"
sid	The session ID, a unique identifier for the SSO2 session.
at	Authorization Ticket.
err	If something went wrong this field will hold an error code to help figure out the problem.
ems	If something went wrong this field can hold an error message to help figure out the problem.
frf	"Frozen For", the number of seconds that the account is frozen for. Defaults to -1 and is only set if err = "account_frozen".
raa	"Remaining Authentication Attempts", defaults to -1 and is only set if err="invalid_credentials".
nbf	This is the epoch timestamp of when this token is created.
exp	This is the epoch timestamp for 10 seconds after token was created.
iat	This is the epoch timestamp of when this token is created.
iss	Will always be issued by "pw-sso".
aud	The client_id of the API-client the token was issued for.

Error codes¶

The error code can be found in the claim err. See general error codes for error codes not specific to a certain operation.

Error codes specific to the authenticate operation:

Error code	Description
invalid_credentials	Means wrong username/password. When this error occours the "raa" claim will contain the number of remaining authentication attempts before the account is frozen for 12 hours.
account_frozen	The account is currently frozen due to too many failed authentication attempts. When this error occurs the "frf" claim will contain the number of seconds until the account is unlocked.
account_not_active	The account is not in an active state and can not log in.
session_terminated	The session is in state terminated and can not be used when authenticating.
session_limit_reached	The user has reached the max number of allowed active sessions.
session_already_logged_in_on_another_account	The session is already logged in on another Payway account.
invalid_otp	See session limitations
otp_consumed_or_expired	See session limitations

Session Status¶

Description¶

The Session Status-operation is used to get updated status about a SSO session. At what interval this happens is not set in stone, but it is recommend that you get updated session status information at most every 6:th minute to not incur too much overhead on the web site users.

This is a server-to-server operation in which you create a Session Status JWT and post to the SSO2-system.

You should perform the Session Status-operation:

Whenever a user arrives to the web site after a time of inactivity.
Before using the Authenticate-operation if your session information is stale.
Before using the Logout-operation if your session information is stale.
When your session information is considered stale. We recommend that this is no more often than every 6 minutes.

What action to take after getting updated status information is depending on your implementation and what state change has occured:

Status changed from "anon" to "logged in"¶

There are two different ways to handle when the session status changes from "anon" to "loggedin".

The "last_know_status"-method¶

If you use the "lks" claim in the JWT when performing your request to the Session Status-operation the SSO system will generate an Authentication-Ticket and include it in the response JWT. The Authentication ticket is traded for an access token. The access token is used to call the Payway API to figure out what user this is. The user is then logged into the local session and the new Session Token is persisted in the local session.

The Identify-method¶

The second way to deal with a detected status change from "anon" to "loggedin" when calling Session Status is to redirect the users using the Identify-operation. This will result in the users UA coming back to your landing page, getting logged in, and then forwarded to their intended destination.

Status changed from "anon" to "terminated"¶

When this happen it means that the current SSO session that you are keeping track of have been logged in and later logged out again from another web site in your network. When this has happened you must redirect the users' UA using the Identify-operation to get hold of a new SSO session to use.

Status changed from "loggedin" to "terminated"¶

When this happens it means that the current SSO session that you are keeping track of have been logged out from another web site in your network. When this has happened you must redirect the users' UA using the Identify-operation to get hold of a new SSO session to use.

Overview¶

SessionStatus

Request¶

The request to the session status-endpoint is a server-to-server operation. You create a HTTP POST-request with a JSON payload containing the encoded JWT. You sign the token with the secret related to the API-client that you use.

Param	Description
t	Encoded JWT-token.

Example session status request:

curl --request POST \
  --url https://payway-sso-stage.azurewebsites.net/sessionstatus \
  --header 'Content-Type: application/json' \
  --data '{
    "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiI1ZjhkNDM5MWJkZjkyODExYTE3ZTc3ZTIiLCJzaWQiOiIzNjVlYTIxZS0yNTE5LWViMTEtOWZiNC0yODE4Nzg3MmRmYTciLCJpcGEiOiIxMjcuMC4wLjEiLCJ1YXMiOiJNb3ppbGxhLzUuMCAoV2luZG93cyBOVCAxMC4wOyBXaW42NDsgeDY0KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvODYuMC40MjQwLjExMSBTYWZhcmkvNTM3LjM2IiwibmJmIjoxNjAzODkzNDI5LCJleHAiOjE2MDM5Nzk4MjksImlhdCI6MTYwMzg5MzQyOSwiaXNzIjoieW91cl9vcmdhbmlzYXRpb25faWQiLCJhdWQiOiJwdy1zc28iLCJsa3MiOiJhbm9uIn0.9faIJbS04S2F4-KdB5b0gLkcPyL8SLscTSdpzkf7g8A"
}'

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "cid": "5f8d4391bdf92811a17e77e2",
  "sid": "365ea21e-2519-eb11-9fb4-28187872dfa7",
  "ipa": "127.0.0.1",
  "uas": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36",
  "nbf": 1603893429,
  "exp": 1603979829,
  "iat": 1603893429,
  "iss": "your_organisation_id",
  "aud": "pw-sso",
  "lks": "anon"
}

Claim	Type	Description
cid	string	"Client ID", Your API-client ID
sid	string	"Session ID", the SSO session unique identifier.
ipa	string	"IP Adress", the users' IP adress.
uas	string	"User-Agent string", The users' User-Agent String.
nbf	int(epoch)	"Not before", this should be the epoch timestamp of when this token is created.
exp	int(epoch)	"Expires", this should be the epoch timestamp for 10 seconds after token was created.
iat	int(epoch)	"Issued At", this should be the epoch timestamp of when this token is created.
iss	string	"Issuer", this should be your Payway Organisation ID.
aud	string	"Audience", this should always be "pw-sso".
lks	string	"Last Known Status", this should be the last known status you had on the session locally. Can be "anon", "loggedid" or "terminated". If you submit "lks": "anon" and the state has changed to "loggedin" you will be issued an Authentication Ticket in the response JWT.

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/sessionstatus
Production	https://sso.worldoftulo.com/sessionstatus

Response¶

The response from the session status request is a JSON payload containing an encoded JWT Session Token.

Example authenticate response:

{
  "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHMiOiJsb2dnZWRpbiIsInNpZCI6IjM2MTMwYzM3LTJhMTUtZWIxMS05ZmI0LTI4MTg3ODcyZGZhNyIsImF0IjoiNzQxYjljMjA5ZmFjYWUzZDZlOWZmMzQzM2RlOGRjMWNhMjUxMjQwMmI3OTFlODkxNTQxMTU0YWZkNTQzOGMwMiIsImVyciI6bnVsbCwibmJmIjoxNjAzNDU4ODU3LCJleHAiOjE2MDM0NTg4NjcsImlhdCI6MTYwMzQ1ODg1NywiaXNzIjoicHctc3NvIiwiYXVkIjoiNWY4ZDQzOTFiZGY5MjgxMWExN2U3N2UyIn0.Aca341yAPrfEjnRwZy0ht6jWzngtW7koFMgCQ5WDSHI"
}

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "sts": "anon",
  "sid": "365ea21e-2519-eb11-9fb4-28187872dfa7",
  "at": null,
  "err": null,
  "nbf": 1603893616,
  "exp": 1603893626,
  "iat": 1603893616,
  "iss": "pw-sso",
  "aud": "5f8d4391bdf92811a17e77e2"
}

Claim	Description
sts	Session state, can be "anon", "loggedin" or "terminated"
sid	The session ID, a unique identifier for the SSO2 session.
at	Authorization Ticket. Only here if the "lks" claim was used in the request and the session status has changed from "anon" to "loggedin".
err	If something went wrong this field will hold an error code to help figure out the problem.
ems	If something went wrong this field can hold an error message to help figure out the problem.
nbf	This is the epoch timestamp of when this token is created.
exp	This is the epoch timestamp for 10 seconds after token was created.
iat	This is the epoch timestamp of when this token is created.
iss	Will always be issued by "pw-sso".
aud	The client_id of the API-client the token was issued for.

Error codes¶

The error code can be found in the claim err. See general error codes for error codes not specific to a certain operation.

Logout¶

Description¶

The Logout-operation is used to terminate a SSO session, transitioning it to the "terminated" status. A session in the terminated status can no longer be used. After calling this operation you must redirect the users' UA using the Identify-operation to make sure that they get a new SSO session with the "anon" status.

Overview¶

Logout

Request¶

The request to the logout-endpoint is a server-to-server operation. You create a HTTP POST-request with a JSON payload containing the encoded JWT. You sign the token with the secret related to the API-client that you use.

Param	Description
t	Encoded JWT-token.

Example logout request:

curl --request POST \
  --url https://payway-sso-stage.azurewebsites.net/logout \
  --header 'Content-Type: application/json' \
  --data '{
    "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiI1ZjhkNDM5MWJkZjkyODExYTE3ZTc3ZTIiLCJzaWQiOiIzNjVlYTIxZS0yNTE5LWViMTEtOWZiNC0yODE4Nzg3MmRmYTciLCJpcGEiOiIxMjcuMC4wLjEiLCJ1YXMiOiJNb3ppbGxhLzUuMCAoV2luZG93cyBOVCAxMC4wOyBXaW42NDsgeDY0KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvODYuMC40MjQwLjExMSBTYWZhcmkvNTM3LjM2IiwibmJmIjoxNjAzODkzNDI5LCJleHAiOjE2MDM5Nzk4MjksImlhdCI6MTYwMzg5MzQyOSwiaXNzIjoieW91cl9vcmdhbmlzYXRpb25faWQiLCJhdWQiOiJwdy1zc28ifQ.dqCNcPdZSoXkKUaZ-H3QwSSDok_hbMfv4IK_sh4l0is"
}'

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "cid": "5f8d4391bdf92811a17e77e2",
  "sid": "365ea21e-2519-eb11-9fb4-28187872dfa7",
  "ipa": "127.0.0.1",
  "uas": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36",
  "nbf": 1603893429,
  "exp": 1603979829,
  "iat": 1603893429,
  "iss": "your_organisation_id",
  "aud": "pw-sso"
}

Claim	Type	Description
cid	string	"Client ID", Your API-client ID
sid	string	"Session ID", the SSO session unique identifier.
ipa	string	"IP Adress", the users' IP adress.
uas	string	"User-Agent string", The users' User-Agent String.
nbf	int(epoch)	"Not before", this should be the epoch timestamp of when this token is created.
exp	int(epoch)	"Expires", this should be the epoch timestamp for 10 seconds after token was created.
iat	int(epoch)	"Issued At", this should be the epoch timestamp of when this token is created.
iss	string	"Issuer", this should be your Payway Organisation ID.
aud	string	"Audience", this should always be "pw-sso".

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/logout
Production	https://sso.worldoftulo.com/logout

Response¶

The response from the session status request is a JSON payload containing an encoded JWT Session Token.

Example authenticate response:

{
  "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHMiOiJ0ZXJtaW5hdGVkIiwic2lkIjoiMzY1ZWEyMWUtMjUxOS1lYjExLTlmYjQtMjgxODc4NzJkZmE3IiwiYXQiOm51bGwsImVyciI6bnVsbCwibmJmIjoxNjAzODk1MDMzLCJleHAiOjE2MDM4OTUwNDMsImlhdCI6MTYwMzg5NTAzMywiaXNzIjoicHctc3NvIiwiYXVkIjoiNWY4ZDQzOTFiZGY5MjgxMWExN2U3N2UyIn0.5OoKe3IoWx-yDORj5B7oyMINEnfFvUXV3PyNJc639Ak"
}

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "sts": "terminated",
  "sid": "365ea21e-2519-eb11-9fb4-28187872dfa7",
  "at": null,
  "err": null,
  "nbf": 1603895033,
  "exp": 1603895043,
  "iat": 1603895033,
  "iss": "pw-sso",
  "aud": "5f8d4391bdf92811a17e77e2"
}

Claim	Description
sts	Session state, can be "anon", "loggedin" or "terminated"
sid	The session ID, a unique identifier for the SSO2 session.
at	Authorization Ticket. Only here if the "lks" claim was used in the request and the session status has changed from "anon" to "loggedin".
err	If something went wrong this field will hold an error code to help figure out the problem.
ems	If something went wrong this field can hold an error message to help figure out the problem.
nbf	This is the epoch timestamp of when this token is created.
exp	This is the epoch timestamp for 10 seconds after token was created.
iat	This is the epoch timestamp of when this token is created.
iss	Will always be issued by "pw-sso".
aud	The client_id of the API-client the token was issued for.

Error codes¶

The error code can be found in the claim err. See general error codes for error codes not specific to a certain operation.

Logout all¶

Description¶

The Logout all-operation is used to terminate all active SSO sessions, transitioning them to the "terminated" status. A session in the terminated status can no longer be used. After calling this operation you must redirect the users' UA using the Identify-operation to make sure that they get a new SSO session with the "anon" status.

This operation is strongly recommended to use after the user has performed a password change, to force any logged in sessions to use the new password.

Overview¶

Logout

Request¶

The request to the logout all-endpoint is a server-to-server operation. You create a HTTP POST-request with a JSON payload containing the encoded JWT. You sign the token with the secret related to the API-client that you use.

Param	Description
t	Encoded JWT-token.

Example logout request:

curl --request POST \
  --url https://payway-sso-stage.azurewebsites.net/logoutall \
  --header 'Content-Type: application/json' \
  --data '{
    "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiI1ZjhkNDM5MWJkZjkyODExYTE3ZTc3ZTIiLCJzaWQiOiIzNjVlYTIxZS0yNTE5LWViMTEtOWZiNC0yODE4Nzg3MmRmYTciLCJpcGEiOiIxMjcuMC4wLjEiLCJ1YXMiOiJNb3ppbGxhLzUuMCAoV2luZG93cyBOVCAxMC4wOyBXaW42NDsgeDY0KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvODYuMC40MjQwLjExMSBTYWZhcmkvNTM3LjM2IiwibmJmIjoxNjAzODkzNDI5LCJleHAiOjE2MDM5Nzk4MjksImlhdCI6MTYwMzg5MzQyOSwiaXNzIjoieW91cl9vcmdhbmlzYXRpb25faWQiLCJhdWQiOiJwdy1zc28ifQ.dqCNcPdZSoXkKUaZ-H3QwSSDok_hbMfv4IK_sh4l0is"
}'

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "cid": "5f8d4391bdf92811a17e77e2",
  "aid": "365ea21e-2519-eb11-9fb4-28187872dfa7",
  "ipa": "127.0.0.1",
  "uas": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36",
  "nbf": 1603893429,
  "exp": 1603979829,
  "iat": 1603893429,
  "iss": "your_organisation_id",
  "aud": "pw-sso"
}

Claim	Type	Description
cid	string	"Client ID", Your API-client ID
aid	string	"Account ID", the Payway Account ID.
ipa	string	"IP Adress", the users' IP adress.
uas	string	"User-Agent string", The users' User-Agent String.
nbf	int(epoch)	"Not before", this should be the epoch timestamp of when this token is created.
exp	int(epoch)	"Expires", this should be the epoch timestamp for 10 seconds after token was created.
iat	int(epoch)	"Issued At", this should be the epoch timestamp of when this token is created.
iss	string	"Issuer", this should be your Payway Organisation ID.
aud	string	"Audience", this should always be "pw-sso".

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/logoutall
Production	https://sso.worldoftulo.com/logoutall

Response¶

The response from the session status request is a JSON payload containing an encoded JWT Session Token.

Example authenticate response:

{
  "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHMiOiJ0ZXJtaW5hdGVkIiwic2lkIjoiMzY1ZWEyMWUtMjUxOS1lYjExLTlmYjQtMjgxODc4NzJkZmE3IiwiYXQiOm51bGwsImVyciI6bnVsbCwibmJmIjoxNjAzODk1MDMzLCJleHAiOjE2MDM4OTUwNDMsImlhdCI6MTYwMzg5NTAzMywiaXNzIjoicHctc3NvIiwiYXVkIjoiNWY4ZDQzOTFiZGY5MjgxMWExN2U3N2UyIn0.5OoKe3IoWx-yDORj5B7oyMINEnfFvUXV3PyNJc639Ak"
}

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "sts": "terminated",
  "aid": "365ea21e-2519-eb11-9fb4-28187872dfa7",
  "at": null,
  "err": null,
  "nbf": 1603895033,
  "exp": 1603895043,
  "iat": 1603895033,
  "iss": "pw-sso",
  "aud": "5f8d4391bdf92811a17e77e2"
}

Claim	Description
sts	Session state, can be "anon", "loggedin" or "terminated"
aid	The account ID, the Payway Account ID.
at	Authorization Ticket. Only here if the "lks" claim was used in the request and the session status has changed from "anon" to "loggedin".
err	If something went wrong this field will hold an error code to help figure out the problem.
ems	If something went wrong this field can hold an error message to help figure out the problem.
nbf	This is the epoch timestamp of when this token is created.
exp	This is the epoch timestamp for 10 seconds after token was created.
iat	This is the epoch timestamp of when this token is created.
iss	Will always be issued by "pw-sso".
aud	The client_id of the API-client the token was issued for.

Error codes¶

The error code can be found in the claim err. See general error codes for error codes not specific to a certain operation.

Landing Page¶

Description¶

Your web site application must supply a landing page that can complete the Identify-operation and redirect the users' UA to its final destination after being identified. This landing pages' URI must be configured on your API-client in the PAP.

The purpose of the landing page is to read the state of the current SSO2 session (from the JWT-token in the t parameter) and depending on the state either log the user into your web site or not.

Overview¶

Identify

Details¶

When the users' UA arrives from the Identify-operation to your web sites landing page it will carry two query string parameters:

Param	Description
t	Encoded JWT-token.
r	The return URI where the users' UA should be redirected.

Example of the request URI to the web sites landing page:

https://your-website.com/landing_page
?t=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJjaWQiOiI8WW91ciBBUEktY2xp
ZW50IElEPiIsIm5iZiI6MTYwNTA5NzMyMCwiZXhwIjoxNjA1MTgzNzIwLCJpYXQiO
jE2MDUwOTczMjAsImlzcyI6IjxZb3VyIG9yZ2FuaXNhdGlvbiBJRD4iLCJhdWQiOi
Jwdy1zc28ifQ.FTo5eUlacFWpFri6sDNJ4NGMSSAUUpFicy-yjyp5fW0
&r=https%3A%2F%2Fyour-website.com%2Fsome_page.php

The decoded JWT is a session token and looks like this:

{
  "alg": "HS256",
  "typ": "JWT
}
{
    "nbf": 1605097320,
    "exp": 1605183720,
    "iat": 1605097320,
    "iss": "pw-sso",
    "aud": "<Your client ID>",
    "sid": "<Session ID>",
    "sts": "<Session Status>",
    "at": "<Authorization Ticket>",
    "err": "<Error Message>"
}

Claim	Description
nbf	Token can not be used (verified) before this Epoch timestamp.
exp	Epoch timestamp for when the token expires.
iat	Epoch timestamp of when this token is created.
iss	Will always be issued by "pw-sso".
aud	The client_id of your web sites API-client.
sid	Session ID, a unique identifier for the SSO2 session.
sts	Session state, can be "anon", "loggedin" or "terminated". Will never be "terminated" when coming from the Identify-operation.
at	Authorization Ticket. Will be null unless sts is "loggedin".
err	If something went wrong this field will hold an error code to help figure out the problem.
ems	If something went wrong this field can hold an error message to help figure out the problem.