Skip to content

Login Form Integration

Target Audience: Developers

Warning

Please note: We do not recommend that you implement SSO using this system. This system will be obsolete in the future. Please implement Single Sign-On using Single Sign-On v2 (SSO2), read more here.

Introduction

A third party application can implement its own login form and forward the credentials to Payway (PW) for authentication. Upon successful authentication, PW will return a Login Handle (LH). Using the LH the application can then initialize the authorization process and establish a Session for the user. This way the third party application can brand its own login and serve the login form on its own web pages instead of performing a Payway Login.

Requirements and limitations

  • It is necessary that the web page serving the custom login form is only accessible through the HTTPS protocol.
  • Using a custom Login Form and the Javascript-API combined with the Intelligent Tracking Prevention the fix will not work. This means that "Remember me" functionality will NOT work for users browsing with Safari 11 or later, and above and these users will always have to log in again upon re-opening their browsers if their session cookie has been removed. This is a technical limitation that we can not work around today.
  • This solutions requires that the highest possible trust is established between PW and the implementing application. It is the responsibility of the implementor to make sure that the user credentials, that are exposed to their application, in NO way is displayed, logged or persisted in any way to avoid any breach of security.

Abbreviations

Abbreviation Full name Description
LH Login Handle A token supplied by Payway as a means to start the authorization process

Authentication process

Overview

Authorization Process

Details

Request Login Handle

Having the user credentials at hand, the 3:d party application backend can make a server-to-server call, requesting a LH to use as a means to initialize a Session for the user. The request needs to be completed with an access token that has the /oauth2/login/x scope. For details on how to request an access token for use with our API:s Read More Here.

Environment Endpoint URL
Stage https://payway-api.stage.adeprimo.se/oauth2/login
Production https://backend.worldoftulo.com/oauth2/login
Request parameters

The parameters are sent as x-www-form-urlencoded in the request body.

Parameter Description
username The users username
password The users plain text password
persist "Remember me"-function. Same as if the user clicked the "Remember me" checkbox when logging on using the PW Portal. Valid values are true or false
Example request
POST /oauth2/login
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: OAuth <access_token_here>
username=myusername&password=mypassword&persist=false
Example successful authentication

If the username and password are a set of valid user credentials the response will look like below. The string contained in the result field is the LH to use when proceeding the login process. The response will be using the application/json content type.

{
  status: "ok",
  result: "53f9e2a1-1c1e-425a-bdae-24894c0f6916"
}
Example failed authentication

In case that the submitted user credentials aren't valid the response will look like below. The response will be using the application/json content type.

{
  status: "error",
  code: "invalid_username_or_password",
  field: "unspecified_field",
  message: "Invalid username and/or password",
  error_data: null
}

Respond with 302 Redirect

When the 3:d party application has a LH to work with it will have to construct a URI and redirect the browser to start the authorization process. After this redirect has been performed the process will follow the regular authorization process, but will not require the user to make a regular Payway Login but will rather use the LH as proof that the user has authenticated. At this stage there is already a Session established between the browser and the Payway backend.

Environment Endpoint URL
Stage https://payway-api.stage.adeprimo.se/oauth2/auth
Production https://backend.worldoftulo.com/oauth2/auth
Query string parameters

This request is identical to a request starting the standard authorization process except for the login_handle parameter. See more information about the standard authorization process Here.

Parameter Description
client_id The API Client ID of the calling 3:d party application
redirect_uri The 3:d party application landing page. This must be the same URI as the one that has been registered for the API Client
state The local state variable.
response_type Typically 'code'
oid The id of your Payway instance
scope One or more API scopes you want to have access to, delimited by a space, url-encoded
login_handle The Login Handle that you got from the previous step in the process. This is a token that is consumed as proof that your user has already authenticated and established a Session with Payway
Example redirect return to browser
HTTP 302
https://payway-api.stage.adeprimo.se/oauth2/auth?client_id=6a98217e95ddeee048023001&redirect_uri=http%3A%2F%2Flocalhost%3A9292%2Flanding&state=bG9jYWxfY29udGludWVfdXJsPSUyRiZyYW5kb21fc3RhdGU9VGhpcytpcytteStzdGF0ZS1zdHJpbmc%3D&response_type=code&oid=adeprimo&scope=&login_handle=c2c749dd-c236-45c8-9dd0-25c65621b13b