Chapter 3A — Social & Custom OAuth 2.0 Federation

OAuth 2.0 Social & Custom Connections

Eliminate signup friction by letting users sign in with Google, GitHub, Microsoft, Apple, LinkedIn, Facebook, or any custom OAuth 2.0 provider in under two minutes via /connections.

The Social Login Story 1. Built-In Templates 2. Step-by-Step Setup 3. Profile & Group Mapping 4. API & AI Prompt

Developer Story: Boosting SaaS Sign-Up Conversion by 42%

Adding Google & GitHub Login Without Writing Provider-Specific Code

CloudPulse's growth team noticed developers were dropping off at the registration form because they didn't want to invent another password. Instead of installing separate Passport.js strategies for Google, GitHub, and LinkedIn inside their application code, CloudPulse configured those three OAuth 2.0 providers in SSO.ID v2 ( /connections) and enabled them on their Application.

Zero Code Changes in Your App: Your application still speaks a single standard OIDC/OAuth 2.0 flow with https://{your-tenant}.sso.id/auth. SSO.ID brokers the upstream OAuth 2.0 handshake with Google or GitHub, normalizes the profile attributes, auto-provisions the user, and returns a clean, standard SSO.ID JWT to your app.

1. Pre-Configured OAuth 2.0 Provider Templates

When you click Create Connection in /connections and choose OAuth 2.0, SSO.ID loads verified defaults from GET /api/connections/defaults so Authorization URLs, Token URLs, UserInfo URLs, and default scopes are pre-filled automatically:

Flow Diagram Social OAuth 2.0 Brokering & Profile Normalization Flow

flowchart LR APP["Client App"] -->|"Standard OIDC Request"| SSO["SSO.ID Broker (Auth.SSO.Id)"] SSO -->|"OAuth 2.0 Handshake"| SOC{"Social IdP"} SOC -->|"Google"| G["Google Profile (sub, email, picture)"] SOC -->|"GitHub"| GH["GitHub Profile (id, login, avatar_url)"] SOC -->|"LinkedIn"| LI["LinkedIn Profile (id, localizedFirstName)"] G --> NORM["SSO.ID Normalization Engine"] GH --> NORM LI --> NORM NORM --> APPTOK["Unified Standard SSO.ID JWT & User Claims"]

SSO.ID abstracts disparate provider schemas (Google, GitHub, Apple), returning a unified RS256 token and user profile to your application.

Provider	Pre-Configured Endpoints	Default Scopes	Callback URL to Register in Provider Console
Google	`accounts.google.com/o/oauth2/v2/auth` `oauth2.googleapis.com/token`	`openid profile email`	`https://{your-tenant}.sso.id/auth/oauth/callback` (or your custom domain)
GitHub	`github.com/login/oauth/authorize` `github.com/login/oauth/access_token`	`read:user user:email`	`https://{your-tenant}.sso.id/auth/oauth/callback`
Microsoft	`login.microsoftonline.com/common/oauth2/v2.0/authorize`	`openid profile email User.Read`	`https://{your-tenant}.sso.id/auth/oauth/callback`
LinkedIn / Apple / Facebook	Pre-configured OAuth 2.0 v2 endpoints	`openid profile email`	`https://{your-tenant}.sso.id/auth/oauth/callback`
Custom OAuth 2.0	Any RFC 6749 Authorization, Token & UserInfo URL	Custom space-delimited scopes	`https://{your-tenant}.sso.id/auth/oauth/callback`

2. Step-by-Step Setup in the v2 Admin Console

Select OAuth 2.0 & Provider Template

Navigate to /connections → Add Connection → select OAuth 2.0. Pick a template (e.g., Google or GitHub) or choose Custom. Paste the Client ID and Client Secret obtained from the external provider's developer console.

Run Live Pre-Save Test (`POST /api/connections/test`)

Click Test Connection at the bottom of the dialog. Authenticate with your Google/GitHub account in the popup window and verify that SSO.ID receives your email, name, and avatar cleanly.

Enable on Target Applications or Organizations

Enable the connection globally for specific Applications ( /applications → Settings → Connections tab) or scope it to a specific B2B customer Organization using assignToOrganizationOnly.

3. Attribute Mapping & Just-In-Time (JIT) Provisioning

In the Mappings tab of the OAuth 2.0 Connection dialog, configure how JSON fields returned by the provider's UserInfo endpoint map to SSO.ID user properties:

email ← email (or primary verified email from GitHub)
firstName ← given_name (or split from name)
lastName ← family_name
avatarUrl ← picture / avatar_url

4. Programmatic Creation & AI Agent Prompt

AI Agent Prompt Create & Wire an OAuth 2.0 Social Connection via API & Frontend Button

You are a full-stack identity developer. Add "Continue with Google" and "Continue with GitHub" buttons to my application using **SSO.ID v2**.

### How SSO.ID v2 Social Login Works
1. In the Admin Console (`/connections`), we created Google (`CONNECTION_ID_GOOGLE`) and GitHub (`CONNECTION_ID_GITHUB`) OAuth 2.0 connections and enabled them on our Application (`CLIENT_ID`).
2. To trigger social login directly from our custom frontend button (bypassing the hosted chooser) OR via the hosted login page:
   - Redirect the browser to `GET https://{your-tenant}.sso.id/auth/oauth/authorize` with standard OIDC PKCE params (`client_id`, `response_type=code`, `redirect_uri`, `scope=openid profile email`, `state`, `code_challenge`, `code_challenge_method=S256`) PLUS `connectionId=${CONNECTION_ID_GOOGLE}`.
3. Handle the callback on `redirect_uri` identically to standard OIDC by exchanging `code` at `POST https://{your-tenant}.sso.id/auth/oauth/token`.

Please generate the social login button components and PKCE redirect helper.