Social Login (OAuth 2.0)

Ithbat IAM federates external OAuth 2.0 identity providers into your tenant's user directory. Users can sign in with their existing Google, GitHub, Microsoft, or Apple accounts without creating a separate password.

Supported Providers

Provider	Identifier
Google	google
GitHub	github
Microsoft (Azure AD / Entra ID)	microsoft
Apple	apple

Custom OAuth 2.0 providers can be added via the Identity Provider (IdP) configuration API.

---

How It Works

Social login uses the OAuth 2.0 Authorization Code flow. Ithbat IAM acts as the OAuth client on your behalf.

1. Your application redirects the user to the Ithbat IAM social login endpoint.
2. Ithbat IAM redirects the user to the provider's authorization page.
3. The user authenticates with the provider and grants consent.
4. The provider redirects back to the Ithbat IAM callback URL with an authorization code.
5. Ithbat IAM exchanges the code for provider tokens, retrieves the user's profile, and either creates or links the user account.
6. Ithbat IAM returns Ithbat tokens (access, refresh, ID) to your application.

sequenceDiagram
    participant User
    participant App as Your App
    participant Ithbat as Ithbat IAM
    participant Provider as OAuth Provider (Google etc.)

    User->>App: Click "Sign in with Google"
    App->>Ithbat: GET /api/v1/auth/social/google/login?redirect_uri=...
    Ithbat->>Ithbat: Generate state parameter, build auth URL
    Ithbat-->>App: 302 Redirect to provider auth URL
    App-->>User: Browser follows redirect

    User->>Provider: Authenticate and grant consent
    Provider-->>Ithbat: 302 Redirect to /api/v1/auth/social/google/callback?code=...&state=...

    Ithbat->>Provider: Exchange code for access token
    Provider-->>Ithbat: Provider access token + user profile
    Ithbat->>Ithbat: Create or link user account
    Ithbat-->>App: 200 { accessToken, refreshToken, idToken, user }

---

Configuring Providers in the Admin Console

Before social login can be used, configure the provider credentials in the admin console:

1. Go to Settings → Identity Providers in the admin console.
2. Select the provider (e.g., Google).
3. Enter your OAuth application credentials:
   • Client ID — from the provider's developer console
   • Client Secret — from the provider's developer console
4. Set Scopes (defaults are pre-filled per provider).
5. Copy the Callback URL and register it in the provider's developer console.
6. Toggle Enabled and save.

Via API

POST /api/v1/tenant/idp-configs

Required header: Authorization: Bearer <adminToken>

{
  "provider": "google",
  "name": "Google",
  "clientId": "123456789-abc.apps.googleusercontent.com",
  "clientSecret": "GOCSPX-...",
  "scopes": ["openid", "email", "profile"],
  "enabled": true
}

Response — 201 Created

{
  "id": "idp_01J8X...",
  "provider": "google",
  "name": "Google",
  "clientId": "123456789-abc.apps.googleusercontent.com",
  "scopes": ["openid", "email", "profile"],
  "enabled": true,
  "createdAt": "2026-02-24T10:00:00Z",
  "updatedAt": "2026-02-24T10:00:00Z"
}

---

Initiating Social Login

List Enabled Providers

GET /api/v1/auth/social/providers

Required header: X-Tenant-ID: <tenant-uuid>

Response — 200 OK

[
  { "provider": "google", "name": "Google", "enabled": true },
  { "provider": "github", "name": "GitHub", "enabled": true }
]

Start the OAuth Flow

GET /api/v1/auth/social/{provider}/login

Required header: X-Tenant-ID: <tenant-uuid>

Query parameter: redirect_uri — the URL in your application that the user will be redirected to after authentication

GET /api/v1/auth/social/google/login?redirect_uri=https://app.example.com/auth/callback
X-Tenant-ID: ten_01J8X...

This endpoint issues a 302 Found redirect to the provider's authorization page. Your application should follow this redirect (or redirect the user's browser to this URL).

The provider will eventually redirect back to the Ithbat IAM callback URL:

GET /api/v1/auth/social/{provider}/callback?code=...&state=...

Ithbat IAM processes the callback and returns the token response.

---

Callback Response

On successful authentication, the callback endpoint returns 200 OK with the standard token response:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "user": {
    "id": "usr_01J8X...",
    "tenantId": "ten_01J8X...",
    "email": "[email protected]",
    "firstName": "Sara",
    "familyName": "Al-Rashidi",
    "displayName": "Sara Al-Rashidi",
    "roles": ["member"],
    "permissions": ["profile:read"]
  }
}

---

Account Linking

Automatic Linking (Email Match)

If a user with the same verified email already exists in the tenant, Ithbat IAM automatically links the social identity to the existing account rather than creating a duplicate. The user is signed into their existing account.

This behavior requires that the provider returns a verified email address.

Manual Linking (Authenticated User)

Authenticated users can link additional social providers to their account without going through the full OAuth flow from scratch.

Step 1 — Initiate linking (same as a regular social login, but done while the user is already signed in)

POST /api/v1/users/me/identities/{provider}

Required header: Authorization: Bearer <accessToken>

{
  "code": "4/0AX4XfWh...",
  "redirectUrl": "https://app.example.com/settings/accounts"
}

Response — 200 OK

{
  "message": "Identity linked successfully"
}

Listing Linked Identities

GET /api/v1/users/me/identities

Required header: Authorization: Bearer <accessToken>

Response — 200 OK

[
  {
    "id": "fed_01J8X...",
    "provider": "google",
    "providerUserId": "1078239012...",
    "email": "[email protected]",
    "name": "Sara Al-Rashidi",
    "avatarUrl": "https://lh3.googleusercontent.com/...",
    "linkedAt": "2026-02-20T08:30:00Z"
  }
]

Unlinking an Identity

DELETE /api/v1/users/me/identities/{provider}

Required header: Authorization: Bearer <accessToken>

{
  "message": "Identity unlinked successfully"
}

warning

A user cannot unlink their last social identity if they have no password set on their account. They would be locked out. Ithbat IAM prevents this automatically.

---

Code Examples

cURL — List Providers

curl https://api.ithbat.io/api/v1/auth/social/providers \
  -H "X-Tenant-ID: ten_01J8X..."

cURL — Initiate Social Login

Redirect the user's browser to this URL:

curl -L "https://api.ithbat.io/api/v1/auth/social/google/login?redirect_uri=https://app.example.com/callback" \
  -H "X-Tenant-ID: ten_01J8X..."

JavaScript SDK

import { IthbatSDK } from '@ithbatiam/sdk';

const ithbat = new IthbatSDK({
  tenantId: 'ten_01J8X...',
  baseUrl: 'https://api.ithbat.io',
});

// Get available providers
const providers = await ithbat.auth.listSocialProviders();
// [{ provider: 'google', name: 'Google', enabled: true }, ...]

// Start OAuth flow — this redirects the browser
ithbat.auth.startSocialLogin('google', {
  redirectUri: 'https://app.example.com/auth/callback',
});

// Link a social identity to the current user
await ithbat.auth.linkIdentity('github', {
  code: '4/0AX4XfWh...',
  redirectUrl: 'https://app.example.com/settings',
});

// List linked identities
const identities = await ithbat.auth.listIdentities();

// Unlink a provider
await ithbat.auth.unlinkIdentity('github');

---

Error Handling

HTTP Status	Error Code	Cause
400	VALIDATION_ERROR	Missing redirect_uri or X-Tenant-ID
400	VALIDATION_ERROR	Missing state or code in callback
401	UNAUTHORIZED	Provider returned an error or denied access
404	NOT_FOUND	Provider not configured for this tenant
409	CONFLICT	Social identity already linked to a different account

---

Next Steps

• Email & Password — combine with password-based login for a hybrid experience
• Token Lifecycle — understand the tokens returned after social login
• MFA — require a second factor even for social login users