Skip to main content

Social Login

Social login lets users sign in with an existing account from an external identity provider such as Google, GitHub, or Microsoft. LumoAuth handles the OAuth/OIDC handshake with the provider, creates or links a local user account, and then issues its own tokens to your application. This reduces registration friction and improves conversion.

Supported Providers​

ProviderProtocolData Returned
GoogleOAuth 2.0 / OIDCEmail, profile, avatar
GitHubOAuth 2.0Email, profile, organization membership
MicrosoftOAuth 2.0 / OIDCEmail, profile, Azure AD integration
FacebookOAuth 2.0Email, profile, friends list
AppleOAuth 2.0 / OIDCEmail (private relay), name
LinkedInOAuth 2.0Email, profile, professional info
Custom OIDCOpenID ConnectAny OIDC-compliant provider

How It Works​

  1. User clicks a social login button on your login page.
  2. Redirect to provider. LumoAuth redirects to the provider's authorization page.
  3. User authenticates at the provider.
  4. Provider callback. The provider redirects back to LumoAuth with an authorization code.
  5. Account linking. LumoAuth creates or links a local user account.
  6. Token issuance. LumoAuth issues its own OAuth tokens to your application.

Account Linking Behavior​

When a user authenticates via social login:

  • New user: a LumoAuth user account is automatically created (JIT provisioning).
  • Existing user (same email): the social account is linked to the existing user.
  • Multiple social accounts: a user can link multiple social providers to one account.

Configuration​

Organization-Level Social Login​

Configure social login providers per organization at:

/orgs/{orgId}/portal/configuration/social-login

For each provider, you will need:

  1. Client ID — from the provider's developer console.
  2. Client Secret — from the provider's developer console.
  3. Scopes — what data to request (email, profile, etc.).

Per-Application Social Login​

You can also configure social login on a per-application basis at:

/orgs/{orgId}/portal/applications/{clientId}/social-login

This lets different OAuth clients within the same organization show different social login buttons.

Setting Up Google Login​

1. Create Google OAuth Credentials​

  1. Go to the Google Cloud Console.
  2. Create a new project or select an existing one.
  3. Navigate to APIs & Services → Credentials.
  4. Click Create Credentials → OAuth client ID.
  5. Select Web application.
  6. Add the authorized redirect URI: 
    https://your-domain.com/orgs/{orgId}/auth/social/google/callback
  7. Copy the Client ID and Client Secret.

2. Configure in LumoAuth​

  1. Go to /orgs/{orgId}/portal/configuration/social-login.
  2. Click Add Provider → Google.
  3. Enter the Client ID and Client Secret.
  4. Save and Enable.

Setting Up GitHub Login​

1. Create GitHub OAuth App​

  1. Go to GitHub Developer Settings.
  2. Click New OAuth App.
  3. Set the authorization callback URL: 
    https://your-domain.com/orgs/{orgId}/auth/social/github/callback
  4. Copy the Client ID and Client Secret.

2. Configure in LumoAuth​

  1. Go to /orgs/{orgId}/portal/configuration/social-login.
  2. Click Add Provider → GitHub.
  3. Enter credentials and save.

Setting Up Microsoft Login​

1. Register in Azure AD​

  1. Go to the Azure Portal → App registrations.
  2. Click New registration.
  3. Add the redirect URI: 
    https://your-domain.com/orgs/{orgId}/auth/social/microsoft/callback
  4. Under Certificates & secrets, create a new client secret.
  5. Note the Application (client) ID and Client Secret.

2. Configure in LumoAuth​

  1. Go to /orgs/{orgId}/portal/configuration/social-login.
  2. Click Add Provider → Microsoft.
  3. Enter credentials and save.

Social Login URLs​

Each social provider has organization-specific authentication URLs:

Initiate:  /orgs/{orgId}/auth/social/{provider}
Callback:  /orgs/{orgId}/auth/social/{provider}/callback

Where {provider} is: google, github, microsoft, facebook, apple, linkedin.

User Experience​

When social login is enabled, the login page displays:

  1. Social login buttons — one button per enabled provider.
  2. Email/password form — standard credential login (if enabled).
  3. Separator — visual "or" divider between social and credential login.

Users who sign up via social login can later:

  • Set a password (for email/password login as well).
  • Link additional social accounts.
  • Remove linked social accounts (from the account settings page).

Account Settings​

Users can manage their linked social accounts at the account settings page:

/account/security

From here they can:

  • View all linked social accounts.
  • Link new social providers.
  • Unlink social providers (if they have another login method).

Just-In-Time (JIT) Provisioning​

When a user authenticates via social login for the first time, LumoAuth automatically:

  1. Creates a new user account in the organization.
  2. Populates the user profile with data from the social provider.
  3. Links the social account to the new user.
  4. Optionally assigns default roles (configurable per organization).

If a user with the same email already exists, the social account is linked to the existing user instead of creating a duplicate.

Security Considerations​

  • State parameter. LumoAuth uses the OAuth state parameter to prevent CSRF attacks.
  • PKCE. When supported by the provider, PKCE is used for additional security.
  • Token storage. Social provider tokens are encrypted in the database.
  • Scope minimization. Only request the minimum scopes needed.