Authentication flow architecture
Actors
Entry points
The SSO flow starts the same way whatever page the user opens, from a browser or from a WebView embedded in the bank app.- The WebApp home page.
- An internal page of the WebApp, opened from a bookmark, a push notification, a native menu entry or any direct link (see Page URLs).
Flow at a glance
Your Paylead contact provides the Consumer URL for your Program. It differs per environment:https://consumer-<reference_pm>.sandbox.paylead.tech in
sandbox, https://consumer-<reference_pm>.paylead.eu in production. The
examples below use the production host.
1
Open the WebApp
The user opens the WebApp from the partner app.
2
Query the Paylead IdP
The WebApp detects that the user is not authenticated and queries the
Paylead IdP.
3
Delegate to the Partner IdP
The Paylead IdP redirects the browser to the Partner IdP with an OIDC
Authentication Request (including
state and nonce).4
Authenticate the user
The Partner IdP performs all required authentication steps, then redirects
back to the Paylead callback URL with an
authorization_code and the
original state.5
Create the Paylead session
The Paylead IdP exchanges the code for an ID Token, retrieves the
authenticated identifiers (see Claims) and the session state,
then creates a Paylead session.
6
Open the authenticated WebApp
The user is redirected to the page originally requested, with an active
session.
Claims
The Partner IdP identifies each Consumer through two mandatory claims in the ID Token.
The Partner IdP must NOT send any claim belonging to the
profile, email,
address or phone.
Partner IdP requirements
Paylead-initiated authentication
The Partner IdP must accept Authentication Requests sent by the Paylead WebApp. IdP-initiated flows are not supported. The request carries two values Paylead relies on.state. Paylead checks thestatereturned in the Authentication Response against the current user session, then uses it to redirect the user to the page originally requested.nonce. Paylead checks that thenoncein the ID Token matches the value sent in the Authentication Request and bound to the current user session. This protects against CSRF attacks.
Authentication Request
- Paylead authenticates as a confidential client (OAuth 2.0, section 2.1).
- The Partner IdP must support Authentication Requests sent with the
GETmethod, through an HTTP redirect from the Paylead WebApp. - The Partner IdP must support the optional
noncerequest parameter. - The Paylead OIDC client can be configured to send any scope the Partner IdP requires.
Strong authentication
Some sensitive actions, such as changing the bank account used to pay out Cashback, require a stronger authentication level. Two mechanisms are available.Session management
Session types
Recommended durations
- Paylead IdP. Defaults to the durations above, and is configurable.
- Partner IdP. Must be greater than or equal to the Paylead IdP session,
to avoid showing the authentication screen after a redirect to the Partner
IdP
/authorizeendpoint.
Expected behaviour by session state
Access check and re-authentication
Step 1. Pre-check before opening
Before opening the WebApp, perform aGET without automatically following
redirects.
- A 2xx response means the session is valid. Open the WebApp directly.
- A 3xx response whose
Locationheader points to/auth(the Paylead IdP auth route) means the full SSO flow must start (Step 2).
state and nonce values. See
Paylead-initiated authentication.
Step 2. Web authentication
1
Follow every redirect
Follow all redirects present in the
Location header.2
Keep all cookies
Keep all cookies (
Set-Cookie) received at each step.3
Validate the final redirect
Check that it contains
scope, state, nonce, client_id and
redirect_uri. Otherwise, clear the cookies for the Paylead domain and
retry once.4
Generate the authorization code
Generate the authorization code through the custom Paylead IdP plugin.
5
Build the callback URL
Build it as
redirect_uri?code=<authorization_code>&state=<state>.6
Call the callback
Call it with a
GET, following redirects and storing cookies.7
Open the WebApp
Open the WebApp with the updated cookies.
What’s next
WebView configuration
Cookie and WebView setup required for the flow above to work reliably.
Troubleshooting
Diagnose a recurring auth screen, lost cookies, or hard-to-trace behaviour.