OAuth Providers

Pulsabase includes a built-in Identity Provider (IDP) that handles social login flows on your behalf. Users can sign in with a third-party provider, and Pulsabase will create (or link) a local user account automatically.

Supported Providers

Provider	Status	Notes
Google	Available	OIDC-based, returns email + name + avatar
GitHub	Available	OAuth2, returns email + login
Microsoft	Available	OIDC-based (Azure AD / Entra ID)
Custom OIDC	Available	Any OIDC-compliant provider (Okta, Keycloak, Auth0, etc.)
Apple	Coming Soon	—

How It Works

The OAuth flow is handled entirely server-side by pulsabase-idp:

1. Frontend opens: GET /oauth/projects/{pid}/providers/{provider}/start
        ↓ IDP generates a random `state` (CSRF protection) and returns:
        { "auth_url": "https://accounts.google.com/o/oauth2/auth?...", "state": "xyz" }

2. Frontend redirects the user to the provider's auth_url
        ↓ User authenticates with Google/GitHub/etc.
        ↓ Provider redirects back to your configured callback URL

3. IDP callback: GET /oauth/projects/{pid}/providers/{provider}/callback?code=...&state=...
        ↓ IDP validates the state (anti-CSRF)
        ↓ IDP exchanges the code → provider access token
        ↓ IDP fetches user identity (email, name, avatar)
        ↓ IDP creates or links the local user account
        ↓ IDP issues Pulsabase JWT (access_token + refresh_token)
        ↓ Returns JWT to your frontend

Account Linking

If a user with the same email already exists (e.g., they previously signed up with email/password), Pulsabase automatically links the social identity to that existing account. The user sees no difference.

If this is a new email, a new user account is created automatically (if self-registration is allowed in Dashboard → Authentication → Settings).

Step 1 — Configure the Provider

In Dashboard → Authentication → Providers:

1. Select the provider (Google, GitHub, Microsoft, or Custom OIDC)
2. Enter the Client ID and Client Secret from the provider’s console
3. Copy the Callback URL shown in the dashboard and paste it into the provider’s OAuth app settings
4. Enable the provider and save

Provider OAuth App Setup

Google

1. Go to Google Cloud Console → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Web application
4. Authorized redirect URI: https://your-idp.pulsabase.io/oauth/projects/{project_id}/providers/google/callback
5. Copy Client ID and Client Secret into the Dashboard

GitHub

1. Go to GitHub → Settings → Developer Settings → OAuth Apps
2. Click New OAuth App
3. Authorization callback URL: https://your-idp.pulsabase.io/oauth/projects/{project_id}/providers/github/callback
4. Copy Client ID and generate a Client Secret

Microsoft

1. Go to Azure Portal → App registrations
2. Click New registration
3. Redirect URI: https://your-idp.pulsabase.io/oauth/projects/{project_id}/providers/microsoft/callback
4. Copy Application (client) ID and create a Client Secret in Certificates & secrets

Custom OIDC

For any OIDC-compliant provider (Okta, Keycloak, Auth0, Ping, etc.), you need:

Field	Description
Client ID	OAuth client ID
Client Secret	OAuth client secret
Auth URL	Provider’s authorization endpoint
Token URL	Provider’s token endpoint
Userinfo URL	Provider’s userinfo endpoint
JWKS URL	Provider’s public key set (for token verification)
Issuer	Token issuer (for validation)
Scopes	Usually openid profile email
Redirect URI	Your IDP callback URL

All these fields are available in the provider’s OIDC discovery document at /.well-known/openid-configuration.

Step 2 — Initiate the Login (Frontend)

Your frontend starts the OAuth flow by requesting the authorization URL from the IDP:

TypeScript (SDK Helper)

// Coming soon: pb.auth.signInWithProvider('google')
// For now, use the direct API:

const res = await fetch(
  `${pb.idpUrl}/oauth/projects/${pb.projectId}/providers/google/start`,
  {
    headers: {'X-Api-Key': pb.apiKey}
  }
);
const { auth_url, state } = await res.json();

// Save state in sessionStorage for CSRF validation
sessionStorage.setItem('oauth_state', state);

// Redirect the user to Google
window.location.href = auth_url;

Direct API (cURL)

curl "https://your-idp.pulsabase.io/oauth/projects/{project_id}/providers/google/start" \
  -H "X-Api-Key: pk_live_your_api_key"

# Response:
# {
#   "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
#   "state": "abc123xyz"
# }

Step 3 — Handle the Callback

After the user authenticates with the third-party provider, they are redirected to your configured callback URL. The IDP then returns a JWT directly:

GET /oauth/projects/{project_id}/providers/google/callback?code=XXXX&state=abc123xyz

The IDP handles the token exchange internally. If the flow is successful, the response contains the same session tokens as a regular sign-in:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "rt_xxxx",
  "id_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "provider": "google"
}

Store these tokens using the SDK’s session management:

// After receiving the tokens from your callback handler:
pb.auth.setSession({ access_token, refresh_token });

Security

Mechanism	Implementation
CSRF protection	A random state is generated per flow and validated on callback
State expiry	OAuth state is valid for 10 minutes only
PKCE	Supported for public clients (no client_secret)
Account linking	Linked by email or external sub — prevents duplicate accounts
Self-registration control	Dashboard setting to disable auto account creation

Self-Registration Policy

By default, new OAuth users are automatically registered. You can disable this in Dashboard → Authentication → Settings → Allow Self-Registration.

When disabled:

• A user can only sign in via OAuth if they already have an account with the same email
• First-time users from OAuth providers will receive a 403 error
• This is useful for invite-only or enterprise applications

Session & Token Behavior

OAuth sessions behave identically to email/password sessions:

• The resulting access_token is a standard Pulsabase JWT
• JWT claims include the user’s sub, email, roles, permissions, and sub_tenant_id
• The token is used for all database queries and storage operations
• Token refresh works exactly the same as email sessions

Note

The provider field in the JWT claim indicates the authentication method (social-google, social-github, etc.), which you can use in RLS policies if needed.