Social Authentication

Gate Identity supports OAuth 2.0 / OIDC social login for your end-users. You can let users register and sign in with their existing accounts from 11 major providers, with zero infrastructure to maintain.

Supported Providers

How It Works

Social auth is built on top of Ory Kratos OIDC flows. When a user clicks a social login button:

1. Your UI fetches the Kratos registration or login flow.
2. Kratos returns OIDC nodes for each provider you have enabled.
3. Your UI submits { method: "oidc", provider: "<id>", csrf_token } to the flow action URL.
4. Kratos redirects the browser to the OAuth provider (GitHub, Google, etc.).
5. After authorization, the provider redirects back to the Kratos callback URL.
6. Kratos creates or resumes the identity, runs your configured post-registration hooks, and establishes a session.

Verne's post-registration hook fires for both password and OIDC registrations, so your tenant's user record is always provisioned automatically.

Enabling Providers in the Dashboard

By default, no social providers are visible to your end-users. You control the list from Dashboard → Settings → Authentication.

Each provider appears as a card with a toggle. Turning a provider on makes it available in your end-users' login and registration UI. You can enable or disable providers at any time without redeploying anything.

Note: Verne runs a shared Kratos instance. Provider credentials (Client ID / Secret) are configured at the platform level. Your toggle controls whether the button appears in your tenant's UI — you do not need to register OAuth apps for your end-users' social login.

API: Manage Social Providers

All provider management endpoints use your Gate API key in the Authorization header — the same key you use for identity management.

Get enabled providers

GET /v1/gate/settings/oidc-providers

Returns the current configuration for all 11 providers.

Response (200 OK)

{
  "providers": [
    { "provider": "github",    "enabled": true  },
    { "provider": "google",    "enabled": true  },
    { "provider": "gitlab",    "enabled": false },
    { "provider": "microsoft", "enabled": false },
    { "provider": "discord",   "enabled": false },
    { "provider": "facebook",  "enabled": false },
    { "provider": "linkedin",  "enabled": false },
    { "provider": "apple",     "enabled": false },
    { "provider": "slack",     "enabled": false },
    { "provider": "twitch",    "enabled": false },
    { "provider": "spotify",   "enabled": false }
  ]
}

Example

curl https://api.vernesoft.com/v1/gate/settings/oidc-providers \
  -H 'Authorization: Bearer vrn_gate_live_sk_9f8a7...'

Update enabled providers

PUT /v1/gate/settings/oidc-providers

Sets the enabled flag for one or more providers. Any provider not listed in the request body is left unchanged.

Request body

{
  "providers": [
    { "provider": "github",  "enabled": true  },
    { "provider": "google",  "enabled": true  },
    { "provider": "discord", "enabled": false }
  ]
}

Response (200 OK)

Returns the full updated list in the same format as the GET response.

Example

curl -X PUT https://api.vernesoft.com/v1/gate/settings/oidc-providers \
  -H 'Authorization: Bearer vrn_gate_live_sk_9f8a7...' \
  -H 'Content-Type: application/json' \
  -d '{ "providers": [{ "provider": "github", "enabled": true }] }'

Public Endpoint: Fetch Active Providers for a Tenant

Your end-user auth UI can query which providers are currently enabled for a given tenant, without authentication.

GET /public/gate/providers/{tenant_id}

This is the endpoint you call from your login/registration page before rendering the social buttons.

Response (200 OK)

{
  "providers": ["github", "google"]
}

Example

curl https://api.vernesoft.com/public/gate/providers/ten_001

Use the returned list to decide which social login buttons to render in your UI.

Integrating Social Login in Your App

The integration has two parts: a server-side call that initializes the auth flow using your Gate API key, and a browser-side script that renders the buttons and handles the OAuth redirect.

Security: Your vrn_gate_* API key must stay on your server. The flow JSON it returns is safe to pass to the browser.

// ─── 1. Backend (Node.js / any server) ────────────────────────────────────────
// Call this from your server and return the result as JSON to your frontend.

const GATE_API = 'https://api.vernesoft.com';
const GATE_KEY = 'vrn_gate_live_sk_...'; // Dashboard → API Keys → Gate

async function createLoginFlow() {
  const res = await fetch(`${GATE_API}/v1/gate/auth/login`, {
    headers: { Authorization: `Bearer ${GATE_KEY}` },
  });
  if (!res.ok) throw new Error(`Gate error: ${res.status}`);
  return res.json(); // only enabled providers are included
}

// ─── 2. Frontend (browser) ────────────────────────────────────────────────────
// Fetch the flow from your server, then render a button per OIDC provider.

async function renderSocialButtons(containerId, flow) {
  const container = document.getElementById(containerId);
  const csrf = flow.ui.nodes.find(n => n.attributes?.name === 'csrf_token');

  flow.ui.nodes
    .filter(n => n.group === 'oidc' && n.attributes?.type === 'submit')
    .forEach(({ attributes, meta }) => {
      const btn = document.createElement('button');
      btn.textContent = meta?.label?.text ?? `Sign in with ${attributes.value}`;
      btn.onclick = async () => {
        const r = await fetch(flow.ui.action, {
          method: 'POST',
          credentials: 'include',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            method: 'oidc',
            provider: attributes.value,
            csrf_token: csrf?.attributes?.value,
          }),
        });
        const data = await r.json();
        // Kratos returns 422 with redirect_browser_to to start the OAuth round-trip
        if (data.redirect_browser_to) window.location.href = data.redirect_browser_to;
      };
      container.appendChild(btn);
    });
}

// ─── Usage ────────────────────────────────────────────────────────────────────
// Add a server route: GET /auth/flow → returns createLoginFlow() as JSON.
// Then on page load:
fetch('/auth/flow')
  .then(r => r.json())
  .then(flow => renderSocialButtons('social-login-container', flow));

The flow returned by GET /v1/gate/auth/login already contains only the providers your tenant has enabled — no client-side filtering needed.

Callback URL pattern

The Kratos OIDC callback for end-user providers is handled automatically by Verne:

https://api.vernesoft.com/auth/self-service/methods/oidc/callback/{provider}

You do not need to register your own OAuth app. Verne manages the OAuth credentials for all supported providers on behalf of all tenants.

Social Login for Verne Tenants

In addition to end-user social auth, Verne tenants can register and log in to the Verne Dashboard itself using GitHub or Google.

This uses dedicated provider IDs (github-tenant, google-tenant) separate from the end-user providers, so the same GitHub/Google account can simultaneously be both a Verne tenant and an end-user of a tenant's application without any credential conflicts.

The GitHub and Google buttons appear automatically on the registration and login pages at app.vernesoft.com when the corresponding OAuth credentials are configured at the platform level.

Traits populated via social login

When a tenant registers via GitHub or Google, Gate automatically populates: