Skip to main content
The Paylead WebApp (MFP) authenticates bank users through OpenID Connect, using the Authorization Code Flow (OpenID Connect Core 1.0).

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).
Once authenticated, the user always lands on the page originally requested.

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 the state returned 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 the nonce in 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 GET method, through an HTTP redirect from the Paylead WebApp.
  • The Partner IdP must support the optional nonce request 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

  • 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 /authorize endpoint.
The idle session timer counts from the moment the session stops being active, not from the moment it was created.

Expected behaviour by session state

Access check and re-authentication

Step 1. Pre-check before opening

Before opening the WebApp, perform a GET without automatically following redirects.
  • A 2xx response means the session is valid. Open the WebApp directly.
  • A 3xx response whose Location header points to /auth (the Paylead IdP auth route) means the full SSO flow must start (Step 2).
This response also carries the 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.