GitHub
Implemented flow
The mock implements the OAuth 2.0 authorization code flow for OAuth Apps:
authorize a user, exchange the code for an access token, then read /user and
/user/emails for the profile and email addresses. PKCE with S256 is supported.
It does not implement GitHub Apps: app installation, installation access tokens, app JWT authentication, and GitHub App permissions are outside this flow. There are no OIDC ID tokens or discovery. Repository and organization APIs are not served.
Sources: OAuth App web flow, OAuth Apps and GitHub Apps, email API.
Using the connector
// Better Auth: pass the same options you give socialProviders.githubimport { mockGitHub } from "@mockatoo/connect-better-auth";const github = { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET! };export const auth = betterAuth({ socialProviders: process.env.NODE_ENV === "production" ? { github } : {}, plugins: process.env.NODE_ENV === "production" ? [] : [mockGitHub(github)],});// Auth.jsimport GitHub from "next-auth/providers/github";import { MockGitHub } from "@mockatoo/connect-authjs";providers: [process.env.NODE_ENV === "production" ? GitHub() : MockGitHub()],- Normal sign-in issues a non-expiring
gho_access token with no refresh token. The mock'soffline_accessextension issues expiring tokens and refresh tokens for testing refresh handling; it does not simulate a GitHub App registration. - A private email is
nullin/user. Requestuser:email(oruser) so the connector can load/user/emails; handle an unverified primary email. - The API uses
/github/api/v3so Auth.js can use its Enterprise URL option. This URL layout does not mean GitHub Enterprise features are implemented. - Custom API requests need a
User-Agent. Token errors can have HTTP 200; check the response body, and request JSON if your client expects it.
Special test addresses
Log in as you+<tag>@example.com with your own account's password to get a distinct, stable test user. Tags combine with dots, such as you+hd.unverified@example.com. Any other tag, such as you+1@example.com, is just another user; see Email tags.
| Tag | Behavior | |
|---|---|---|
unverified | email_verified: false (GitHub: primary email verified: false; Discord: verified: false; LinkedIn: "false" in the ID token) | Example |
renamed | Same user ID (sub, Microsoft oid, GitHub, Discord, X and Facebook id) as the address without +renamed, different email | Example |
noname | No name (Google: also no given_name/family_name; GitHub: name: null; Discord: global_name: null) | Example |
private | Private email: /user has email: null, so the app must read /user/emails | Example |
revoked | Sign-in works; every refresh returns invalid_grant (GitHub: bad_refresh_token, and only with offline_access; X: invalid_request) | Example |
badcode | The code exchange fails (invalid_grant; GitHub: bad_verification_code; LinkedIn and X: invalid_request; Facebook: Invalid verification code format.) | Example |
down | The token endpoint returns 503 | Example |
flaky | The first exchange of each code returns 503; a retry succeeds | Example |
slow | Token responses are delayed (10 seconds) | Example |
Known differences
This provider
| Difference | Effect |
|---|---|
Better Auth hardcodes github.com, so mockGitHub() contains a copy of Better Auth's token request and profile lookup with the URLs changed. | Hides changes in a newer Better Auth until the copy is updated. |
The API is served at GitHub Enterprise's path, /github/api/v3/user, not at api.github.com/user. | Breaks code that builds api.github.com URLs itself. |
OAuth App sign-in is modeled; GitHub App installation, permissions, app JWTs and installation tokens are not. Normal gho_ tokens do not expire. The mock-only offline_access extension issues expiring tokens and refresh tokens without a GitHub App registration. | Cannot validate a GitHub App integration; offline_access only exercises refresh handling. |
Shared mock limits
| Difference | Effect |
|---|---|
| ID tokens are issued to the shared mock client. Native bundle IDs and native client registrations are not modeled. | Hides a native audience setting that does not match your production registration. |
Refresh tokens do not expire from age or inactivity, even when a response advertises refresh_token_expires_in. Rotation and revocation still apply where supported; +revoked forces refresh failure. | Hides failures after long periods without sign-in. Use +revoked to exercise expired or revoked grant handling. |
Any http/https callback URL is accepted, including localhost. Apple refuses http and localhost, and Microsoft refuses http except for localhost, whatever the app registered. | Hides a callback URL the real provider refuses outright. |
Everyone uses one shared client (mockatoo / mockatoo-secret). The connectors replace your production client ID and secret, Apple's signed client secret, and Microsoft's client assertion. | Hides wrong production credentials or a broken client-secret setup. |
The login form and the consent screen appear on every sign-in; there is no remembered session. prompt=none fails for Google (interaction_required) and Microsoft (login_required), and Discord and LinkedIn, which skip consent for a returning user (LinkedIn even with prompt=consent), always ask again. | Breaks silent sign-in that works with a real signed-in user. |
Issuers and signing keys are the mock's (for example https://app.mockatoo.globalunderdog.com/google, not https://accounts.google.com). Discord's authorization responses carry iss=https://app.mockatoo.globalunderdog.com/discord, not https://discord.com. | Breaks code that hardcodes a real issuer or key URL. |
Tokens are only valid at the mock. Real provider APIs (Google APIs, Microsoft Graph, GitHub's api.github.com, Discord's discord.com/api, LinkedIn's api.linkedin.com, X's api.x.com, Facebook's graph.facebook.com) reject them, and the mock doesn't serve those APIs beyond what sign-in needs. | Breaks app features that call the provider's API after sign-in. |
A special address (you+tag@…) is a different test user with the same password. Apps that strip +tags from emails will merge them into one user. | Breaks special addresses in such apps. |