Skip to main content

OAuth Integration

Enable Single Sign-On (SSO) with GitHub or Google for your Bloqd dashboard.

Supported Providers​

ProviderStatus
GitHubSupported
GoogleSupported
Custom OIDCComing soon

GitHub OAuth​

1. Create GitHub OAuth App​

  1. Go to GitHub → Settings → Developer settings → OAuth Apps
  2. Click New OAuth App
  3. Fill in the details:
    • Application name: Bloqd
    • Homepage URL: https://bloqd.example.com
    • Authorization callback URL: https://bloqd.example.com/api/v1/auth/github/callback
  4. Click Register application
  5. Copy the Client ID
  6. Generate and copy a Client Secret

2. Configure in Bloqd​

Via environment variables:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
GITHUB_CALLBACK_URL=https://bloqd.example.com/api/v1/auth/github/callback

3. Allowed Users​

By default, any GitHub user can attempt login. To restrict:

# Only allow specific users
GITHUB_ALLOWED_USERS=user1,user2,user3

# Or allow an entire organization
GITHUB_ALLOWED_ORG=your-organization

Google OAuth​

1. Create Google OAuth Credentials​

  1. Go to Google Cloud Console
  2. Create a new project (or select existing)
  3. Go to APIs & Services → Credentials
  4. Click Create Credentials → OAuth client ID
  5. Select Web application
  6. Fill in:
    • Name: Bloqd
    • Authorized redirect URIs: https://bloqd.example.com/api/v1/auth/google/callback
  7. Click Create
  8. Copy Client ID and Client Secret

2. Configure in Bloqd​

Via environment variables:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_CALLBACK_URL=https://bloqd.example.com/api/v1/auth/google/callback

3. Allowed Domains​

Restrict to specific email domains:

# Only allow your company domain
GOOGLE_ALLOWED_DOMAINS=example.com,company.com

Login Flow​

┌────────┐     ┌───────────┐     ┌──────────────┐
│  User  │────►│   Bloqd   │────►│   Provider   │
│        │     │  (Login)  │     │(GitHub/Google)│
└────────┘     └───────────┘     └──────┬───────┘
                                         │
    ┌────────────────────────────────────┘
    │ OAuth callback with token
    ▼
┌───────────┐     ┌────────────┐
│   Bloqd   │────►│  Dashboard │
│ (Verify)  │     │ (Logged in)│
└───────────┘     └────────────┘
  1. User clicks "Login with GitHub/Google"
  2. Redirected to provider for authentication
  3. User authorizes Bloqd
  4. Provider redirects back with auth code
  5. Bloqd exchanges code for user info
  6. Bloqd creates session and redirects to dashboard

User Management​

First Login​

When a user first logs in via OAuth:

  • Account is created automatically
  • Default role is assigned (configurable)
  • Admin can modify role later

Role Assignment​

Configure default role for OAuth users:

OAUTH_DEFAULT_ROLE=Viewer

Options:

  • Viewer - Read-only access
  • Operator - Can manage servers
  • Admin - Full access

Linking Existing Account​

If a user has an existing local account:

  1. Log in with local credentials
  2. Go to Profile → Linked Accounts
  3. Click Link GitHub or Link Google
  4. Authorize the connection

Security Considerations​

HTTPS Required​

OAuth requires HTTPS for callback URLs. Ensure your Bloqd instance has valid SSL.

Token Storage​

OAuth tokens are:

  • Stored encrypted in database
  • Not accessible via API
  • Automatically refreshed when needed

Session Management​

OAuth sessions:

  • Expire after configured time
  • Can be revoked by admin
  • Support "Remember me" option

Disabling Local Login​

To require OAuth for all users:

DISABLE_LOCAL_LOGIN=true
warning

Ensure at least one admin can log in via OAuth before disabling local login.

Troubleshooting​

Callback URL Mismatch​

Error: redirect_uri_mismatch
  1. Verify callback URL in provider settings
  2. Ensure it matches exactly (including https://)
  3. Check for trailing slashes

User Not Allowed​

Error: User not in allowed list
  1. Add user to GITHUB_ALLOWED_USERS or GOOGLE_ALLOWED_DOMAINS
  2. Or remove restrictions to allow all users

Invalid Client​

Error: invalid_client
  1. Verify Client ID is correct
  2. Verify Client Secret is correct
  3. Check credentials haven't been revoked

SSL Certificate Error​

Error: SSL certificate problem
  1. Ensure valid SSL certificate
  2. Check certificate chain is complete
  3. Verify callback URL uses https://

Best Practices​

  1. Use organization restrictions - Don't allow arbitrary users
  2. Set appropriate default role - Start with Viewer
  3. Require MFA - Enable MFA for OAuth accounts too
  4. Audit logins - Review login history regularly
  5. Keep secrets secure - Don't commit to version control