Skip to content

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.

Overview

Flowchart

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "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
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 be hold an error code to help figure out the problem.

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.

Example redirect URI:

1
2
3
4
5
6
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "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:

1
2
3
4
5
6
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "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.
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:

1
2
3
{
  "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHMiOiJsb2dnZWRpbiIsInNpZCI6IjM2MTMwYzM3LTJhMTUtZWIxMS05ZmI0LTI4MTg3ODcyZGZhNyIsImF0IjoiNzQxYjljMjA5ZmFjYWUzZDZlOWZmMzQzM2RlOGRjMWNhMjUxMjQwMmI3OTFlODkxNTQxMTU0YWZkNTQzOGMwMiIsImVyciI6bnVsbCwiZnJmIjotMSwicmFhIjotMSwibmJmIjoxNjAzNDU4ODU3LCJleHAiOjE2MDM0NTg4NjcsImlhdCI6MTYwMzQ1ODg1NywiaXNzIjoicHctc3NvIiwiYXVkIjoiNWY4ZDQzOTFiZGY5MjgxMWExN2U3N2UyIn0.bw6NmvfYcuXIessiYDPs-lTEW7XTJiisxW05LyA3vTE"
}

The decoded JWT in the above example looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "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 be hold an error code 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
Claim 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 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:

1
2
3
4
5
6
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "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:

1
2
3
{
  "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHMiOiJsb2dnZWRpbiIsInNpZCI6IjM2MTMwYzM3LTJhMTUtZWIxMS05ZmI0LTI4MTg3ODcyZGZhNyIsImF0IjoiNzQxYjljMjA5ZmFjYWUzZDZlOWZmMzQzM2RlOGRjMWNhMjUxMjQwMmI3OTFlODkxNTQxMTU0YWZkNTQzOGMwMiIsImVyciI6bnVsbCwibmJmIjoxNjAzNDU4ODU3LCJleHAiOjE2MDM0NTg4NjcsImlhdCI6MTYwMzQ1ODg1NywiaXNzIjoicHctc3NvIiwiYXVkIjoiNWY4ZDQzOTFiZGY5MjgxMWExN2U3N2UyIn0.Aca341yAPrfEjnRwZy0ht6jWzngtW7koFMgCQ5WDSHI"
}

The decoded JWT in the above example looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "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 be hold an error code 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.

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:

1
2
3
4
5
6
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "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:

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

The decoded JWT in the above example looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "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 be hold an error code 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.

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:

1
2
3
4
5
6
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "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 be hold an error code to help figure out the problem.