OAuth 2.0 Authentication

OAuth 2.0 endpoints for authenticating users via GitHub, Google, and Microsoft providers.

Overview

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

Provider	Supported Features
GitHub	User email, profile, organizations
Google	OpenID Connect, profile, configurable scopes
Microsoft	Azure AD, personal accounts, configurable scopes

Endpoints

Method	Path	Description
`GET`	`/auth/:provider`	Initiate end-user OAuth login
`GET`	`/auth/:provider/callback`	Handle OAuth callback
`GET`	`/auth/admin/:provider`	Initiate admin OAuth login
`GET`	`/auth/admin/:provider/callback`	Handle admin OAuth callback

GET /auth/:provider

Initiate OAuth 2.0 authentication flow for end-users.

Synopsis

Property	Value
Authentication	Public
Rate Limit	None

Path Parameters

Parameter	Type	Description
`provider`	`string`	OAuth provider: `github`, `google`, or `microsoft`

Query Parameters

Parameter	Type	Required	Description
`org`	`string`	Yes	Organization slug
`service`	`string`	Yes	Service slug
`redirect_uri`	`string`	No	Callback URL (must be in allowed URIs)
`user_code`	`string`	No	Device flow user code
`saml_state`	`string`	No	SAML state ID for SAML SSO flows

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

Status	Condition
`404`	Organization or service not found
`400`	Invalid redirect_uri or missing required parameters

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

Property	Value
Authentication	Public
Called By	OAuth provider after authorization

Path Parameters

Parameter	Type	Description
`provider`	`string`	OAuth provider: `github`, `google`, or `microsoft`

Query Parameters

Parameter	Type	Required	Description
`code`	`string`	Yes	Authorization code from OAuth provider
`state`	`string`	No	CSRF protection state parameter

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: Tokens are passed in the URL fragment (after #) rather than query parameters to prevent them from being logged in server access logs. Client applications must parse window.location.hash to extract tokens.

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

Parameter	Type	Required	Description
`org_slug`	`string`	No	Organization slug (for org admin context)
`user_code`	`string`	No	Device flow user code

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

curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/oauth \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "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

CSRF Protection - State parameter validates callback origin
Redirect URI Validation - Only whitelisted URIs allowed
HTTPS Required - All OAuth endpoints require HTTPS
Token Storage - Provider tokens encrypted at rest
PKCE for Public Clients - Mobile and desktop services require PKCE (code_verifier/code_challenge) as they cannot securely store client secrets