Getting Started

Enterprise SSO

Deep Identity Provider integration using OIDC token exchange for Keycloak, Okta, and Azure AD.

Enterprise SSO (Token Exchange)

Token Exchange is for organizations that want Francoflex to trust tokens issued by their Identity Provider (Keycloak, Okta, Azure AD). This provides true Single Sign-On where users authenticate once with your IdP and gain access to Francoflex automatically.

How It Works

sequenceDiagram
    participant U as User
    participant IdP as Your Identity Provider
    participant P as Your Application
    participant F as Francoflex API
    participant FB as Firebase Auth

    U->>IdP: Login
    IdP-->>U: Issue JWT (ID Token)
    U->>P: Access App
    P->>F: POST /api/auth/sso/token-exchange<br/>(JWT + OrgID)
    F->>F: Validate JWT signature<br/>against IdP keys
    F->>FB: Exchange for Firebase Session
    F-->>P: Success (Set Session Cookie)
    P-->>U: Authenticated into Francoflex

Benefits

Centralized Identity: Manage all users through your existing IdP
Automatic Provisioning: Users are created/updated automatically on first login
Group Sync: (Optional) Synchronize groups and roles from your IdP
Standards-Based: Uses OpenID Connect (OIDC) for interoperability

Configuration Requirements

To set up Enterprise SSO, provide us with:

Requirement	Example
Issuer URL	`https://keycloak.yourdomain.com/realms/main`
Client ID	The audience claim expected in tokens
JWKS Endpoint	Where we fetch your public signing keys

We'll configure Francoflex to trust tokens signed by your IdP.

API Usage

Endpoint: POST /api/auth/sso/token-exchange

Body:

{
  "token": "<YOUR_OIDC_ID_TOKEN>",
  "organizationId": "your_org_id"
}

Response: Sets the Set-Cookie header for the authenticated session and returns user profile data.

Token Requirements

Your OIDC ID Token must include:

Claim	Description
`sub`	Unique user identifier
`email`	User's email address
`iss`	Must match your configured Issuer URL
`aud`	Must match your configured Client ID
`exp`	Token must not be expired

Implementation Example

// After user authenticates with your IdP
async function redirectToFrancoflex(idToken, orgId) {
  const response = await fetch('https://francoflex.com/api/auth/sso/token-exchange', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token: idToken,
      organizationId: orgId
    }),
    credentials: 'include' // Important: allows cookie to be set
  });

  if (response.ok) {
    // Session cookie is now set, redirect user
    window.location.href = 'https://francoflex.com/dashboard';
  }
}

Getting Started

Contact us with your IdP details (Issuer URL, Client ID, JWKS endpoint)
We configure Francoflex to trust your IdP
Test the integration in a staging environment
Go live once everything is verified

Troubleshooting

Issue	Solution
"Invalid token"	Verify the token hasn't expired and issuer matches
"Unknown issuer"	Contact us to verify IdP configuration
"Invalid signature"	Ensure JWKS endpoint is accessible and keys are current