AuthBridge

AuthBridge is a framework-agnostic social login UI kit for building provider-based sign-in flows across React, Vue, Angular, and vanilla JavaScript.

It gives you:

• a normalized provider catalog
• a headless layout model
• configurable icons, labels, classes, and data-* attributes
• optional HTML rendering helpers
• an auth demo server for real OAuth testing
• detailed provider setup guides in docs/

Install

From npm:

npm install @eonui/authbridge

From the repo:

cd AuthBridge
npm install

Build

npm run typecheck
npm run build

Lowest-boilerplate start

If you just want working buttons with /auth/<provider>/start links, use createAuthBridge(...).

import { createAuthBridge } from "@eonui/authbridge";

const auth = createAuthBridge({
  title: "Sign in",
  providers: ["google", "github", "linkedin"],
  authBasePath: "/auth"
});

document.body.innerHTML = `
  <style>${auth.css}</style>
  ${auth.html}
`;

That single helper gives you:

• auth.config
• auth.model
• auth.providers
• auth.rows
• auth.html
• auth.css

So you can start simple and only drop down to the lower-level model when you actually need custom rendering.

What you can configure from outside

AuthBridge is meant to be owned by the app layer, not hard-coded inside the library.

You can configure:

• providers Choose, reorder, hide, or feature providers.
• iconResolver Replace built-in icons without editing src/icons.ts.
• providerTransform Override href, label, buttonLabel, loadingLabel, iconHtml, className, and custom attributes per provider.
• texts Use global templates like Continue with {provider} or resolver functions.
• iconMode auto, icon, monogram, or none.
• iconPosition start or end.
• rootClassName, headerClassName, bodyClassName Attach your own wrapper classes.
• rowClassName, providerClassName Static classes or resolver functions.
• rootAttributes, providerAttributes Add analytics hooks, test selectors, or other external metadata.

Quick start

import {
  createAuthBridge,
  getProviderIconHtml
} from "@eonui/authbridge";

const auth = createAuthBridge({
  title: "Continue to your workspace",
  subtitle: "Use the identity your users already trust.",
  orientation: "featured",
  primaryProvider: "google",
  providers: ["google", "github", "linkedin", "discord"],
  authBasePath: "/auth",
  iconMode: "icon",
  texts: {
    buttonLabel: "Continue with {provider}",
    loadingLabel: "Opening {provider}...",
    ariaLabel: "Sign in with {provider}"
  },
  iconResolver: (provider) => getProviderIconHtml(provider.id),
  providerTransform: (provider) =>
    provider.id === "linkedin"
      ? {
          href: "/auth/linkedin/start",
          buttonLabel: "Use LinkedIn profile",
          attributes: {
            "data-provider-kind": "professional"
          }
        }
      : undefined,
  providerAttributes: (provider) => ({
    "data-provider-id": provider.id,
    "data-provider-status": provider.status
  })
});

console.log(auth.rows);

Plain HTML rendering

import {
  createAuthBridge
} from "@eonui/authbridge";

const auth = createAuthBridge({
  title: "Sign in",
  orientation: "grid",
  providers: ["google", "apple", "github", "microsoft"],
  authBasePath: "/auth",
  iconMode: "icon",
  texts: {
    buttonLabel: "Continue with {provider}"
  }
});

document.body.innerHTML = `
  <style>${auth.css}</style>
  ${auth.html}
`;

Helper shortcuts

If you want the API in smaller pieces instead of the full createAuthBridge(...) object:

• createAuthBridgeConfig(...) builds a default config with auto-generated auth links
• createAuthBridgeProviders(...) turns ["google", "github"] into provider inputs with hrefs
• buildAuthRoute("google", "/auth") returns /auth/google/start
• renderAuthBridgeHtml(...) renders HTML directly from the easy options object

Example:

import {
  buildAuthRoute,
  createAuthBridgeProviders
} from "@eonui/authbridge";

const providers = createAuthBridgeProviders(["google", "github"], {
  authBasePath: "/auth"
});

console.log(providers);
console.log(buildAuthRoute("google", "/auth"));

Framework examples

The repo includes concrete examples showing the same outside-driven configuration pattern in each framework.

React

File:

• examples/react/SocialLoginDemo.tsx

Highlights:

• renders the headless model in JSX
• swaps icons with iconResolver
• overrides provider-specific copy with providerTransform

Vue

File:

• examples/vue/SocialLoginDemo.vue

Highlights:

• builds the model in setup()
• renders icon HTML with v-html
• keeps provider labels and links outside the kit

Angular

File:

• examples/angular/social-login-demo.component.ts

Highlights:

• uses createAuthBridge(...) in a standalone component
• sanitizes icon HTML with DomSanitizer
• keeps provider hrefs and button copy externally configured

Vanilla JavaScript

Files:

• examples/vanilla/index.html
• examples/vanilla/main.js

Highlights:

• uses renderSocialLoginHtml(...)
• injects custom CSS plus the generated HTML
• adds button behavior after render

More notes are in examples/README.md.

Supported orientations

• stack
• inline
• grid
• featured
• compact

How real social login works

AuthBridge renders the provider UI. Your backend should own the actual OAuth flow.

Typical flow:

1. Render a button with href: "/auth/google/start".
2. The user clicks the button.
3. Your server redirects them to the provider authorize URL.
4. The provider redirects back to /auth/<provider>/callback.
5. Your server exchanges the code for tokens and creates your app session.

Do not put secrets in frontend code. Keep token exchange and client secrets server-side.

Where credentials go

Put provider keys in .env.local, not in src/providers.ts.

Use:

• env template: .env.example
• provider registry example: examples/server/oauth-config.example.ts
• route example: examples/server/oauth-routes.example.ts
• detailed wiring guide: docs/oauth-wiring.md

.env.local is intentionally ignored and is not copied into this repo.

Provider setup quick reference

Use one callback pattern everywhere:

• local: http://127.0.0.1:3000/auth/<provider>/callback
• secure local when required: https://social-login-kit.127.0.0.1.sslip.io:3443/auth/<provider>/callback
• production: https://your-domain.com/auth/<provider>/callback

| Provider | Where to create the app | Typical env vars | Default scopes | | --- | --- | --- | --- | | Google | Google Cloud Console | GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI | openid email profile | | Apple | Apple Developer | APPLE_SERVICES_ID, APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY, APPLE_REDIRECT_URI | name email | | Microsoft | Microsoft Entra admin center | MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_ID, MICROSOFT_REDIRECT_URI | openid profile email User.Read | | GitHub | GitHub Developer Settings | GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_REDIRECT_URI | read:user user:email | | LinkedIn | LinkedIn Developer Portal | LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET, LINKEDIN_REDIRECT_URI | openid profile email | | Discord | Discord Developer Portal | DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, DISCORD_REDIRECT_URI | identify email | | Slack | Slack API Apps | SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_REDIRECT_URI | openid email profile | | Facebook | Meta for Developers | FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, FACEBOOK_REDIRECT_URI | public_profile email | | X | X Developer Console | X_CLIENT_ID, X_CLIENT_SECRET, X_REDIRECT_URI, X_AUTH_MODE | tweet.read users.read offline.access | | TikTok | TikTok for Developers | TIKTOK_CLIENT_KEY, TIKTOK_CLIENT_SECRET, TIKTOK_REDIRECT_URI | user.info.basic | | Patreon | Patreon Clients & API Keys | PATREON_CLIENT_ID, PATREON_CLIENT_SECRET, PATREON_REDIRECT_URI | identity identity[email] | | Twitch | Twitch Developer Console | TWITCH_CLIENT_ID, TWITCH_CLIENT_SECRET, TWITCH_REDIRECT_URI | user:read:email | | Spotify | Spotify Developer Dashboard | SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, SPOTIFY_REDIRECT_URI | user-read-email user-read-private | | Reddit | Reddit apps page | REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDDIT_REDIRECT_URI | identity | | Instagram | Meta for Developers | INSTAGRAM_APP_ID, INSTAGRAM_APP_SECRET, INSTAGRAM_REDIRECT_URI | varies by product |

Provider-specific notes

Google

• Create a project in Google Cloud Console.
• Configure the OAuth consent screen first.
• Create an OAuth client ID for Web application.
• Register: http://127.0.0.1:3000/auth/google/callback
• If you request more than openid email profile, Google may require test users or app verification.

Apple

• Apple web auth uses a Services ID, not just a bundle ID.
• You also need a signed client-secret JWT generated from the .p8 private key.
• Apple web callbacks require an HTTPS domain for real usage.

Microsoft

• Create the app in Entra ID -> App registrations.
• If you want both work and personal accounts, use MICROSOFT_TENANT_ID=common.
• Add a Web redirect URI matching your callback exactly.

GitHub

• Use OAuth Apps for login-only flows.
• Register the callback URL exactly.
• Use minimal scopes like read:user user:email.

LinkedIn

• Enable Sign In with LinkedIn using OpenID Connect in the app Products tab.
• Use openid profile email.
• The legacy Sign In with LinkedIn flow is not the right choice for new builds.

Discord

• Add the redirect URL under OAuth2.
• Application ID is your Client ID.
• The Public Key is not the OAuth client secret.

Facebook

• Add the Facebook Login product to the Meta app.
• Save the callback both in App authentication and Facebook Login -> Settings.
• For local testing, Facebook is much happier with a secure HTTPS origin than plain HTTP.

X

• Use console.x.com.
• Make sure the callback is exactly: http://127.0.0.1:3000/auth/x/callback
• Use the OAuth 2.0 Client ID and Client Secret, not the API key, for the current demo flow.

Instagram and Truth Social

• Instagram is included in the catalog but is not recommended as a mainstream consumer login provider.
• Truth Social is treated as unsupported for real OAuth login until it publishes a public auth product.

Full provider setup docs

Use these when you want the detailed, provider-by-provider checklist:

• docs/provider-credentials.md
• docs/oauth-wiring.md

Run the auth demo

After filling the providers you want in .env.local:

npm run auth:demo

The demo:

• renders real provider buttons
• starts OAuth from local routes like /auth/google/start
• exchanges codes server-side
• shows returned scopes, claims, and provider API payloads

Currently wired in the demo:

• Google
• Microsoft
• GitHub
• LinkedIn
• Discord
• Facebook
• X
• Apple

Local HTTPS support

Some providers reject plain HTTP localhost flows. AuthBridge supports an optional second HTTPS listener.

Set:

HTTPS_BASE_URL=https://social-login-kit.127.0.0.1.sslip.io:3443
HTTPS_CERT_PFX_PATH=.certs/social-login-kit-local.pfx
HTTPS_CERT_PFX_PASSPHRASE=change-me

Then point provider-specific redirect URIs such as FACEBOOK_REDIRECT_URI to that HTTPS origin.

Repo structure

• src/ Headless model, icons, providers, and render helpers
• docs/ Provider credential and wiring guides
• examples/ React, Vue, Angular, vanilla, and server wiring examples
• scripts/ Preview generation and auth demo server
• preview/ Generated preview HTML