Ticket Authentication

Target Audience: Developers, Stakeholders

Release version: 3.9.2

Introduction

When integrating applications and web sites with Payway (PW) without making use of the Javascript-API and instead solely depend on the Payway API you will not get support for Single Sign-On (SSO) as described in Payway Session

Ticket Authentication provides a way to transfer authorization of a logged in user in one of your applications to another trusted application as long as you have an access token tied to that user's identity. This enables you to give an SSO-like experience and avoid asking your users for their credentials repeatedly when transitioning them between your applications.

Authorization-ticket exchange overview

Term	description
Origin Client	The PW API-Client being used by the Origin Application.
Origin Application	The application where the user is authenticated and authorized. This is the application that will send the user off to another application.
Destination Client	The PW API-Client being used by the Destination Application.
Destination Application	This is the application that should be able to receive an authorization-ticket and exchange it for an access-token for a specific end-user.
Authorization Server	This is the Payway Authorization Service
Resource Server	In this case this is refers to the Payway API

(A) The end-user, being authenticated and authorized in the context of the origin application, follows a hyperlink or performs similar interaction with the intent on transitioning from the origin application to the destination application.

(B) The web browser requests that the origin application forwards the resource owner to the destination application.

(C) The origin application requests an authorization-ticket from the authorization server. The authorization server creates an authorization-ticket for the identity of the requesting resource owner and the intended destination application.

(D) The origin application receives the issued authorization-ticket.

(F) The origin application redirects the web browser to the destination application, supplying the issued authorization- ticket as proof of identity and authorization.

(G) The destination application requests an access token from the authorization server using the ticket grant type.

(H) The authorization server authenticates the user and validates the authorization-ticket, and if valid, returns an access token.

(I) This step is optional. The destination application uses the issued access token to request a resource from the resource server. This could e.g. be a request for more details of the users identity.

(J) This step is optional. If the access token is valid the resource server returns the requested resource.

(K) The destination application now has an access token with authorization on behalf of the end-user and returns a redirect for the web browser to display e.g. the destination application start page.

(L) The web browser presents the destination application to the end-user.

Origin Application

The origin application is the application where your end user is authenticated and authorized. This means that you have an access token tied to a user identity. To be able to forward the user to another application you must request an authorization-ticket from the authorization server. This is done with a HTTP-request to the ticket-endpoint.

Request

• The calling application must supply a bearer token tied to a user identity.
• The token must have the api/authorization/ticket scope.
• The HTTP-request must be using the POST-method.

The following headers must be set:

Authorization: Bearer <insert_access_token_here>
Content-Type: application/x-www-form-urlencoded
Accept: application/json

The parameters must be supplied in the application/x-www-form-urlencoded format in the requests body:

Field name	Example value	description
client_id	50fe72bb400e0351b400000e	The client_id of the PW API-Client being used in the Destination Application

Example curl:

curl --request POST \
  --url https://payway-api.stage.adeprimo.se/api/authorization/ticket \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <insert access_token here>' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data client_id=<insert client_id here>

Endpoints:

Environment	URI
Stage	https://payway-api.stage.adeprimo.se/api/authorization/ticket
Production	https://backend.worldoftulo.com/api/authorization/ticket

Successful Response

Example response from successful request:

{
  "ticket": "0d67c58762cadb9ef5ff10624e6bc05d904c63fe3df01102e8d4442faeece91e",
  "expires_at": 1553699227
}

Error Response

400 no_target

The client_id parameter is missing from the request.

Example response:

{
  "error": "no_target",
  "error_description": "requires valid client_id parameter"
}

400 no_trust

The PW API-Client with the specified client_id is not trusted and can not be the target of this operation. As long as you own the target client_id this should not happen.

Example response:

{
  "error": "no_trust",
  "error_description": "no trust exists between these two clients"
}

400 no_identity

There is no identity tied to the access token being used.

Example response:

{
  "error": "no_identity",
  "error_description": "no identity on access token"
}

401 Unauthorized

You may get an 401 Unauthorized response if the access token being used have expired. In the case of a 401 Unauthorized response you can examine the WWW-Authenticate response header for further details.

Example response header:

WWW-Authenticate: OAuth realm="payway-api.stage.adeprimo.se", error="expired_token", error_description="The access token has expired."

403 Forbidden

You may get an 403 Forbidden response if the access token being used does not have the correct scope. You can examine the WWW-Authenticate response header for further details.

Example response header:

WWW-Authenticate: OAuth realm="payway-api.stage.adeprimo.se", error="insufficient_scope", scope="/api/authorization/ticket"

Destination Application

The destination application is the target application where you wish to authorize the user with the authorization-ticket. This application must supply an endpoint that acts as a starting point for on-boarding the end-user.

The endpoint must:

• accept HTTP GET requests
• get the authorization-ticket from the query parameter "at"
• call the access token endpoint to exchange the authorization-ticket for an access token tied to the user

Access Token Request

• The HTTP-request to the access token endpoint must use the POST-method.

The following headers must be set:

Content-Type: application/x-www-form-urlencoded
Accept: application/json

The parameters must be supplied in the application/x-www-form-urlencoded format in the request body:

Field Name	Example Value	description
grant_type	ticket	This indicates that we're using the ticket grant type
client_id	50fe72bb400e0351b400000b	The client_id of the Destination Client.
client_secret		The Destination Client secret
scope	/external/me/r /external/me/w	Whitespace delimited list of scopes that we wish to use with this access token. Must be scopes that are enabled on the Destination Client.
ticket	...75f5b45dbebb9c52b4d...	The authorization-ticket to authorize with

Example curl:

curl --request POST \
  --url https://payway-api.stage.adeprimo.se/api/authorization/access_token \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id=<insert client_id here>&grant_type=ticket&client_secret=<insert client_secret here>&scope=%2Fapi%2Faccount%2Fr&ticket=9291613e6a5dccaa15f6646914781bf84cb172cfbd222109f56bd0a7b8bb8660'

Endpoints:

Environment	URI
Stage	https://payway-api.stage.adeprimo.se/api/authorization/access_token
Production	https://backend.worldoftulo.com/api/authorization/access_token

Successful Response

Example response from successful request:

{
  "access_token": "b1d7824d868f26b65233a006b337e75f7d50b827cab94978fe7ca14fd0463207",
  "scope": "/api/account/r",
  //refresh_token: Only if refresh-token is enabled for the client
  "refresh_token": "fc035355f6f0ad173e4d33d834e9d5e04dd3778756100465f31edd0d8d1814d3",
  "expires_in": 60,
  "token_type": "Bearer"
}

Error Response

400 invalid_ticket

The authorization-ticket is not valid. Reason described in error_description:

• Ticket not issued by client
• Ticket already consumed
• Ticket expired

Example response:

{
  "error": "invalid_ticket",
  "error_description": "Ticket already consumed"
}

Payway Client Portal Integration

PCP login from website

The Payway Client Portal (PCP) has support for consuming authorization-tickets. This enables you to forward a user from your application to the PCP and have them automatically logged in without having to have an active Payway Session.

PCP client_id

You might have to contact the Payway-team to get information about your Payway Client Portal's client_id to be able to create an authorization-ticket to use.

Landing Page

Once you've requested an authorization-ticket for the PCP you redirect your user to the PCP landing page, supplying the authorization-ticket and a continue-uri in the query-string.

The parameters must be supplied in the application/x-www-form-urlencoded format in the query string:

Field Name	Example Value	description
at	...75f5b45dbebb9c52b4d...	The authorization-ticket
continue	https://adeprimo.portal.worldoftulo.com	The user will be sent to this url when login is completed. If this is omitted the user will be directed to the "My Account"-page in the PCP.

Landing page URI:

Environment	URI
Stage	https://.payway-portal.stage.adeprimo.se/login/ticket
Production	https://.portal.worldoftulo.com/login/ticket

Example redirect location:

https://adeprimo.payway-portal.stage.adeprimo.se/login/ticket?at=a4a391af8acf6e65a237af9ac2bce4613d499e4f72dbc77c53ddee874790c8a4

Website login from PCP

When redirecting an anonymous user, for whom you do not have an access token and cannot not create an authorization ticket for, to a purchase page in the PCP, you can ask the PCP to include an authorization ticket in the link back to the website. This enables you to log the user in, using the authorization ticket, when the purchase is complete and the user has either logged in or created an account in the process.

Requirements

• The destination client must have a redirect uri specified
• The destination application must implement an endpoint for the redirect uri

Overview

(A) The unauthenticated end-user follows a hyperlink to the purchase page. See details about the purchase link.

(B) The user logs in with an existing account or creates a new account and completes the purchase.

(C) PCP renders a confirmation page including a link back to the original website where the purchase was initiated.

(D) User clicks on the link back to the original website.

(E) PCP creates an authorization ticket and redirects the user agent to the redirect uri of the destination client.

(F) The User-Agent follows the redirect to the landing page specified in the redirect uri of the destination client.

(G) The landing page returns a redirect to the desired destination after completed purchase. This is usually the page where step (A) was initiated.

(H) The User-Agent follows the redirect to the destination.

Purchase link

The hyperlink pointing to the purchase page must supply the following querystring parameters. The parameters must be supplied in the application/x-www-form-urlencoded format in the query string:

Field Name	Example Value	description
tcid	...75f5b45dbebb9c52b4d...	The destination client id, in this case the API client id of the website.
ts	Pvet6ezcyhGMcSnlGivspg%3D%3D	The target state value.

Target state parameter

The target state parameter is intended to be used for passing information about the state when the user initiated the purchase on the website. A common use case would be to include the location where the user left the website in order to make a purchase. This information could be used to return the customer to the same location after completing the purchase and being logged in on the website using an authorization ticket.

The format or content of the data in the target state parameter may be freely determined by the website implementation. PCP will not use this parameter, only pass it on when the user is sent to the landing page.

The data structured contained in this parameter should be base64 encoded and urlencoded in that specific order.

Example pseudo-code:

ts = url_encode(base64_encode("returnUrl=http://example.com"))

Landing page

This is the designated landing page for the website. The redirect uri on the API-client must point here. This is where the website exchanges the authorization-ticket for an access-token and logs the user in. This typically requires using the access-token and calling the Me-API to establish the users identity.

This endpoint must

• Accept HTTP GET requests
• Read the parameter "at" (authentication ticket)
• Read the parameter "ts" (target state)
• Call the access token endpoint to exchange the authorization-ticket for an access token tied to the user

Cancel button on purchase page

When a user logs in on the purchase page in this situation, the cancel-button will return the user via the landing page in the same fashion as when a user has completed the purchase.