Add GitHub sign-in

You'll learn how to create the GitHub OAuth App, register the SqlOS callback URL, and enable the provider from either the dashboard or code.

Goal#

Users see Continue with GitHub on the hosted AuthPage or your headless login UI. After GitHub redirects back to SqlOS, SqlOS resolves the user's GitHub profile, requires a verified primary email address, and completes the normal SqlOS login flow.

1. Create the GitHub OAuth App#

1. Open GitHub Settings > Developer settings > OAuth Apps or the same page in your GitHub organization settings.
2. Create a New OAuth App.
3. Set Application name and Homepage URL for your app.
4. Set Authorization callback URL to the SqlOS provider callback URL.

For the default SqlOS mount path, the provider callback URL is:

https://your-app.example.com/sqlos/auth/oidc/callback

For local development with the default SqlOS base path:

http://localhost:5062/sqlos/auth/oidc/callback

If you changed DashboardBasePath or AuthServer.BasePath, use:

{AuthServer.PublicOrigin}{AuthServer.BasePath}/oidc/callback

5. Register the app and copy the GitHub Client ID.
6. Generate a Client secret and store it in configuration, user secrets, or your secret manager.

2. Enable GitHub from the dashboard#

1. Open /sqlos/admin/auth/oidc in your running app.
2. Create a social provider connection:
   • Provider: GitHub
   • Display name: GitHub
   • Client ID: the GitHub OAuth App client ID
   • Client secret: the GitHub OAuth App client secret
   • Allowed callback URI: keep the prefilled SqlOS callback URL
3. Leave scopes empty unless you need to override the defaults. SqlOS requests read:user and user:email.
4. Save the connection.
5. Enable the connection.

GitHub OAuth Apps allow one authorization callback URL. Use separate GitHub OAuth Apps for local, staging, and production when those environments have different callback URLs.

3. Seed GitHub from code#

For repeatable environments, seed the GitHub connection at startup instead of creating it by hand in the dashboard:

var publicOrigin = builder.Configuration["SqlOS:PublicOrigin"]
    ?? "https://your-app.example.com";
 
builder.AddSqlOS<AppDbContext>(options =>
{
    options.AuthServer.PublicOrigin = publicOrigin;
 
    options.AuthServer.SeedGitHubConnection(
        clientId: builder.Configuration["SqlOS:Oidc:GitHub:ClientId"]!,
        clientSecret: builder.Configuration["SqlOS:Oidc:GitHub:ClientSecret"]!,
        $"{publicOrigin}/sqlos/auth/oidc/callback");
});

Store the secret outside source control:

dotnet user-secrets set "SqlOS:Oidc:GitHub:ClientId" "YOUR_GITHUB_CLIENT_ID"
dotnet user-secrets set "SqlOS:Oidc:GitHub:ClientSecret" "YOUR_GITHUB_CLIENT_SECRET"
dotnet user-secrets set "SqlOS:PublicOrigin" "https://localhost:5001"

4. Test the flow#

1. Open your app's hosted authorization URL or /sqlos/auth/login.
2. Choose Continue with GitHub.
3. Complete GitHub authorization.
4. Confirm the user returns to your app with a SqlOS session and tokens.
5. Check /sqlos/admin/auth/users and /sqlos/admin/auth/sessions to confirm the user and session were created.

Common failures#

Next steps#

• GitHub provider reference
• OIDC Social Login
• Home realm discovery
• Troubleshooting