OAuth 2.0 Authentication

Beta OAuth/OIDC integration endpoints for GitHub, Google, and Microsoft. Public provider-interoperability and protocol-conformance results are not yet published; validate the exact provider configuration and flows you rely on.

Overview

AuthOS supports three OAuth providers with the option to use your own OAuth credentials (BYOO - Bring Your Own OAuth).

Endpoints

GET /auth/:provider

Initiate OAuth 2.0 authentication flow for end-users.

Synopsis

Path Parameters

Query Parameters

Example Request

curl -X GET "https://sso.example.com/auth/github?org=acme-corp&service=main-app&redirect_uri=https://app.acme.com/callback"

Response: 302 Redirect to OAuth provider’s authorization page

Errors

GET /auth/:provider/callback

Handle OAuth callback from provider. Exchanges authorization code for access token, creates or updates user account, and generates JWT session.

Synopsis

Path Parameters

Query Parameters

Success Response: Redirects to service’s redirect_uri with tokens in the URL fragment:

https://app.acme.com/callback#access_token={jwt}&refresh_token={token}

Security Note: URL fragments are not normally sent to the origin server, which reduces exposure in server query logs. Tokens can still be exposed to browser history, extensions, client-side scripts, screenshots, or telemetry; client applications must parse and clear window.location.hash carefully.

Or returns HTML success page if no redirect_uri configured.

Error Response: HTML error page with user-friendly message

Admin OAuth Authentication

GET /auth/admin/:provider

Initiate OAuth flow for platform owners and organization administrators.

Query Parameters

Response: 302 Redirect to OAuth provider’s authorization page

GET /auth/admin/:provider/callback

Handle admin OAuth callback. Creates admin JWT with appropriate permissions (platform owner or organization admin).

Success Response: Redirects to platform admin redirect URI with tokens

BYOO (Bring Your Own OAuth)

Organizations can use their own OAuth credentials instead of platform defaults.

Configuring Custom OAuth Credentials (BYOO)

curl -X POST https://sso.example.com/api/organizations/acme-corp/oauth-credentials/github \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-app-client-id",
    "client_secret": "your-app-client-secret"
  }'

Benefits

• Custom branding on OAuth consent screen
• App-specific callback URLs
• Control over OAuth scopes
• Separate analytics from platform

OAuth Flow Sequence

sequenceDiagram
    participant User
    participant App
    participant AuthOS
    participant Provider

    User->>App: Click "Login with GitHub"
    App->>AuthOS: GET /auth/github?org=acme&service=app
    AuthOS->>Provider: Redirect to GitHub authorization
    Provider->>User: Show consent screen
    User->>Provider: Authorize
    Provider->>AuthOS: Callback with code
    AuthOS->>Provider: Exchange code for token
    Provider-->>AuthOS: Access token + profile
    AuthOS->>AuthOS: Create/update user
    AuthOS->>AuthOS: Generate JWT
    AuthOS->>App: Redirect with JWT
    App->>User: Logged in

Security Considerations

1. CSRF Protection - State parameter validates callback origin
2. Redirect URI Validation - Only whitelisted URIs allowed
3. HTTPS Required - Operators must enforce HTTPS at the reverse proxy or ingress for every OAuth endpoint
4. Token Storage - Provider tokens encrypted at rest
5. Upstream PKCE - For mobile and desktop service types, AuthOS generates the provider code_challenge and binds the verifier to its stored upstream login transaction. The consuming application does not act as a client of an AuthOS authorization-code endpoint.