OAuth (Google & Apple)

Let users sign in with their Google or Apple accounts. ezAuth handles the full OAuth 2.0 code flow, ID token verification, and user creation.

Supported Providers

Setup

Google

1. Go to the Google Cloud Console
2. Create an OAuth 2.0 Client ID (Web application)
3. Add your ezAuth callback URL as an authorized redirect URI: https://your-ezauth.com/v1/oauth/google/callback
4. Configure the provider in ezAuth via the dashboard or API

Apple

1. Go to the Apple Developer Portal
2. Create a Services ID with "Sign in with Apple" enabled
3. Create a key for Sign in with Apple
4. Add your callback URL: https://your-ezauth.com/v1/oauth/apple/callback
5. Configure the provider in ezAuth with your team ID, client ID, key ID, and private key

Configure via API

Use the secret key to configure OAuth providers:

// Configure Google OAuth
await fetch('https://your-ezauth.com/v1/oauth/providers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    provider: 'google',
    client_id: 'your-google-client-id.apps.googleusercontent.com',
    client_secret: 'GOCSPX-...',
  }),
})

// Configure Apple OAuth
await fetch('https://your-ezauth.com/v1/oauth/providers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    provider: 'apple',
    client_id: 'com.yourapp.service',
    team_id: 'ABCD1234EF',
    key_id: 'XYZ789',
    private_key: '-----BEGIN EC PRIVATE KEY-----\\n...',
  }),
})

Client-Side Flow

From your frontend, redirect the user to the OAuth authorization URL:

JavaScript

const { authorization_url } = await ez.auth.signInWithOAuth({
  provider: 'google',
  redirectUrl: 'https://myapp.com/dashboard',
})

// Redirect the user to the authorization URL
window.location.href = authorization_url

Swift

let result = try await ez.auth.signInWithOAuth(
    provider: "google",
    redirectUrl: "https://myapp.com/dashboard"
)
// Open result.authorization_url in a browser/webview

How It Works

1. Your app calls GET /v1/oauth/{provider}/authorize?redirect_url=...
2. ezAuth generates a CSRF nonce, stores it in Redis (10-minute TTL), and returns the provider's authorization URL
3. The user authenticates with Google/Apple and is redirected back to ezAuth's callback
4. ezAuth exchanges the authorization code for an ID token
5. The ID token signature is verified against the provider's JWKS (cached 1 hour)
6. ezAuth upserts the user via the OAuth identity (creates a new user or links to an existing one)
7. A session is created, the __session cookie is set, and the user is redirected to your redirect_url

Callback URLs

Managing Providers

Use the secret key to list, configure, or remove OAuth providers: