OIDC Federation

Beta

This feature is in beta. Core behavior is stable and ready to try, but some APIs or configuration may still evolve before general availability.

Connect any OpenID Connect-compliant identity provider to EdgeBase. Beyond the 14 built-in OAuth providers, OIDC Federation lets you integrate with corporate identity systems (Okta, Auth0, Azure AD, Keycloak, etc.) or any provider that supports the OIDC discovery protocol.

Standard OAuth Flow

OIDC Federation providers use the same OAuth sign-in flow as built-in providers. From the client SDK perspective, the only difference is the provider name format: oidc:{name} instead of a built-in name like google.

How It Works

1. EdgeBase fetches the provider's OpenID Connect Discovery document from {issuer}/.well-known/openid-configuration
2. The discovery document provides the authorization_endpoint, token_endpoint, and userinfo_endpoint
3. The standard OAuth authorization code flow runs using these discovered endpoints
4. EdgeBase requires and cryptographically verifies the ID token against the discovery document's JWKS, issuer, audience, expiry, authorized party, and per-flow nonce
5. EdgeBase fetches the authenticated userinfo_endpoint and requires its sub to match the verified ID token before using profile or email claims
6. PKCE is automatically enabled for all OIDC providers

Configuration

1. Register in allowedOAuthProviders

Add your OIDC provider with the oidc: prefix:

// edgebase.config.ts
export default defineConfig({
  auth: {
    allowedOAuthProviders: [
      'google',                // Built-in provider
      'oidc:okta',             // Custom OIDC provider
      'oidc:azure-ad',         // Another custom OIDC provider
      'oidc:keycloak',         // Any name you choose after oidc:
    ],
  },
});

2. Set Credentials and Issuer

OIDC provider credentials are configured in edgebase.config.ts under auth.oauth.oidc.{name}:

export default defineConfig({
  auth: {
    oauth: {
      oidc: {
        okta: {
          clientId: 'YOUR_CLIENT_ID',
          clientSecret: 'YOUR_CLIENT_SECRET',
          issuer: 'https://your-org.okta.com',
        },
      },
    },
  },
});

Each OIDC provider requires three fields:

Field	Required	Description
clientId	Yes	OAuth client ID from your identity provider
clientSecret	Yes	OAuth client secret
issuer	Yes	The exact OIDC issuer URL (must serve a matching /.well-known/openid-configuration; HTTPS is required outside loopback development)
scopes	No	Custom scopes array (default: ['openid', 'email', 'profile'])

3. Register Redirect URI

In your identity provider's admin console, register the callback URL:

https://your-edgebase-url/api/auth/oauth/oidc:{name}/callback

For example, if your OIDC provider is named okta:

https://your-edgebase-url/api/auth/oauth/oidc:okta/callback

For local development:

http://localhost:8787/api/auth/oauth/oidc:okta/callback

Provider Setup Examples

Okta

{
  "auth": {
    "oauth": {
      "oidc": {
        "okta": {
          "clientId": "0oaxxxxxxxxxxxxxxxx",
          "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "issuer": "https://your-org.okta.com"
        }
      }
    }
  }
}

Okta issuer URL format: https://{your-org}.okta.com or https://{your-org}.okta.com/oauth2/default for the default authorization server.

Auth0

{
  "auth": {
    "oauth": {
      "oidc": {
        "auth0": {
          "clientId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "issuer": "https://your-tenant.auth0.com"
        }
      }
    }
  }
}

Azure AD (Entra ID)

{
  "auth": {
    "oauth": {
      "oidc": {
        "azure-ad": {
          "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0"
        }
      }
    }
  }
}

Replace {tenant-id} with your Azure AD tenant ID. Use common for multi-tenant apps.

Keycloak

{
  "auth": {
    "oauth": {
      "oidc": {
        "keycloak": {
          "clientId": "my-client",
          "clientSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "issuer": "https://keycloak.example.com/realms/my-realm"
        }
      }
    }
  }
}

Custom Scopes

Override the default scopes if your provider requires specific ones:

{
  "auth": {
    "oauth": {
      "oidc": {
        "custom-provider": {
          "clientId": "...",
          "clientSecret": "...",
          "issuer": "https://idp.example.com",
          "scopes": ["openid", "email", "profile", "groups"]
        }
      }
    }
  }
}

Usage

OIDC providers use the same SDK methods as built-in OAuth providers. Use the oidc:{name} format for the provider parameter.

Native callback support

Only @edge-base/web and @edge-base/react-native currently complete a bound app callback. The Dart, Swift, Kotlin, Java, and C# methods shown below only construct a provider-start URL; they are not an end-to-end production OAuth completion flow.

JavaScript

// Sign in with an OIDC provider
client.auth.signInWithOAuth('oidc:okta');

// With redirect URL
client.auth.signInWithOAuth('oidc:azure-ad', {
  redirectUrl: 'https://my-app.com/auth/callback',
});

Dart/Flutter

final url = client.auth.signInWithOAuth('oidc:okta');

Swift

let url = await client.auth.signInWithOAuth(provider: "oidc:okta")
// Open url in SFSafariViewController or ASWebAuthenticationSession

Kotlin

val url = client.auth.signInWithOAuth("oidc:okta")

Java

client.auth().signInWithOAuth("oidc:okta");

C#

client.Auth.SignInWithOAuth("oidc:okta");

REST API

OIDC federation uses the same OAuth endpoints with the oidc:{name} provider parameter:

Endpoint	Description
GET /auth/oauth/oidc:{name}	Start OIDC OAuth flow (redirects to provider)
GET /auth/oauth/oidc:{name}/callback	Handle OIDC OAuth callback
POST /auth/oauth/link/oidc:{name}	Link the current account to an OIDC provider (anonymous upgrade or signed-in attach)
GET /auth/oauth/link/oidc:{name}/callback	OIDC link callback

Technical Details

Discovery Document Caching

EdgeBase caches the OIDC discovery document in memory for 1 hour per Worker instance. This avoids refetching the discovery document on every authentication request while still picking up provider configuration changes reasonably quickly.

ID Token and Userinfo Verification

An id_token, discovery jwks_uri, and userinfo_endpoint are required for the current OIDC flow. EdgeBase accepts only asymmetric JWT algorithms, verifies the signature with the discovered JWKS, and checks iss, aud, exp, iat, sub, nonce, and azp when required. The discovery document's issuer must match the configured issuer, and discovered endpoints must be HTTPS except for explicit loopback development.

After ID-token verification, EdgeBase fetches userinfo with the provider access token and requires userinfo.sub === id_token.sub. Profile data comes from that authenticated userinfo response. email_verified is true only for the literal boolean true or string "true"; other truthy-looking values do not enable email auto-linking. There is no decode-only or missing-ID-token fallback.

PKCE Support

PKCE (Proof Key for Code Exchange) is automatically enabled for all OIDC providers, providing an additional layer of security for the authorization code exchange.

Account Linking

If a user signs in with an OIDC provider using an email that already exists in your EdgeBase project, accounts are automatically linked when the email is verified by the provider. See Account Linking for details.

Verifying Your Setup

To verify that your OIDC provider is correctly configured:

1. Confirm the discovery endpoint is accessible: curl https://your-issuer/.well-known/openid-configuration
2. Verify the response includes issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, and jwks_uri
3. Confirm the redirect URI is registered in your provider's admin console
4. Start the dev server and attempt a sign-in via GET /api/auth/oauth/oidc:{name}