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¶
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