> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paylead.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Program × Developer: SSO integration between your bank app and the Paylead WebApp (MFP).

<Info>
  The goal is a smooth SSO integration between your bank app and the Paylead
  WebApp, ensuring:

  * correct cookie and session handling between the WebView and the IdPs,
  * no spurious redirects to the authentication screen,
  * and silent re-authentication as long as the IdP sessions are valid.
</Info>

## Authentication flow architecture

### Actors

<CardGroup cols={3}>
  <Card title="Paylead WebApp" icon="smartphone">
    The end-user interface.
  </Card>

  <Card title="Paylead IdP" icon="key">
    The Paylead Identity Provider. Manages the WebApp session (the Paylead session
    cookie).
  </Card>

  <Card title="Partner IdP" icon="landmark">
    Authenticates the bank user. OIDC delegation flows from the Partner IdP to the
    Paylead IdP.
  </Card>
</CardGroup>

<Note>
  The Consumer URL for your Program (`https://consumer-<reference_pm>.paylead.eu`)
  is provided by your Paylead contact.
</Note>

### Flow at a glance

<Steps>
  <Step title="Open the WebApp">
    The user opens the WebApp from the partner app.
  </Step>

  <Step title="Query the Paylead IdP">
    The WebApp queries the Paylead IdP.
  </Step>

  <Step title="Delegate to the Partner IdP">
    The Paylead IdP redirects to the Partner IdP if needed.
  </Step>

  <Step title="Authenticate the user">
    The Partner IdP authenticates the user.
  </Step>

  <Step title="Create the Paylead session">
    The Paylead IdP creates a Paylead session and redirects back to the WebApp.
  </Step>

  <Step title="Open the authenticated WebApp">
    The WebApp opens for the user with an active session.
  </Step>
</Steps>

```mermaid theme={null}
%%{init: {'themeVariables': {'actorBorder':'#0465ff','signalColor':'#378add'}}}%%
sequenceDiagram
    autonumber
    participant U as User (bank app)
    participant A as Bank application
    participant W as Paylead WebApp<br/>consumer-<reference_pm>.paylead.eu
    participant K as Paylead IdP
    participant L as Partner IdP

    U->>A: Opens the Paylead WebApp
    A->>W: GET https://consumer-<reference_pm>.paylead.eu
    W-->>K: Redirect to /auth (Paylead IdP SSO)
    K-->>L: OIDC delegation to the Partner IdP
    L->>L: Authenticates the user
    L-->>K: Returns authorization_code
    K-->>W: Creates Paylead session + redirects to the WebApp
    W-->>A: Serves the authenticated Paylead WebApp
    A-->>U: User sees their Cashback space with no auth screen
```

## Session management

### Session types

| Level       | IdP         | Lifetime                        | Impact                         |
| ----------- | ----------- | ------------------------------- | ------------------------------ |
| Paylead SSO | Paylead IdP | 30 min idle / 10h max (default) | Manages the SSO authentication |
| Partner IdP | Partner     | Variable                        | Authenticates the bank user    |

### Recommended durations

* **Paylead IdP** (configurable):
  * SSO Session Idle: 30 min
  * SSO Session Max: 10h
* **Partner IdP**: must be **≥** the Paylead IdP session to avoid showing the
  authentication screen after a redirect to `/authorize`.

<Note>
  The idle session timer counts from the moment the session stops being active,
  not from the moment it was created.
</Note>

### Expected behaviour by session state

| Paylead IdP session | Partner IdP session | Result                   |
| ------------------- | ------------------- | ------------------------ |
| ✅ Valid             | ✅ Valid             | Direct access            |
| ⚙️ Expired          | ✅ Valid             | Silent re-authentication |
| ⚠️ Expired          | ⚠️ Expired          | Partner IdP auth screen  |
| ⚠️ Valid            | ⚠️ Expired          | Partner IdP auth screen  |
| ❌ Cookies lost      | n/a                 | Redirect to `/auth`      |

## Access check & re-authentication

### Step 1: Pre-check before opening

Before opening the WebApp, perform a `GET` **without automatically following
redirects**:

```http theme={null}
GET https://consumer-<reference_pm>.paylead.eu
```

Expected handling:

* If the response is **2xx** → the session is considered valid, **open the WebApp
  directly**.
* If the response is a **3xx redirect** and the `Location` header points to
  **`/auth`** (the Paylead IdP auth route) → **start the full SSO flow** (Step 2).

<Note>
  The response of this `GET` is also useful for what follows, as it carries:

  * **`state`**: lets you send the user back to the page they originally requested.
  * **`nonce`**: lets you bind the session to the token we create.
</Note>

### Step 2: Web authentication

<Steps>
  <Step title="Follow every redirect">
    Follow all redirects present in the `Location` header.
  </Step>

  <Step title="Keep all cookies">
    Keep every cookie (`Set-Cookie`) received at each step.
  </Step>

  <Step title="Validate the final redirect">
    Check that the last redirect contains `scope`, `state`, `nonce`, `client_id`
    and `redirect_uri`. Otherwise, clear the cookies for the Paylead domain and
    retry once.
  </Step>

  <Step title="Generate the authorization code">
    Generate the `authorization_code` via the custom Paylead IdP plugin.
  </Step>

  <Step title="Build the callback URL">
    ```http theme={null}
    redirect_uri?code=<authorization_code>&state=<state>
    ```
  </Step>

  <Step title="Call the callback">
    Perform a `GET` on this callback, following redirects and storing cookies.
  </Step>

  <Step title="Open the WebApp">
    Open the WebApp with the updated cookies.
  </Step>
</Steps>

## What's next

<CardGroup cols={2}>
  <Card title="WebView configuration" icon="settings" href="/program/webapp/configuration">
    Cookie and WebView setup required for the flow above to work reliably.
  </Card>

  <Card title="Troubleshooting" icon="life-buoy" href="/program/webapp/troubleshooting">
    Diagnose a recurring auth screen, lost cookies, or hard-to-trace behaviour.
  </Card>
</CardGroup>