Social Login and Enterprise IdPs

ZITADEL supports identity federation through social login providers and enterprise identity providers (IdPs). Users can authenticate using their existing accounts from Google, GitHub, Microsoft, and many other providers instead of creating new credentials.

Supported Identity Providers

ZITADEL provides built-in templates for popular identity providers: Google: OAuth 2.0 / OpenID Connect GitHub: OAuth 2.0 GitLab: OAuth 2.0 Apple: OAuth 2.0 / OpenID Connect with Sign in with Apple

Enterprise Providers

Azure AD / Microsoft Entra ID: OpenID Connect Generic OIDC: Any OpenID Connect-compliant provider Generic OAuth 2.0: Any OAuth 2.0 provider SAML 2.0: Enterprise SAML identity providers JWT: Token-based authentication with JWT providers LDAP: Lightweight Directory Access Protocol providers

How Identity Federation Works

Identity federation follows the OAuth 2.0 / OpenID Connect protocols:

User Initiates Login

User clicks on a social login button (e.g., “Sign in with Google”) in the ZITADEL Login UI

Redirect to Provider

ZITADEL redirects the user to the external identity provider’s authentication page

User Authenticates

User authenticates with the external provider using their existing credentials

Authorization Grant

Provider redirects back to ZITADEL with an authorization code or tokens

Token Exchange

ZITADEL exchanges the authorization code for access and ID tokens

User Information

ZITADEL retrieves user profile information from the provider

Account Linking

ZITADEL links the external identity to a local user account (or creates a new one)

Session Creation

ZITADEL creates an authenticated session and returns to the application

Configuring Identity Providers

Prerequisites

Before adding an identity provider to ZITADEL:

Enable external IdP support in your Login Policy
Register your application with the external provider
Obtain client credentials (Client ID and Client Secret)
Configure redirect URIs at the provider

Navigate to Login Policy

Go to Instance/Organization Settings > Login Policy

Allow External IdP

Enable Allow External IdP option

Save Configuration

Save the settings to enable social login support

Or via API:

curl -X PUT https://$ZITADEL_DOMAIN/v2/settings/login_policy \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowExternalIdp": true
  }'

Adding Identity Providers

Google

Create Google OAuth App

Go to Google Cloud Console
Create a new project or select existing
Navigate to APIs & Services > Credentials
Create OAuth 2.0 Client ID (Web application)
Add authorized redirect URI: https://your-domain.zitadel.cloud/ui/login/login/externalidp/callback
Note the Client ID and Client Secret

Add Provider in ZITADEL

Navigate to Instance/Organization Settings > Identity Providers
Click Add Provider
Select Google template
Enter Client ID and Client Secret
Configure scopes (default: openid profile email)
Save the configuration

Add to Login Policy

Go to Login Policy > Identity Providers
Add the Google provider
Save changes

GitHub

Create GitHub OAuth App

Go to GitHub Settings > Developer settings > OAuth Apps
Click New OAuth App
Set Authorization callback URL: https://your-domain.zitadel.cloud/ui/login/login/externalidp/callback
Note the Client ID and Client Secret

Add Provider in ZITADEL

Navigate to Identity Providers
Select GitHub template
Enter Client ID and Client Secret
Configure scopes (default: user:email)
Save configuration

GitHub Provider Implementation

// From internal/idp/providers/github/github.go
const (
    authURL        = "https://github.com/login/oauth/authorize"
    tokenURL       = "https://github.com/login/oauth/access_token"
    profileURL     = "https://api.github.com/user"
)

func New(clientID, secret, callbackURL string, scopes []string, options ...oauth.ProviderOpts) (*Provider, error) {
    return NewCustomURL(name, clientID, secret, callbackURL, authURL, tokenURL, profileURL, scopes, options...)
}

Azure AD / Microsoft Entra ID

Go to Azure Portal
Navigate to Azure Active Directory > App registrations
Click New registration
Set Redirect URI: https://your-domain.zitadel.cloud/ui/login/login/externalidp/callback
Create a client secret in Certificates & secrets
Note Application (client) ID and Directory (tenant) ID

Configure in ZITADEL

Add new Identity Provider
Select Azure AD template
Enter:
- Client ID (Application ID)
- Client Secret
- Tenant ID (or use common for multi-tenant)
Configure scopes: openid profile email
Save configuration

Generic OIDC Provider

For any OpenID Connect-compliant provider:

curl -X POST https://$ZITADEL_DOMAIN/admin/v1/idps/oidc \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom OIDC Provider",
    "issuer": "https://provider.example.com",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "scopes": ["openid", "profile", "email"],
    "isLinkingAllowed": true,
    "isCreationAllowed": true,
    "isAutoCreation": false,
    "isAutoUpdate": true
  }'

Identity Provider Options

When configuring identity providers, you can control user account behavior:

Linking Options

IsLinkingAllowed: Allow users to manually link external identity to existing ZITADEL account IsCreationAllowed: Allow users to create new ZITADEL account using external identity IsAutoCreation: Automatically create ZITADEL account on first login (no manual confirmation) IsAutoUpdate: Automatically update user profile from external provider on each login

// From internal/idp/providers implementation
type ProviderOpts func(provider *Provider)

func WithLinkingAllowed() ProviderOpts {
    return func(p *Provider) {
        p.isLinkingAllowed = true
    }
}

func WithCreationAllowed() ProviderOpts {
    return func(p *Provider) {
        p.isCreationAllowed = true
    }
}

func WithAutoCreation() ProviderOpts {
    return func(p *Provider) {
        p.isAutoCreation = true
    }
}

func WithAutoUpdate() ProviderOpts {
    return func(p *Provider) {
        p.isAutoUpdate = true
    }
}

Recommended Settings

B2C Applications (consumer apps):

isLinkingAllowed: true
isCreationAllowed: true
isAutoCreation: true
isAutoUpdate: true

B2B Applications (enterprise apps):

isLinkingAllowed: true
isCreationAllowed: false (pre-provision users)
isAutoCreation: false
isAutoUpdate: true

Attribute Mapping

ZITADEL maps attributes from external providers to local user profiles:

Standard Mappings

Google:

ID → External User ID
Email → Email (verified)
Given Name → First Name
Family Name → Last Name
Picture → Avatar URL

GitHub:

ID → External User ID
Login → Preferred Username
Email → Email (verified)
Name → Display Name
Avatar URL → Avatar URL

Azure AD:

OID → External User ID
Email → Email
Given Name → First Name
Surname → Last Name
Picture → Avatar URL

Custom Attribute Mapping

For generic OIDC/OAuth providers, you can configure custom attribute mappings to extract specific claims from the provider’s ID token or user info endpoint.

Identity Brokering

ZITADEL acts as an identity broker, allowing you to:

Aggregate multiple identity providers
Provide consistent authentication experience
Centralize user management
Apply organization-specific policies
Maintain audit trail across providers

ZITADEL acts as an identity broker, aggregating multiple identity providers while maintaining a centralized user management system.

Domain Discovery

Automate organization and IdP selection based on user’s email domain:

Enable Domain Discovery

Enable in Login Policy: allowDomainDiscovery: true

Configure Organization Domains

Add verified domains to organizations

Map IdPs to Organizations

Configure which IdPs are available per organization

User Experience

User enters email → ZITADEL detects organization → Shows appropriate IdP options

Domain discovery automates organization and IdP selection based on the user’s email domain.

MFA with External IdPs

Control MFA requirements for federated users:

Force MFA for Local Only

Require MFA only for local accounts, not federated users:

curl -X PUT https://$ZITADEL_DOMAIN/v2/settings/login_policy \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "forceMfa": true,
    "forceMfaLocalOnly": true
  }'

With forceMfaLocalOnly: true, users authenticating via external IdPs bypass ZITADEL’s MFA requirement (assuming the external provider handles MFA).

Testing Identity Providers

Redirect URI

Ensure your redirect URI matches exactly:

https://{your-zitadel-domain}/ui/login/login/externalidp/callback

Test Flow

Open incognito/private browser window
Navigate to your application’s login page
Click the social login button
Verify redirect to external provider
Authenticate with test credentials
Verify successful redirect back to ZITADEL
Check user creation/linking in ZITADEL Console

Common Issues

Redirect URI mismatch: Verify exact match including protocol (https) and trailing slash Invalid client credentials: Double-check Client ID and Client Secret Scope errors: Ensure requested scopes are enabled at the provider CORS issues: For custom providers, verify CORS configuration

Security Considerations

Client Secret Protection: Store client secrets securely. Never expose them in client-side code or version control.

Email Verification: External provider email claims are trusted as verified. Ensure you trust the provider’s verification process.

Account Takeover Prevention: Carefully configure linking options to prevent unauthorized account linking.

Best Practices

Use HTTPS: Always use HTTPS for redirect URIs in production
Verify State Parameter: ZITADEL automatically includes state parameter for CSRF protection
Limit Scopes: Request only necessary scopes from external providers
Monitor Account Linking: Track which accounts link external identities
Update Regularly: Keep provider configurations up to date

API Reference

Key IdP-related API endpoints:

Add OIDC IdP

POST /admin/v1/idps/oidc

Add OAuth IdP

POST /admin/v1/idps/oauth

Add SAML IdP

POST /admin/v1/idps/saml

List IdPs

GET /admin/v1/idps/_search

POST /admin/v1/policies/login/idps

See the Admin Service API for complete documentation.

Multi-Tenancy Considerations

In multi-tenant deployments:

Configure IdPs at Instance level for global availability
Configure IdPs at Organization level for tenant-specific providers
Organization-level IdPs override instance-level settings
Each organization can have different available IdPs

Migration from Other IAM Systems

When migrating from other IAM systems:

Map External IDs

Preserve external identity provider links during migration

Configure Matching IdPs

Set up the same external providers in ZITADEL

Test Thoroughly

Verify authentication flow with test users before migration

Update Redirect URIs

Update all redirect URIs at external providers to point to ZITADEL

Overview

Core Concepts

Deployment

User Management

Authentication

Integration

​Supported Identity Providers

​Social Providers

​Enterprise Providers

​How Identity Federation Works

​Configuring Identity Providers

​Prerequisites

​Enable External IdP in Login Policy

​Adding Identity Providers

​Google

​GitHub

​GitHub Provider Implementation

​Azure AD / Microsoft Entra ID

​Generic OIDC Provider

​Identity Provider Options

​Linking Options

​Recommended Settings

​Attribute Mapping

​Standard Mappings

​Custom Attribute Mapping

​Identity Brokering

​Domain Discovery

​MFA with External IdPs

​Force MFA for Local Only

​Testing Identity Providers

​Redirect URI

​Test Flow

​Common Issues

​Security Considerations

​Best Practices

​API Reference

​Add OIDC IdP

​Add OAuth IdP

​Add SAML IdP

​List IdPs

​Add IdP to Login Policy

​Multi-Tenancy Considerations

​Migration from Other IAM Systems

​Related Documentation

Build docs developers (and LLMs) love

Supported Identity Providers

Social Providers

Enterprise Providers

How Identity Federation Works

Configuring Identity Providers

Prerequisites

Enable External IdP in Login Policy

Adding Identity Providers

Google

GitHub

GitHub Provider Implementation

Azure AD / Microsoft Entra ID

Generic OIDC Provider

Identity Provider Options

Linking Options

Recommended Settings

Attribute Mapping

Standard Mappings

Custom Attribute Mapping

Identity Brokering

Domain Discovery

MFA with External IdPs

Force MFA for Local Only

Testing Identity Providers

Redirect URI

Test Flow

Common Issues

Security Considerations

Best Practices

API Reference

Add OIDC IdP

Add OAuth IdP

Add SAML IdP

List IdPs

Add IdP to Login Policy

Multi-Tenancy Considerations

Migration from Other IAM Systems

Related Documentation