# Trust Relationship Authentication

## Goal

Use industry standards to power developer access to DailyPay APIs and Embedded Experiences, minimizing user and developer surprise and maximizing user-session reuse.

## Approach

Use nested OIDC flows to authenticate users for DailyPay using the developer’s Identity Provider.

## Methods

Developers will use OAuth2.0 Authorization Code Flow + PKCE and OIDC to retrieve access and refresh tokens for use with [DailyPay APIs](/products/rest/reference/) and [DailyPay Elements](/elements/): see [Authorization Code Flow](/guides/auth/authorization-code-flow).

Within the Authorization Code Flow, DailyPay will reach out to the partner’s Identity Provider to identify the user. DailyPay prefers an OIDC Identity Provider wherever possible, and our Auth Server will initiate its own, **nested** OAuth2.0 Authorization Code Flow to the partner’s Auth Server. If the partner’s Auth Server identifies an active session, the experience is seamless and potentially zero-touch for the end user, and DailyPay will match the subject identifier from the active session to an identity loaded into DailyPay from the Data Exchange or elsewhere. DailyPay Auth Server will then return the payload needed to complete the Authorization Code Flow and obtain an access token for the API or Element.

**Note**: An important prerequisite is that a unique identifier for each user is shared across systems, usually through the DailyPay Data Exchange.

The following diagram details all steps of the OIDC-in-OIDC or SAML-in-OIDC approach.


```mermaid
%%{init: {'theme': 'forest'}}%%
sequenceDiagram
    autonumber
    actor User
    participant Your Auth Server
    participant Your Application
    participant DailyPay Auth Server
    participant DailyPay API
    Your Auth Server-->>User: Has an authenticated session
    User->>Your Application: Clicks on funtionality requiring DailyPay user access
    Your Application->>Your Application: Construct a signed OAuth2 Request URL
    Your Application->>User: Open a webview or secure tab to request URL with iss=your_auth_url
    User->>DailyPay Auth Server: Initiate OAuth2 Authorization Code Flow
    critical OIDC (Preferred)
        DailyPay Auth Server->>User: Redirect to your auth URL with DailyPay client parameters
        User->>Your Auth Server: Login or reuse session
        Your Auth Server->>User: Redirect user to DailyPay callback URL with authorization code
        User->>DailyPay Auth Server: Authorization code
        DailyPay Auth Server->>Your Auth Server: Exchange authorization code
        Your Auth Server->>DailyPay Auth Server: Return access token and (optionally) ID token
        DailyPay Auth Server->>DailyPay Auth Server: Extract unique ID from ID token
    end
    opt SAML
        DailyPay Auth Server->>User: Redirect to your SSO URL
        User->>Your Auth Server: Login or reuse session
        Your Auth Server->>User: Redirect user with SAML response
        User->>DailyPay Auth Server: SAML response forwarded
        DailyPay Auth Server->>DailyPay Auth Server: Validate SAML response
        DailyPay Auth Server->>DailyPay Auth Server: Extract unique ID from SAML
    end
    DailyPay Auth Server->>User: Present terms and conditions
    User->>DailyPay Auth Server: Click to sign terms and conditions
    DailyPay Auth Server-->>DailyPay API: Activate user
    DailyPay Auth Server->>User: Redirect user to your callback URL with authorization code
    User->>Your Application: authorization code
    Your Application->>DailyPay Auth Server: Exchange authorization code
    DailyPay Auth Server->>Your Application: Return API access token
    Your Application->>DailyPay API: Authenticate API calls
```

## Guidance for Developers Without Preexisting OIDC or SSO

In order to establish a trust relationship, DailyPay needs a way to verify the authenticity of the user session that wraps the Authorization Code Flow. OAuth2.0 with OIDC provides a set of mechanisms to establish that trust relationship. Below are the critical elements, that even without full OIDC support, are advised or required to create the highest security and lowest friction user auth experience.

1. Accept an OAuth2.0-style GET request (6), and return an authorization code using an http redirect to the DailyPay callback endpoint (8).
  1. If the user is already logged in with an active session (1), the authorization server should detect the session (7) and return the authorization code without prompting the user for additional information.
2. Allow only the DailyPay preregistered client to exchange that authorization code (10) for an access token (11), using a client secret or a signature using our public key.
3. Populate the access token or an OIDC-style JWT Identity Token with signed claims, and provide a way to validate those claims.
  1. The claims must include the shared unique identifier for the user (12).