Skip to main content

Integrations (email + social login)

Configure email + social-login providers from the admin console — paste your keys at /admin/integrations, no redeploy. Keys are encrypted at rest in your own database; nothing is sent to us. Social login covers Google, GitHub, Microsoft, Apple, and Meta (Facebook); enable only the ones your users need and toggle the rest off. Google and GitHub additionally have an env-var fallback so existing deployments keep working unchanged.

Prerequisites​

To store secrets from the dashboard, set a master key on the server:

IDENTSPHERE_CONFIG_KEY="$(openssl rand -base64 32)"   # 32 bytes, base64 or hex

See Secrets & encryption for how this protects your keys and how to rotate it. Without it, the Integrations page shows a banner and providers fall back to env vars.

Resend (email)​

  1. In Resend → API Keys, create a key (re_…), and verify your sending domain.
  2. /admin/integrations → Resend: set the From address (on your verified domain), paste the API key, toggle Enabled, Save, then Test connection.
  3. Done — verification, password-reset, and invite emails now send via Resend.

Env fallback: the default server ships SMTP/log-only; Resend via the dashboard is the supported runtime path.

Google sign-in​

  1. Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID (Web application).
  2. Authorized redirect URI: https://YOUR_HOST/v1/auth/oauth/google/callback (YOUR_HOST = your IDENTSPHERE_PUBLIC_BASE_URL).
  3. Copy the Client ID + Client secret.
  4. /admin/integrations → Google sign-in: paste both, Enabled, Save. The "Sign in with Google" button works immediately.

Env fallback: IDENTSPHERE_OAUTH_GOOGLE_CLIENT_ID + IDENTSPHERE_OAUTH_GOOGLE_CLIENT_SECRET.

GitHub sign-in​

  1. GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.
  2. Authorization callback URL: https://YOUR_HOST/v1/auth/oauth/github/callback.
  3. Copy the Client ID + generate a Client secret.
  4. /admin/integrations → GitHub sign-in: paste both, Enabled, Save.

Env fallback: IDENTSPHERE_OAUTH_GITHUB_CLIENT_ID + IDENTSPHERE_OAUTH_GITHUB_CLIENT_SECRET.

Microsoft sign-in (Entra ID)​

  1. Entra admin center → App registrations → New registration.
  2. Add a Web redirect URI: https://YOUR_HOST/v1/auth/oauth/microsoft/callback.
  3. Copy the Application (client) ID; under Certificates & secrets, create a client secret.
  4. /admin/integrations → Microsoft sign-in: paste the client ID + secret. Optionally set a Tenant (defaults to common = work/school and personal accounts; use organizations, consumers, or a tenant GUID to restrict). Enabled, Save.

Dashboard-managed (no env fallback).

Apple sign-in​

Apple has no static secret — you provide a signing key and the server mints the short-lived secret for you.

  1. Apple Developer → Certificates, Identifiers & Profiles:
    • Create a Services ID (this is your client_id, e.g. com.yourcompany.web) and enable Sign in with Apple on it.
    • Add the return URL https://YOUR_HOST/v1/auth/oauth/apple/callback.
    • Create a Sign in with Apple key, download the .p8 (shown once), and note its Key ID. Note your Team ID (top-right of the portal).
  2. /admin/integrations → Apple sign-in: paste the Services ID, Team ID, Key ID, and the whole .p8 into the key box. Enabled, Save.
  3. Click Test — it mints the client secret from your key, so a wrong .p8 or id is caught right away.

Dashboard-managed (no env fallback).

Facebook sign-in (Meta)​

  1. Meta for Developers → your app → Facebook Login → Settings.
  2. Add the Valid OAuth Redirect URI: https://YOUR_HOST/v1/auth/oauth/meta/callback.
  3. From Settings → Basic, copy the App ID + App Secret.
  4. Make sure your app requests the email permission (sign-in needs it).
  5. /admin/integrations → Facebook sign-in: paste the App ID + secret. Enabled, Save.

Dashboard-managed (no env fallback).

How it resolves​

A provider configured (and enabled) in the dashboard wins; otherwise the server falls back to the env vars. Changes apply within ~30s across replicas (or immediately on the node that saved). If a stored secret can't be decrypted (e.g. the master key was rotated away), the provider shows degraded and the server falls back to env rather than failing — fix it by re-saving the secret.

Security notes​

  • Saving or testing a provider requires a recent MFA step-up (changing credentials is sensitive). Enroll TOTP on your admin account first.
  • The dashboard never displays stored secrets — only whether one is set.
  • Secrets are AES-256-GCM encrypted, bound to their provider, and never logged.