> ## Content Index
> Fetch the complete content index at: https://blog.fabrixly.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# How 2FA and Social Logins Work (Architectural Guide)
- URL: https://blog.fabrixly.com/how-to-use-2fa-and-social-logins-architecture/
- Published: 2026-07-07T14:10:43.000Z
- Updated: 2026-07-07T14:10:43.000Z
- Author: Fabrixly
- Tags: Documentation

This guide describes the technical workflows of **Two-Factor Authentication (2FA)** and **Social Logins** inside the Fabrixly-IDS OIDC interaction engine, explaining how session state, tokens, and redirects are managed during multi-step logins.

---

## Part A: Social Logins OIDC Workflow

Social Logins (Google, GitHub) hook directly into the OIDC interaction flow. Here is the step-by-step path from authorization redirect to interaction completion:

```mermaid
sequenceDiagram
    participant ClientApp as Client Application (SPA/Backend)
    participant IDS as Fabrixly-IDS (OIDC Issuer)
    participant UI as Login / Interaction Screen
    participant Google as Google OAuth Authority

    ClientApp->>IDS: GET /oidc/auth (OIDC Authorization Redirect)
    IDS->>UI: Redirect to /interaction/:uid (Consent/Login Screen)
    UI->>Google: Click Login → GET /api/auth/google?client_id=...&uid=:uid
    Google-->>IDS: Callback GET /api/auth/google/callback?code=...
    Note over IDS: Verifies Google profile, links/creates User record, creates session
    IDS->>UI: Redirect GET /interaction/:uid/google-callback?token=:jwtToken
    Note over UI: Verifies temporary JWT, sets active session, calls interactionFinished
    UI->>IDS: interactionFinished() callback
    IDS->>ClientApp: Redirect to Callback URI with Auth Code

```

### 1\. Initiation

The client application redirects the user to `/oidc/auth`. The OIDC provider detects no active session and redirects the browser to the interaction page: `/interaction/:uid`.

### 2\. Social Login Redirection

The interaction UI displays Google/GitHub buttons. Clicking a button triggers a query containing the OIDC session identifier (`uid`): `GET https://ids.fabrixly.com/api/auth/google?client_id=your-client-id&uid=oidc-session-uid`

### 3\. Callback & User Provisioning

After authenticating at Google, Google callbacks to `/api/auth/google/callback` with `state` containing the `uid`.

- **Existing User**: Links `googleId` if it is not already stored on the user's database record.
- **Just-in-Time (JIT) Provisioning**: If the email doesn't exist, Fabrixly-IDS auto-registers the user under the client's parent organization.
- **Session Creation**: The server creates a session and redirects the browser to: `GET /interaction/:uid/google-callback?token=<signed-jwt-containing-userId>`

### 4\. Completing OIDC Flow

The interaction route (`/:uid/google-callback`) validates the temporary JWT token, marks the OIDC session login reference (`amr: ['google']`), and calls: `provider.interactionFinished(req, res, { login: { accountId: userId } })` This redirects the user back to the client application with the standard OIDC authorization code.

---

## Part B: Two-Factor Authentication (2FA) Workflow

2FA (`password_and_otp`) divides the login screen into a two-step verification process context-bound by the OIDC session.

### 1\. Step 1: Password Verification

1. The user enters their email and password on the login screen.
2. The UI posts credentials to: `POST /interaction/:uid/login`.
3. Upon matching the password hash, the backend:
  - Generates a cryptographically secure 6-digit OTP code.
  - Sends the code using the configured provider (SMTP or SMS).
  - Stores the intermediate auth state (e.g. `is_password_verified: true`) on the OIDC interaction session.

Returns:

```json
{
  "status": "otp_required",
  "message": "Please enter the OTP verification code sent to your device."
}

```

### 2\. Step 2: OTP Challenge

1. The UI displays the OTP submission input box.
2. The user submits the code: `POST /interaction/:uid/verify-otp`.
3. The backend verifies the OTP code against expiration limits (default: 5 minutes):
  - If correct, it completes the session, registers the user login event in the audit logs, and calls `interactionFinished` to complete the OIDC auth code redirect.

---

## Part C: Interaction Between Social Logins and 2FA

When a user authenticates via a social identity provider (Google/GitHub), standard credential challenges (password and OTP) are **bypassed by default** because the identity provider has already confirmed the authentication.

### Enforcing Multi-Factor on Social Login

If your security policies mandate that social users must still complete a second-factor challenge (e.g., verifying a mobile OTP):

1. Ensure `enable_2fa: true` is toggled on the user profile record.
2. After the social callback completes `/interaction/:uid/google-callback`, the interaction controller detects `enable_2fa: true` on the user entity.
3. Rather than finalizing the flow, the controller generates an OTP code, redirects the user to the `/interaction/:uid/mfa` challenge screen, and expects the user to verify the code before calling `interactionFinished`.