GitHub Sign-In

​

Prerequisites

1. Have a GitHub account
2. Register a new OAuth application on GitHub
3. Obtain OAuth credentials (Client ID and Client Secret)
4. Configure authorization callback URLs

​

GitHub OAuth App Setup

1. Create an OAuth App
   • Go to GitHub Developer Settings
   • Click “OAuth Apps” in the left sidebar
   • Click “New OAuth App”
2. Configure Application Details
   • Application name: Enter your application’s name
   • Homepage URL:
     • For local development: http://localhost:3000
     • For production: https://yourdomain.com
   • Application description: (Optional) Describe your application
   • Authorization callback URL: This is critical for OAuth to work
     • For local development: http://localhost:3000/api/_internal/auth/github/callback
     • For production: https://yourdomain.com/api/_internal/auth/github/callback
3. Register Application
   • Click “Register application”
4. Generate Client Secret
   • After registration, you’ll see your Client ID
   • Click “Generate a new client secret”
   • Copy and save the Client Secret immediately (it won’t be shown again)
5. Save Credentials
   • Store your Client ID and Client Secret securely
   • Use environment variables or Modelence Cloud config
   • Never commit these credentials to version control

​

Server-Side Configuration

​

Option 1: Modelence Cloud (Recommended)

1. Go to https://cloud.modelence.com/
2. Navigate to your project
3. Go to Authentication → Providers → GitHub
4. Enable GitHub authentication
5. Enter your Client ID and Client Secret from GitHub
6. Save the configuration

​

Option 2: Environment Variables

MODELENCE_AUTH_GITHUB_ENABLED=true
MODELENCE_AUTH_GITHUB_CLIENT_ID=your-github-client-id
MODELENCE_AUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
MODELENCE_AUTH_GITHUB_CLIENT_SCOPES=user:email,read:user

• MODELENCE_AUTH_GITHUB_CLIENT_SCOPES: Comma-separated list of OAuth scopes to request from GitHub. Defaults to user:email if not specified.

​

Client-Side Implementation

function handleGitHubSignIn() {
  // Redirect to GitHub OAuth flow
  window.location.href = '/api/_internal/auth/github';
}

​

UI Integration

function LoginForm() {
  return (
    <div>
      <h2>Sign In</h2>
      <button onClick={() => window.location.href = '/api/_internal/auth/github'}>
        Sign in with GitHub
      </button>
    </div>
  );
}

​

How GitHub Sign-In Works

1. Initiation - User clicks “Sign in with GitHub” button
2. Redirect - User is redirected to GitHub’s OAuth authorization page
3. Authorization - User grants permission to your app
4. Callback - GitHub redirects back to your app with an authorization code
5. Token Exchange - Your server exchanges the code for an access token and user information
6. User Creation/Login - If user doesn’t exist, a new account is created; otherwise, user is logged in
7. Session Creation - A session is established and the user is authenticated

​

User Data Handling

• Creates a user account if one doesn’t exist
• Links the GitHub account to the user profile
• Retrieves profile information (username, email, avatar, name)
• Marks the email as verified if GitHub has verified it

{
  email: string;           // GitHub account email
  handle: string;          // Generated from GitHub username or email
  emailVerified: boolean;  // true if GitHub email is verified
  githubId: string;        // GitHub user ID
  name?: string;           // Full name from GitHub profile
  picture?: string;        // Avatar URL from GitHub
}

​

Requesting Additional Scopes

​

Configuring Scopes

# Request multiple scopes (comma-separated)
MODELENCE_AUTH_GITHUB_CLIENT_SCOPES=user:email,read:user,repo

1. Go to cloud.modelence.com
2. Navigate to Authentication → Providers → GitHub
3. Add the desired scopes in the scopes configuration field

​

Common GitHub Scopes

• user:email - Access to user’s email addresses (default, required for authentication)
• read:user - Read access to user profile data
• user - Full access to user profile data (includes read and write)
• repo - Access to public and private repositories
• public_repo - Access to public repositories only
• gist - Access to gists
• read:org - Read-only access to organization membership

​

Combining with Email/Password Authentication

import { loginWithPassword, logout } from 'modelence/client';
import { useState } from 'react';

function LoginOptions() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  return (
    <div>
      <h2>Sign In</h2>

      {/* GitHub Sign-In */}
      <button onClick={() => window.location.href = '/api/_internal/auth/github'}>
        Sign in with GitHub
      </button>

      <div>or</div>

      {/* Email/Password Sign-In */}
      <form onSubmit={async (e) => {
        e.preventDefault();
        await loginWithPassword({ email, password });
      }}>
        <input
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          placeholder="Email"
        />
        <input
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          placeholder="Password"
        />
        <button type="submit">Sign In</button>
      </form>
    </div>
  );
}

​

Troubleshooting

• Ensure the callback URL in your GitHub OAuth App settings exactly matches your application URL
• Check for trailing slashes and http vs https
• Common format: https://yourdomain.com/api/_internal/auth/github/callback
• You can only register one callback URL per OAuth App

• Check your GitHub app settings to ensure it hasn’t been suspended
• Verify your account is in good standing

• Verify your Client ID and Client Secret are correct
• Check that environment variables are properly loaded
• Ensure you copied the Client Secret correctly (it’s only shown once)
• Make sure credentials are from the correct GitHub OAuth App

• Some GitHub users have private email addresses
• Users must have at least one public email or primary email set
• You may need to handle cases where email is not provided
• Consider prompting users to provide an email if not available from GitHub

• GitHub enforces rate limits on OAuth endpoints
• If developing locally, avoid making too many authentication requests in quick succession
• Production apps typically don’t hit these limits under normal usage