Skip to content

Ticket Authentication

Target Audience: Developers, Stakeholders

1
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

Ticket Exchange Protocol

(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.

Ticket Exchange Protocol

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:

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

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

1
2
3
4
{
  "ticket": "0d67c58762cadb9ef5ff10624e6bc05d904c63fe3df01102e8d4442faeece91e",
  "expires_at": 1553699227
}

Error Response

400 no_target

The client_id parameter is missing from the request.

Example response:

1
2
3
4
{
  "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:

1
2
3
4
{
  "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:

1
2
3
4
{
  "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:

1
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:

1
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.

Ticket Exchange Protocol

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:

1
2
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:

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

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

1
2
3
4
{
  "error": "invalid_ticket",
  "error_description": "Ticket already consumed"
}

Payway Client Portal Integration

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:

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