Social Login

Social login enables users to authenticate with their existing Google, Microsoft, GitHub, or other OAuth/OIDC provider accounts.

Supported Providers

Google

OpenID Connect. Supports personal and Workspace accounts.

Microsoft

Entra ID (formerly Azure AD). Multi-tenant, organization, and consumer accounts.

GitHub

OAuth 2.0. Includes GitHub Enterprise Server support.

Apple / Facebook / LinkedIn

Built-in templates are available for additional common providers.

Custom

Any OIDC or OAuth 2.0 compliant provider.

Why Use Social Login?

Better User Experience

• One-click login with existing accounts
• No passwords to remember
• Reduced registration friction

Enhanced Security

• Leverage enterprise-grade authentication infrastructure
• Delegate MFA/2FA to external IdPs
• Reduce password management burden

JIT Provisioning

• Automatic user creation on first login
• Email-based account linking
• Profile synchronization via attribute mapping

Authentication Flow

sequenceDiagram
    participant User
    participant App as Your App
    participant Authrim
    participant ExtIdP as External IdP

    User->>App: 1. Click "Login with GitHub"
    App->>Authrim: 2. GET /auth/external/github/start
    Authrim->>Authrim: 3. Generate state, nonce, PKCE
    Authrim-->>User: 4. Redirect to External IdP
    User->>ExtIdP: 5. Authentication screen
    ExtIdP->>ExtIdP: 6. User authentication
    ExtIdP-->>Authrim: 7. Callback (authorization code)
    Authrim->>ExtIdP: 8. Token exchange
    ExtIdP-->>Authrim: 9. Access token
    Authrim->>ExtIdP: 10. Fetch user info
    ExtIdP-->>Authrim: 11. User info
    Authrim->>Authrim: 12. Identity stitching
    Authrim-->>User: 13. Create session + redirect
    User->>App: 14. Authentication complete

Provider Setup

Google

1. Go to Google Cloud Console

2. Navigate to APIs & Services → Credentials → Create Credentials → OAuth client ID

3. Select Application type: Web application

4. Add Authorized redirect URI:

   https://your-domain.com/auth/external/google/callback

5. Copy the Client ID and Client Secret

6. Register the provider via Admin API:

   curl -X POST "https://your-domain.com/api/admin/external-providers" \
     -H "Authorization: Bearer ${ADMIN_MACHINE_ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "template": "google",
       "name": "Google",
       "slug": "google",
       "client_id": "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
       "client_secret": "YOUR_GOOGLE_CLIENT_SECRET"
     }'

Microsoft

1. Go to Azure Portal → Microsoft Entra ID → App registrations

2. Click New registration

3. Add Redirect URI:

   https://your-domain.com/auth/external/microsoft/callback

4. Go to Certificates & secrets → New client secret to create a secret

5. Copy the Application (client) ID and Client Secret

6. Register the provider via Admin API:

   curl -X POST "https://your-domain.com/api/admin/external-providers" \
     -H "Authorization: Bearer ${ADMIN_MACHINE_ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "template": "microsoft",
       "name": "Microsoft",
       "slug": "microsoft",
       "client_id": "YOUR_MICROSOFT_CLIENT_ID",
       "client_secret": "YOUR_MICROSOFT_CLIENT_SECRET",
       "provider_quirks": {
         "tenantType": "common"
       }
     }'

tenantType options:

Value	Description
common	All Microsoft accounts (personal + organizational)
organizations	Organizational accounts only (Azure AD)
consumers	Personal accounts only (Outlook.com, etc.)
{tenant-id}	Specific tenant only

GitHub

1. Go to GitHub Developer Settings

2. Click OAuth Apps → New OAuth App

3. Fill in the details:

   • Application name: Your app name
   • Homepage URL: https://your-domain.com
   • Authorization callback URL: https://your-domain.com/auth/external/github/callback

4. Click Register application

5. Copy the Client ID and Client Secret

6. Register the provider via Admin API:

   curl -X POST "https://your-domain.com/api/admin/external-providers" \
     -H "Authorization: Bearer ${ADMIN_MACHINE_ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "template": "github",
       "name": "GitHub",
       "slug": "github",
       "client_id": "YOUR_GITHUB_CLIENT_ID",
       "client_secret": "YOUR_GITHUB_CLIENT_SECRET"
     }'

GitHub Enterprise Server

For on-premise GitHub Enterprise Server, add configuration to provider_quirks:

{
  "provider_quirks": {
    "allowEnterpriseServer": true,
    "enterpriseServerUrl": "https://github.mycompany.com"
  }
}

Custom OIDC

Configure any OpenID Connect compliant provider:

curl -X POST "https://your-domain.com/api/admin/external-providers" \
  -H "Authorization: Bearer ${ADMIN_MACHINE_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom IdP",
    "slug": "custom-idp",
    "provider_type": "oidc",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "issuer": "https://idp.example.com",
    "scopes": "openid email profile"
  }'

Endpoints are automatically discovered via OIDC Discovery (/.well-known/openid-configuration).

Configuration Reference

Common Fields

Field	Type	Required	Description
name	string	✅	Display name
slug	string	-	URL-friendly identifier
client_id	string	✅	OAuth Client ID
client_secret	string	✅	OAuth Client Secret
enabled	boolean	-	Enable/disable (default: true)

Identity Linking

Field	Default	Description
auto_link_email	true	Auto-link accounts by email
jit_provisioning	true	JIT provisioning (auto user creation)
require_email_verified	true	Require verified email

Provider responses never return client_secret; they expose hasSecret instead.

User Flow Endpoints

Start Authentication

GET /auth/external/:provider/start?redirect_uri=https://app.example.com/callback

Parameter	Required	Description
redirect_uri	✅	Redirect destination after authentication
tenant_id	-	Tenant ID (for multi-tenant setups)
user_id	-	User ID to link (for account linking)

Security

Authrim automatically applies these security measures:

• PKCE: S256 method for all external IdP authentication flows
• State: Cryptographically secure state parameter for CSRF protection
• Nonce: Prevents ID Token replay attacks for OIDC providers
• Client Secret Handling: Secret values are write-only through the Admin API; read responses expose hasSecret
• Email Verification: Only verified emails allowed by default

Troubleshooting

”Provider not found”

1. Verify the provider is created
2. Check that slug or id is correct
3. Confirm enabled: true

”State validation failed”

1. Check if user took more than 60 seconds
2. Ensure the flow completes in the same browser/session
3. Verify cookies are not blocked

”Provider did not return email”

1. Check OAuth App has the appropriate scope (email)
2. For GitHub, user:email scope is required
3. Verify user has an email configured

References

• OpenID Connect Core 1.0
• OAuth 2.0 (RFC 6749)
• Google OAuth 2.0
• Microsoft Identity Platform
• GitHub OAuth Apps