Changelog

The Challenge

Many users wanted to sign in with different authentication providers (like Keycloak at work and Google on their phone) using the same email address. NextAuth.js blocks this by default for security reasons, showing an "OAuthAccountNotLinked" error.

The Solution

We implemented a comprehensive multi-provider authentication system:

1. Provider-Level Configuration: Enabled allowDangerousEmailAccountLinking at the provider level in NextAuth configuration

2. Custom Adapter Logic: Built a custom Prisma adapter that intelligently handles account linking:

• Checks if a user exists by email
• Links new provider accounts to existing users
• Updates tokens and session data seamlessly

3. Enhanced Error Recovery: Added graceful error handling to recover from constraint violations and edge cases

Key Technical Implementation

KeycloakProvider({
  clientId: process.env.KEYCLOAK_CLIENT_ID,
  clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
  issuer: process.env.KEYCLOAK_ISSUER,
  allowDangerousEmailAccountLinking: true, // Critical setting
  profile: (profile, tokens) => {
    // Custom profile mapping
  }
})

Security Considerations

While "dangerous" in name, this feature is safe when:

• Using trusted OAuth providers with email verification
• Implementing proper adapter logic to prevent account takeover
• Logging all account linking events for audit trails

What We Learned

• NextAuth v4 requires allowDangerousEmailAccountLinking at the provider level, not globally
• Custom adapters need comprehensive error handling for database constraints
• Detailed logging is crucial for debugging authentication flows
• TypeScript type assertions (as any) can be necessary to preserve runtime config properties

Impact

Users can now:

• ✅ Sign in with multiple providers using one email
• ✅ Switch between providers seamlessly
• ✅ Maintain one account with all their data intact