OIDC Social Login | SqlOS Docs

SqlOS supports social login via OpenID Connect providers and GitHub OAuth. Users click a provider button, authenticate with the provider, and are linked or created in SqlOS.

Supported providers#

Provider	Key	Notes
Google	`google`	Standard OAuth 2.0
Microsoft	`microsoft`	Entra ID (Azure AD)
Apple	`apple`	Web only, requires Apple Developer account
GitHub	`github`	OAuth profile/email lookup through GitHub's user APIs
Custom	any	Any OIDC-compliant provider via discovery or manual config

Setup#

1. Create the connection#

Dashboard: Auth Server > OIDC > Create Connection

Admin API:

BASH

curl -X POST http://localhost:5062/sqlos/admin/auth/api/oidc-connections \
  -H "Content-Type: application/json" \
  -d '{
    "providerType": "google",
    "displayName": "Google",
    "clientId": "your-google-client-id",
    "clientSecret": "your-google-client-secret"
  }'

2. Configure the callback URI#

SqlOS owns the provider callback URI:

PLAINTEXT

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

Add the exact dashboard-provided URI to your provider's allowed redirect URIs.

If you build a custom headless callback with SqlOSOidcAuthService, register your app-owned callback route instead. The example API uses /api/v1/auth/oidc/callback/{connectionId} so the callback can complete the handoff before returning to the frontend.

3. Enable the connection#

BASH

curl -X POST http://localhost:5062/sqlos/admin/auth/api/oidc-connections/{id}/enable

Auth flow#

PLAINTEXT

Frontend                    Backend                     Provider
   │                          │                            │
   ├─ GET /oidc/providers ───►│                            │
   │◄── provider list ────────│                            │
   │                          │                            │
   ├─ POST /oidc/start ──────►│                            │
   │◄── authorizationUrl ─────│                            │
   │                          │                            │
   ├──── redirect to provider ────────────────────────────►│
   │◄── callback with code ────────────────────────────────│
   │                          │                            │
   │    GET /oidc/callback ──►│── exchange code ──────────►│
   │                          │◄── user info ──────────────│
   │◄── redirect with handoff │                            │
   │                          │                            │
   ├─ POST /oidc/complete ───►│                            │
   │◄── tokens ───────────────│                            │

Backend code (from the example API)#

CSHARP

// Start OIDC flow
app.MapPost("/api/v1/auth/oidc/start", async (
    OidcStartRequest request,
    SqlOSOidcAuthService oidcService,
    SqlOSHomeRealmDiscoveryService discoveryService) =>
{
    var discovery = await discoveryService.DiscoverAsync(
        new SqlOSHomeRealmDiscoveryRequest(request.Email), ct);
 
    if (discovery.Mode == "sso")
        return Results.Ok(new { mode = "sso", discovery.SsoConnectionId });
 
    var result = await oidcService.StartAuthorizationAsync(
        new SqlOSStartOidcAuthorizationRequest
        {
            ConnectionId = request.ConnectionId,
            RedirectUri = $"{origin}/api/v1/auth/oidc/callback/{request.ConnectionId}",
            State = state
        }, ipAddress, ct);
 
    return Results.Ok(new { authorizationUrl = result.AuthorizationUrl });
});

Frontend code (Next.js)#

TYPESCRIPT

const { providers } = await apiGet("/api/v1/auth/oidc/providers");
 
// User clicks a provider
const { authorizationUrl } = await apiPost("/api/v1/auth/oidc/start", {
  email,
  connectionId: provider.connectionId,
});
 
window.location.href = authorizationUrl;

Provider-specific setup#

Google#

Create an OAuth 2.0 Client ID in Google Cloud Console
Set the callback URI to http://localhost:5062/sqlos/auth/oidc/callback
Create the connection with providerType: "google", your client ID and secret

Microsoft#

Register an app in Azure Portal > App Registrations
Add the callback URI under Authentication > Web
Create the connection with providerType: "microsoft", your client ID and secret

Apple#

Register in Apple Developer Portal
Enable "Sign in with Apple" and configure the callback domain
Create the connection with providerType: "apple", your service ID and key

GitHub#

Create an OAuth App in GitHub Developer settings
Set the Authorization callback URL to the SqlOS callback URI
Create the connection with providerType: "github", your GitHub client ID and secret
Keep default scopes so SqlOS can request read:user and user:email

See GitHub OIDC for dashboard, API, and code-first setup.

Custom OIDC#

For any OIDC-compliant provider, use discovery-based or manual configuration:

BASH

# Discovery-based (auto-fetches endpoints from .well-known)
curl -X POST http://localhost:5062/sqlos/admin/auth/api/oidc-connections \
  -d '{
    "providerType": "custom",
    "displayName": "Okta",
    "clientId": "...",
    "clientSecret": "...",
    "discoveryUrl": "https://your-org.okta.com/.well-known/openid-configuration"
  }'