OAuth Providers

Caution

TOML examples on this page are being updated. The [auth] TOML namespace used throughout does not exist in the engine. JWT and OAuth configuration is done via environment variables (JWT_SECRET, JWT_ALGORITHM, OAuth provider credentials), not fraiseql.toml. See Security for the correct configuration pattern.

FraiseQL supports multiple OAuth2/OIDC providers for authentication, with built-in support for popular identity platforms.

Supported Providers

Provider	Protocol	Features
Google	OIDC	Email verification, profile
GitHub	OAuth2	Org membership, teams
Microsoft Azure AD	OIDC	Tenant isolation, groups
Okta	OIDC	Custom claims, MFA
Auth0	OIDC	Rules, roles, permissions
Keycloak	OIDC	Self-hosted, realm support
Generic OIDC	OIDC	Any compliant provider

Configuration

OAuth provider credentials are configured via environment variables — there is no [auth] section in fraiseql.toml.

Google

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
OAUTH_REDIRECT_URI=https://api.example.com/auth/callback

GitHub

GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
OAUTH_REDIRECT_URI=https://api.example.com/auth/callback

Azure AD

AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id
OAUTH_REDIRECT_URI=https://api.example.com/auth/callback

Okta

OKTA_CLIENT_ID=your-client-id
OKTA_CLIENT_SECRET=your-client-secret
OKTA_DOMAIN=your-domain.okta.com
OAUTH_REDIRECT_URI=https://api.example.com/auth/callback

Auth0

AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://api.example.com
OAUTH_REDIRECT_URI=https://api.example.com/auth/callback

Keycloak

KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=your-client-secret
KEYCLOAK_SERVER_URL=https://keycloak.example.com
KEYCLOAK_REALM=my-realm
OAUTH_REDIRECT_URI=https://api.example.com/auth/callback

Generic OIDC

OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_ISSUER=https://identity.example.com
OAUTH_REDIRECT_URI=https://api.example.com/auth/callback
# Discovery URL auto-detected from issuer (/.well-known/openid-configuration)

Authentication Flow

Authorization Code Flow

1. Client sends login request to FraiseQL
2. FraiseQL redirects to the OAuth provider
3. Provider sends Auth Code + State back to client
4. Client sends the code to FraiseQL callback
5. FraiseQL exchanges the code with the provider for tokens
6. FraiseQL issues a session token to the client

Endpoints

Endpoint	Purpose
/auth/login	Initiate OAuth flow
/auth/callback	OAuth callback handler
/auth/logout	End session
/auth/refresh	Refresh access token
/auth/userinfo	Get current user info

Session Management

Sessions are stored in PostgreSQL or Redis. Configuration is via environment variables:

SESSION_STORAGE=postgres        # postgres | redis | memory
SESSION_TTL_SECONDS=86400       # 24 hours
REFRESH_TTL_SECONDS=604800      # 7 days
REDIS_URL=redis://host:6379/0   # required when SESSION_STORAGE=redis

Security Features

PKCE Support

PKCE (Proof Key for Code Exchange) is configured via [security.pkce] in fraiseql.toml — see Security.

State Encryption

State blobs are encrypted via [security.state_encryption] in fraiseql.toml — see Security.

Role Mapping

Roles are read from the roles claim in the JWT returned by your provider. JWT claim names are configured via environment variables:

JWT_ROLES_CLAIM=roles        # JWT field containing roles (default: roles)
JWT_DEFAULT_ROLE=user        # fallback if no roles claim present

Multi-Provider Setup

Set the active provider via environment variable:

OAUTH_PROVIDER=google         # active provider
OAUTH_DEFAULT_PROVIDER=google # fallback when ?provider= not specified

Login endpoint accepts provider parameter:

/auth/login?provider=github
/auth/login?provider=google

Token Handling

Access Token in Context

Python

# In resolvers, access the authenticated user
@fraiseql.query(sql_source="v_user")
def me(context: Context) -> User:
    user_id = context.user_id  # From token
    roles = context.roles      # Mapped roles
    email = context.email      # From claims

TypeScript

import { query, type Context } from 'fraiseql';

// In resolvers, access the authenticated user
@query({ sqlSource: 'v_user' })
function me(context: Context): User {
  const userId = context.userId;  // From token
  const roles = context.roles;    // Mapped roles
  const email = context.email;    // From claims
}

Go

// In resolvers, access the authenticated user from context
func me(ctx context.Context) (*User, error) {
    userID, ok := ctx.Value("user_id").(string)
    if !ok {
        return nil, fmt.Errorf("user not authenticated")
    }

    roles, _ := ctx.Value("roles").([]string)
    email, _ := ctx.Value("email").(string)

    return &User{
        ID:    userID,
        Email: email,
    }, nil
}

Custom Claims

Custom claim namespacing (used by Auth0, Okta, etc.) is handled automatically — FraiseQL extracts claims from the JWT and makes them available in context. Access in context:

Python

tenant_id = context.claims.get("tenant_id")

TypeScript

const tenantId = context.claims.get('tenant_id');

Go

// Access custom claims from context
func getTenantID(ctx context.Context) (string, error) {
    claims, ok := ctx.Value("claims").(map[string]interface{})
    if !ok {
        return "", fmt.Errorf("no claims in context")
    }

    tenantID, ok := claims["tenant_id"].(string)
    if !ok {
        return "", fmt.Errorf("tenant_id not found in claims")
    }

    return tenantID, nil
}

Test the OAuth Flow

After configuring a provider, verify the full authorization code exchange manually before wiring up a frontend.

1. Start the login flow — open the login URL in a browser or follow the redirect:

   curl -v http://localhost:8080/auth/login?provider=google
   # Follow the Location header to the Google authorization page

2. Authorize in the browser — log in and approve the consent screen. Your browser is redirected back to the callback URL with a code parameter.

3. Exchange the authorization code — FraiseQL handles this automatically via the callback endpoint. To test it directly:

   curl -X POST http://localhost:8080/auth/callback \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "code=AUTHORIZATION_CODE&state=STATE_VALUE&provider=google"

4. Inspect the token response — a successful exchange returns a session token:

   {
     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "token_type": "Bearer",
     "expires_in": 86400,
     "refresh_token": "rt_01HV3KQBN7MXSZQZQR4F5P0G2Y",
     "user": {
       "id": "usr_01HV3KQBN7MXSZQZQR4F5P0G2Y",
       "email": "alice@example.com",
       "name": "Alice Smith",
       "roles": ["user"]
     }
   }

5. Call a protected query using the returned token:

   curl http://localhost:8080/graphql \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
     -H "Content-Type: application/json" \
     -d '{"query":"{ me { id email roles } }"}'

Common OAuth Errors

HTTP Status	Error	Cause	Fix
400 Bad Request	invalid_client	Client ID or secret is wrong	Verify client_id and client_secret match the provider app settings
400 Bad Request	redirect_uri_mismatch	Callback URL not registered	Add redirect_uri exactly as configured to the provider’s allowed redirect list
400 Bad Request	invalid_grant	Authorization code already used or expired	Codes are single-use and expire quickly (usually 60 seconds); do not reuse or delay exchange
401 Unauthorized	invalid_token	Access token expired or revoked	Use /auth/refresh with the refresh token to obtain a new access token
403 Forbidden	access_denied	User denied consent or lacks required scope	Check required scopes in fraiseql.toml; ensure the user approves all requested permissions
403 Forbidden	org_required	User is not a member of required_org (GitHub)	Verify required_org value; user must be a member of that GitHub organization
500 Internal Server Error	token_exchange_failed	Network error reaching the provider	Check outbound connectivity; verify issuer URL and discovery_url are reachable

Tip

All OAuth errors are logged at WARN level. Run LOG_LEVEL=debug fraiseql run to see the full error response from the provider, which usually includes a more specific error_description field.

Metrics

Metric	Description
fraiseql_auth_logins_total	Login attempts
fraiseql_auth_login_success_total	Successful logins
fraiseql_auth_login_failure_total	Failed logins
fraiseql_auth_token_refresh_total	Token refreshes
fraiseql_auth_session_active	Active sessions

Troubleshooting

Redirect URI Mismatch

Ensure redirect URI matches exactly in:

1. FraiseQL config
2. Provider app settings
3. Actual callback URL

Token Validation Errors

1. Check clock sync between servers
2. Verify issuer URL is correct
3. Check token hasn’t expired

Missing Claims

1. Verify scopes include required claims
2. Check provider-specific claim names
3. Review claim mapping configuration

JWT Claims and Role Mapping

FraiseQL maps JWT claims to user roles automatically. Given this token (decoded):

{
  "sub": "usr_123",
  "email": "alice@example.com",
  "roles": ["admin", "editor"],
  "exp": 1740787200,
  "iss": "https://auth.example.com"
}

FraiseQL grants access to all resolvers decorated with @role("admin") or @role("editor"). The roles claim field is configured via the JWT_ROLES_CLAIM environment variable (default: roles).

Next Steps

Security

Security — RBAC and field-level authorization

Rate Limiting

Rate Limiting — Protect auth endpoints

Deployment

Deployment — Production OAuth setup