Howto GitHub OIDC

How to set up GitHub OAuth

GitHub does not expose a native OIDC discovery endpoint, so Bindery uses Dex as a standards-compliant OIDC bridge. This guide wires GitHub → Dex → Bindery.

What you'll have at the end: a "Sign in with GitHub" button on the Bindery login page. Dex handles the GitHub OAuth dance; Bindery sees a standard OIDC token with a stable numeric sub (GitHub user ID — survives username changes).

Prerequisites:

• Dex v2.37+ running and reachable from Bindery and from users' browsers
• Bindery v0.24.0+
• A GitHub account to register an OAuth App

---

Steps

1. Register a GitHub OAuth App

1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.
2. Fill in:
   • Application name: Bindery
   • Homepage URL: https://bindery.example.com
   • Authorization callback URL: https://dex.example.com/callback
3. Click Register application. Copy the Client ID.
4. Click Generate a new client secret. Copy the secret immediately — it's shown once.

Expected result: App appears in your OAuth Apps list with a Client ID like Iv1.abc123.

2. Configure Dex with the GitHub connector

# dex/config.yaml
issuer: https://dex.example.com

storage:
  type: sqlite3
  config:
    file: /var/dex/dex.db

web:
  http: 0.0.0.0:5556

connectors:
  - type: github
    id: github
    name: GitHub
    config:
      clientID: <github-oauth-app-client-id>
      clientSecret: <github-oauth-app-client-secret>
      redirectURI: https://dex.example.com/callback
      # Optional: restrict to org members
      orgs:
        - name: your-github-org

staticClients:
  - id: bindery
    secret: <dex-client-secret>       # generate: openssl rand -hex 32
    name: Bindery
    redirectURIs:
      - https://bindery.example.com/api/v1/auth/oidc/github/callback

Restart Dex after saving. Confirm it's healthy:

curl -s https://dex.example.com/.well-known/openid-configuration | jq .issuer
# Expected: "https://dex.example.com"

3. Set the redirect base URL in Bindery

environment:
  BINDERY_OIDC_REDIRECT_BASE_URL: "https://bindery.example.com"

Restart Bindery if adding for the first time.

4. Add the Dex provider in Bindery

Settings → Security → OIDC Providers → Add provider, or:

curl -X POST http://bindery:8787/api/v1/settings/auth/oidc/providers \
  -H "X-Api-Key: <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "github",
    "name": "GitHub",
    "issuer": "https://dex.example.com",
    "client_id": "bindery",
    "client_secret": "<dex-client-secret>",
    "scopes": "openid email profile"
  }'

Note: client_id and client_secret here are the Dex static client credentials, not the GitHub OAuth App credentials. The GitHub credentials live only in Dex's config.

Expected result: provider saved, Sign in with GitHub button appears on the login page.

5. Test the login flow end-to-end

1. Open a private window → https://bindery.example.com/login → click Sign in with GitHub.
2. Browser goes to Dex (dex.example.com) → Dex redirects to GitHub → you authorize → GitHub sends code to Dex → Dex exchanges it → Dex issues an ID token to Bindery.
3. Bindery maps the user by (https://dex.example.com, <dex-sub>). Dex's sub for GitHub users is the numeric GitHub user ID — stable even if the GitHub username changes.
4. Bindery provisions the user account and logs you in. Check Settings → Users to confirm.

---

Restricting to a GitHub org or team

In the Dex config, the orgs block limits logins to members of the specified org. To further restrict to a specific team:

orgs:
  - name: your-github-org
    teams:
      - bindery-users

Users outside the org/team get a Dex error before Bindery is reached.

---

When this goes wrong

Symptom	Cause	Fix
Dex discovery URL returns 404	Dex not running or wrong URL	curl https://dex.example.com/.well-known/openid-configuration — should return JSON
redirect_uri_mismatch from GitHub	GitHub OAuth App callback URL doesn't match Dex	Must be exactly https://dex.example.com/callback — update in GitHub OAuth App settings
redirect_uri_mismatch from Dex	Dex staticClients.redirectURIs doesn't match Bindery callback	Must be https://bindery.example.com/api/v1/auth/oidc/github/callback
connector not found error in Dex logs	Dex config missing or not reloaded	Restart Dex after editing config.yaml
User can log in but gets a different Bindery account after a GitHub username change	Using preferred_username (mutable) as identity	Dex uses the numeric GitHub user ID as sub — this should not happen. If it does, check whether you've overridden the claims mapping in Dex
Org restriction not working — non-members can log in	orgs block missing or Dex not reloaded	Confirm the orgs block in Dex config and restart Dex

See also: Troubleshooting — OIDC | docs/auth-oidc.md