GitHub Login Configuration Flow

The previous article covered the general OAuth login flow. In this article, we configure GitHub login end to end.

GitHub login is especially useful for SaaS products built for developers, indie makers, open-source users, and technical teams. It lowers sign-up friction and gives you a stronger developer identity signal.

However, GitHub OAuth integration has several details you must handle well: OAuth App creation, callback URL, Client Secret, scope, state, email retrieval, and account linking.

This article follows GitHub's official OAuth App documentation:

• Creating an OAuth app
• Authorizing OAuth apps

Step 1: Create a GitHub OAuth App

After logging in to GitHub, open your profile menu in the upper-right corner and click Settings.

In the left sidebar, open Developer settings, choose OAuth apps, then click New OAuth App. If you have not created an app before, the button may say Register a new application.

You need to fill in:

Application name: Your product name
Homepage URL: Your product homepage
Application description: Optional user-facing description
Authorization callback URL: Your OAuth callback URL

This information can be shown to users during authorization, so do not use internal test names, sensitive paths, or anything you do not want public.

Step 2: Configure the Callback URL

The callback URL is where GitHub sends the user after authorization.

Examples:

Development: http://localhost:3000/api/auth/callback/github
Production: https://example.com/api/auth/callback/github

GitHub's docs note that OAuth Apps cannot have multiple callback URLs, unlike GitHub Apps. Plan your environments carefully.

There are two common approaches.

First, create separate OAuth Apps for different environments, such as one for development and one for production. This is the clearest and safest approach.

Second, use one domain and routing logic to handle environments. This adds complexity and is not recommended early.

For indie developers, separate OAuth Apps for development and production are usually best.

Step 3: Save Client ID and Client Secret

After creation, GitHub gives you a Client ID, and you can generate a Client Secret.

They are used differently:

Client ID: Used to build the authorization URL
Client Secret: Server-side only, used to exchange code for token

Do not put Client Secret in frontend code, public repositories, or shared documents. Store it in server-side environment variables.

Example:

GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx
GITHUB_CALLBACK_URL=https://example.com/api/auth/callback/github

If the secret leaks, regenerate it immediately in GitHub settings.

Step 4: Build the GitHub Authorization URL

When users click “Login with GitHub,” redirect them to GitHub's authorization endpoint:

https://github.com/login/oauth/authorize

Common parameters:

client_id: Client ID from the OAuth App
redirect_uri: Your callback URL
scope: Requested permissions
state: Random string to prevent forged requests

Example:

https://github.com/login/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://example.com/api/auth/callback/github
  &scope=read:user user:email
  &state=RANDOM_STATE

Save state when starting the login flow, then verify it on callback.

Step 5: Request Minimal Scopes

If you only need GitHub login, you usually need basic user information and email.

Common scopes:

read:user: Read basic user profile
user:email: Read user email addresses

Do not request sensitive scopes such as repo at the beginning. Too many permissions make users hesitate and increase security risk.

Scopes should match product functionality. Ask only for what login needs.

Step 6: Handle the GitHub Callback

After the user authorizes, GitHub redirects to your callback URL with code and state.

Example:

https://example.com/api/auth/callback/github?code=xxx&state=yyy

Your server should verify state first. If state does not match, reject the request.

After state passes, exchange code for an access token:

POST https://github.com/login/oauth/access_token

Parameters usually include:

client_id
client_secret
code
redirect_uri

Set Accept: application/json so GitHub returns JSON that is easier to parse.

Step 7: Fetch GitHub User Information

After receiving the access token, request the GitHub user API:

GET https://api.github.com/user
Authorization: Bearer ACCESS_TOKEN

This returns GitHub user ID, username, avatar, profile URL, and more.

If you need email, request:

GET https://api.github.com/user/emails
Authorization: Bearer ACCESS_TOKEN

The email in the basic profile may be empty, especially when the user hides their email. A safer approach is to request the email list and choose the primary verified email.

Step 8: Link the Local User

Do not use GitHub username or email as the only local unique identifier.

A safer binding uses GitHub's provider user ID:

user_id
provider = github
provider_user_id = GitHub user id
provider_login = GitHub username
provider_email = primary verified email

If provider_user_id already exists, sign in that user. If not, create a new user or ask the user to link an existing account based on your business rules.

The same email does not always mean accounts should be merged automatically. Be careful when combining OAuth with email-password login.

Step 9: Create Your Own Session

The GitHub token is a credential for GitHub APIs. It should not be your product's login state.

After GitHub login succeeds, create your own session or cookie, then redirect the user back to the product.

If you only use GitHub for login, you may not need to store the access token long term.

If you later need to read repositories, organizations, or other GitHub data, store the token only when needed and handle encryption, expiration, and revocation.

Step 10: Common Error Checklist

When GitHub login fails, check:

Does callback URL match GitHub settings?
Are development and production using different OAuth Apps?
Is Client Secret used only on the server?
Is state saved and verified correctly?
Is scope enough to fetch email?
Do you handle empty email?
Do you bind by provider_user_id?
Do you create a local session?

Most GitHub login issues come from callback URL, environment variables, or email handling.

Final Thoughts

GitHub login is not difficult, but it connects third-party authorization with your own user system. Do not only check whether the redirect works.

A reliable GitHub login flow should include environment separation, secret safety, state verification, minimum scope, email fallback, provider ID binding, and local session creation.

Next, we continue with another common login method: Google Login Configuration.