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¶
{
"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. |
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¶
- (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¶
- (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¶
- (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 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¶
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¶
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 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. |
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¶
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 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. |
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¶
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 be hold an error code to help figure out the problem. |