Skip to main content
ClassQuiz supports OAuth authentication through Google, GitHub, and custom OpenID Connect providers. This allows users to sign in using their existing accounts from these services.

​
Overview

OAuth authentication is optional and can be enabled independently for each provider. Users can still register and log in with email/password even if OAuth is not configured.
All OAuth providers are optional. You can enable one, all, or none of them based on your needs.

​
Google OAuth

Allow users to sign in with their Google accounts.

​
Configuration

​
GOOGLE_CLIENT_ID
string
Google OAuth 2.0 Client ID.Example: 123456789-abc123def456.apps.googleusercontent.com
​
GOOGLE_CLIENT_SECRET
string
Google OAuth 2.0 Client Secret.
Keep this secret secure and never commit it to version control

​
Setup Steps

1

Create Google Cloud Project

  1. Go to the Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google+ API (now part of Google Identity)
2

Configure OAuth Consent Screen

  1. Navigate to APIs & Services → OAuth consent screen
  2. Choose “External” user type (or “Internal” for Google Workspace)
  3. Fill in:
    • App name: “ClassQuiz”
    • User support email: Your email
    • Developer contact: Your email
  4. Add scopes: openid, email, profile
  5. Save and continue
3

Create OAuth Credentials

  1. Go to APIs & Services → Credentials
  2. Click “Create Credentials” → “OAuth client ID”
  3. Application type: “Web application”
  4. Name: “ClassQuiz”
  5. Authorized redirect URIs: 
    https://your-domain.com/api/v1/users/oauth/google/auth
  6. Click “Create”
  7. Copy the Client ID and Client Secret
4

Configure ClassQuiz

Add the credentials to your environment variables:
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

​
Google OAuth Scopes

ClassQuiz requests the following OAuth scopes:
  • openid - OpenID Connect authentication
  • email - User’s email address
  • profile - User’s basic profile information (name, avatar)

​
GitHub OAuth

Allow users to sign in with their GitHub accounts.

​
Configuration

​
GITHUB_CLIENT_ID
string
GitHub OAuth App Client ID.Example: Iv1.1234567890abcdef
​
GITHUB_CLIENT_SECRET
string
GitHub OAuth App Client Secret.
Keep this secret secure and never commit it to version control

​
Setup Steps

1

Create GitHub OAuth App

  1. Go to GitHub Settings → Developer settings → OAuth Apps
  2. Click “New OAuth App”
2

Configure OAuth App

Fill in the following details:
  • Application name: ClassQuiz
  • Homepage URL: https://your-domain.com
  • Authorization callback URL: https://your-domain.com/api/v1/users/oauth/github/auth
  • Application description: (optional)
Click “Register application”
3

Generate Client Secret

  1. On the OAuth App page, click “Generate a new client secret”
  2. Copy both the Client ID and Client Secret immediately
The client secret is only shown once. Save it securely!
4

Configure ClassQuiz

Add the credentials to your environment variables:
GITHUB_CLIENT_ID=Iv1.1234567890abcdef
GITHUB_CLIENT_SECRET=your-client-secret

​
GitHub OAuth Scopes

ClassQuiz requests the following OAuth scopes:
  • read:user - Read user profile information
  • user:email - Access user’s email address
ClassQuiz requires users to have a public email address on their GitHub account. Users without a public email will see an error during authentication.

​
Custom OpenID Connect Provider

Connect to any OpenID Connect (OIDC) compatible identity provider such as:
  • Keycloak
  • Auth0
  • Okta
  • Azure AD
  • Any other OIDC-compliant provider

​
Configuration

​
CUSTOM_OPENID_PROVIDER__CLIENT_ID
string
Client ID for your OpenID Connect provider.
Note the double underscore (__) in the variable name for nested configuration
​
CUSTOM_OPENID_PROVIDER__CLIENT_SECRET
string
Client secret for your OpenID Connect provider.
​
CUSTOM_OPENID_PROVIDER__SERVER_METADATA_URL
string
URL to the OpenID Connect discovery document.Format: https://your-provider.com/.well-known/openid-configurationExamples:
  • Keycloak: https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration
  • Auth0: https://your-tenant.auth0.com/.well-known/openid-configuration
  • Azure AD: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
​
CUSTOM_OPENID_PROVIDER__SCOPES
string
default:"openid email profile"
Space-separated list of OAuth scopes to request.Default: openid email profile

​
Setup Steps

1

Configure your OIDC provider

  1. Create a new OAuth/OIDC client in your identity provider
  2. Set the redirect URI to: https://your-domain.com/api/v1/users/oauth/custom/auth
  3. Note the client ID and client secret
  4. Find the OpenID discovery URL (usually ends with /.well-known/openid-configuration)
2

Configure ClassQuiz

Add the credentials to your environment variables:
CUSTOM_OPENID_PROVIDER__CLIENT_ID=your-client-id
CUSTOM_OPENID_PROVIDER__CLIENT_SECRET=your-client-secret
CUSTOM_OPENID_PROVIDER__SERVER_METADATA_URL=https://your-provider.com/.well-known/openid-configuration
CUSTOM_OPENID_PROVIDER__SCOPES="openid email profile"
3

Test authentication

Navigate to your ClassQuiz instance and try logging in with the custom provider.

​
Custom Provider Examples

CUSTOM_OPENID_PROVIDER__CLIENT_ID=classquiz-client
CUSTOM_OPENID_PROVIDER__CLIENT_SECRET=your-secret
CUSTOM_OPENID_PROVIDER__SERVER_METADATA_URL=https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration
CUSTOM_OPENID_PROVIDER__SCOPES="openid email profile"

​
Complete OAuth Configuration Example

# Google OAuth
GOOGLE_CLIENT_ID=123456789-abc123.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abc123def456

# GitHub OAuth
GITHUB_CLIENT_ID=Iv1.1234567890abcdef
GITHUB_CLIENT_SECRET=github-secret-here

# Custom OpenID
CUSTOM_OPENID_PROVIDER__CLIENT_ID=custom-client-id
CUSTOM_OPENID_PROVIDER__CLIENT_SECRET=custom-secret
CUSTOM_OPENID_PROVIDER__SERVER_METADATA_URL=https://auth.example.com/.well-known/openid-configuration
CUSTOM_OPENID_PROVIDER__SCOPES="openid email profile"

​
OAuth Redirect URLs

When configuring OAuth providers, use these redirect URLs:
ProviderRedirect URL
Googlehttps://your-domain.com/api/v1/users/oauth/google/auth
GitHubhttps://your-domain.com/api/v1/users/oauth/github/auth
Customhttps://your-domain.com/api/v1/users/oauth/custom/auth
Replace your-domain.com with your actual ROOT_ADDRESS domain. The redirect URLs must match exactly, including the protocol (https://).

​
How OAuth Authentication Works

1

User initiates login

User clicks on “Sign in with Google/GitHub/Custom” button on the login page.
2

Redirect to provider

ClassQuiz redirects the user to the OAuth provider’s authorization page.
3

User authorizes

User logs in to the OAuth provider and authorizes ClassQuiz to access their profile information.
4

Provider redirects back

OAuth provider redirects back to ClassQuiz with an authorization code.
5

Token exchange

ClassQuiz exchanges the authorization code for an access token and retrieves user information.
6

Account creation or login

  • If the user doesn’t exist, a new account is created
  • If the user exists, they are logged in
  • User is redirected to the application

​
User Account Linking

When a user signs in with OAuth:
  • A new account is created if the email doesn’t exist
  • If an account with the same email exists but uses a different auth method, registration will fail
  • Each OAuth provider creates a separate auth type (GOOGLE, GITHUB, CUSTOM)
  • Users cannot link multiple OAuth providers to the same account

​
Troubleshooting

Check that both CLIENT_ID and CLIENT_SECRET are set for the provider. ClassQuiz only displays OAuth buttons for fully configured providers.Verify configuration:
docker-compose exec api env | grep -E "GOOGLE|GITHUB|CUSTOM_OPENID"
Ensure the redirect URI configured in your OAuth provider exactly matches the format:
https://your-domain.com/api/v1/users/oauth/{provider}/auth
Common issues:
  • Missing or wrong protocol (http vs https)
  • Trailing slash
  • Wrong domain or ROOT_ADDRESS
This occurs when:
  • A user with the same email is registered with a different auth method
  • Trying to use a different OAuth provider with an email that’s already linked
Solution: Users must log in with their original authentication method.
Verify:
  • The discovery URL returns valid JSON
  • Your provider supports the required scopes
  • The CLIENT_ID and CLIENT_SECRET are correct
  • The redirect URI is registered in your provider
Test the discovery URL:
curl https://your-provider.com/.well-known/openid-configuration
GitHub users must have a public email address. To fix:
  1. Go to GitHub Settings → Emails
  2. Ensure at least one email is public
  3. Or configure your GitHub OAuth App to request private emails

​
Security Considerations

Always use HTTPS in production. OAuth providers will reject redirect URIs using plain HTTP.
  • Store OAuth secrets securely using environment variables or secrets management
  • Never commit CLIENT_SECRET values to version control
  • Regularly rotate OAuth credentials
  • Use the principle of least privilege when requesting OAuth scopes
  • Monitor OAuth login logs for suspicious activity
  • Implement rate limiting on OAuth endpoints

​
Next Steps

Email Configuration

Configure SMTP for email notifications

Environment Variables

View all configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us