0
# Authentication Providers
1

2
Built-in support for 67+ authentication providers including OAuth, email, and credentials-based authentication. NextAuth.js provides extensive provider ecosystem with standardized configuration patterns.
3

4
## Capabilities
5

6
### Provider Types
7

8
NextAuth.js supports three main types of authentication providers with different use cases and configurations.
9

10
```typescript { .api }
11
/**
12
 * Base provider interface for all authentication providers
13
 */
14
interface Provider extends CommonProviderOptions {
15
  id: string;
16
  name: string;
17
  type: ProviderType;
18
  options?: any;
19
}
20

21
interface CommonProviderOptions {
22
  id: string;
23
  name: string;
24
  type: ProviderType;
25
  options?: any;
26
}
27

28
type ProviderType = "oauth" | "email" | "credentials";
29
```
30

31
### OAuth Providers
32

33
OAuth providers for third-party authentication services with standardized configuration.
34

35
```typescript { .api }
36
/**
37
 * OAuth provider configuration interface
38
 */
39
interface OAuthConfig<P> extends CommonProviderOptions {
40
  id: string;
41
  name: string;
42
  type: "oauth";
43
  /** OAuth authorization endpoint or handler */
44
  authorization: string | AuthorizationEndpointHandler;
45
  /** OAuth token endpoint or handler */
46
  token: string | TokenEndpointHandler;
47
  /** OAuth userinfo endpoint or handler */
48
  userinfo?: string | UserinfoEndpointHandler;
49
  /** OpenID Connect well-known configuration URL */
50
  wellKnown?: string;
51
  /** OAuth client configuration */
52
  client: Partial<ClientMetadata>;
53
  /** OAuth client ID */
54
  clientId: string;
55
  /** OAuth client secret */
56
  clientSecret: string;
57
  /** ID token support flag */
58
  idToken?: boolean;
59
  /** OAuth provider style configuration */
60
  style?: ProviderStyleConfig;
61
  /** Custom profile mapping function */
62
  profile?: (profile: P, tokens: TokenSet) => Awaitable<User>;
63
  /** Additional OAuth options */
64
  options?: OAuthUserConfig<P>;
65
}
66

67
interface OAuthUserConfig<P> {
68
  clientId: string;
69
  clientSecret: string;
70
  authorization?: string | AuthorizationEndpointHandler;
71
  token?: string | TokenEndpointHandler;
72
  userinfo?: string | UserinfoEndpointHandler;
73
  wellKnown?: string;
74
  issuer?: string;
75
  client?: Partial<ClientMetadata>;
76
  profile?: (profile: P, tokens: TokenSet) => Awaitable<User>;
77
  style?: ProviderStyleConfig;
78
  options?: any;
79
}
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
// Google OAuth Provider
86
import GoogleProvider from "next-auth/providers/google";
87

88
export default NextAuth({
89
  providers: [
90
    GoogleProvider({
91
      clientId: process.env.GOOGLE_CLIENT_ID!,
92
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
93
    }),
94
  ],
95
});
96

97
// GitHub OAuth Provider with custom profile
98
import GitHubProvider from "next-auth/providers/github";
99

100
export default NextAuth({
101
  providers: [
102
    GitHubProvider({
103
      clientId: process.env.GITHUB_ID!,
104
      clientSecret: process.env.GITHUB_SECRET!,
105
      profile(profile) {
106
        return {
107
          id: profile.id.toString(),
108
          name: profile.name || profile.login,
109
          email: profile.email,
110
          image: profile.avatar_url,
111
          username: profile.login,
112
        };
113
      },
114
    }),
115
  ],
116
});
117

118
// Auth0 Provider with custom domain
119
import Auth0Provider from "next-auth/providers/auth0";
120

121
export default NextAuth({
122
  providers: [
123
    Auth0Provider({
124
      clientId: process.env.AUTH0_CLIENT_ID!,
125
      clientSecret: process.env.AUTH0_CLIENT_SECRET!,
126
      issuer: process.env.AUTH0_ISSUER_BASE_URL,
127
      authorization: {
128
        params: {
129
          scope: "openid email profile",
130
          audience: process.env.AUTH0_AUDIENCE,
131
        },
132
      },
133
    }),
134
  ],
135
});
136
```
137

138
### Email Provider
139

140
Email-based passwordless authentication with magic link functionality.
141

142
```typescript { .api }
143
/**
144
 * Email provider configuration interface
145
 */
146
interface EmailConfig extends CommonProviderOptions {
147
  id: string;
148
  name: string;
149
  type: "email";
150
  /** Email server configuration */
151
  server: string | EmailServerConfig;
152
  /** Sender email address */
153
  from: string;
154
  /** Maximum age for verification tokens in seconds */
155
  maxAge?: number;
156
  /** Custom email sending function */
157
  sendVerificationRequest?: (params: {
158
    identifier: string;
159
    url: string;
160
    expires: Date;
161
    provider: EmailConfig;
162
    token: string;
163
    theme: Theme;
164
    request: Request;
165
  }) => Awaitable<void>;
166
  /** Generate custom verification token */
167
  generateVerificationToken?: () => Awaitable<string>;
168
  /** Normalize email address */
169
  normalizeIdentifier?: (identifier: string) => string;
170
  /** Email provider options */
171
  options?: EmailUserConfig;
172
}
173

174
interface EmailServerConfig {
175
  host: string;
176
  port: number;
177
  auth: {
178
    user: string;
179
    pass: string;
180
  };
181
  secure?: boolean;
182
  tls?: {
183
    ciphers?: string;
184
    rejectUnauthorized?: boolean;
185
  };
186
}
187

188
interface EmailUserConfig {
189
  server: string | EmailServerConfig;
190
  from: string;
191
  maxAge?: number;
192
  sendVerificationRequest?: (params: any) => Awaitable<void>;
193
  generateVerificationToken?: () => Awaitable<string>;
194
  normalizeIdentifier?: (identifier: string) => string;
195
}
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
// Basic email provider with SMTP
202
import EmailProvider from "next-auth/providers/email";
203

204
export default NextAuth({
205
  providers: [
206
    EmailProvider({
207
      server: {
208
        host: process.env.EMAIL_SERVER_HOST,
209
        port: process.env.EMAIL_SERVER_PORT,
210
        auth: {
211
          user: process.env.EMAIL_SERVER_USER,
212
          pass: process.env.EMAIL_SERVER_PASSWORD,
213
        },
214
      },
215
      from: process.env.EMAIL_FROM,
216
    }),
217
  ],
218
});
219

220
// Email provider with custom verification
221
export default NextAuth({
222
  providers: [
223
    EmailProvider({
224
      server: process.env.EMAIL_SERVER,
225
      from: process.env.EMAIL_FROM,
226
      maxAge: 24 * 60 * 60, // 24 hours
227
      sendVerificationRequest: async ({ identifier, url, provider }) => {
228
        // Custom email sending logic
229
        await sendCustomVerificationEmail({
230
          to: identifier,
231
          verificationUrl: url,
232
          provider,
233
        });
234
      },
235
    }),
236
  ],
237
});
238

239
// Email provider with custom domain normalization
240
export default NextAuth({
241
  providers: [
242
    EmailProvider({
243
      server: process.env.EMAIL_SERVER,
244
      from: process.env.EMAIL_FROM,
245
      normalizeIdentifier: (identifier: string) => {
246
        // Custom email normalization
247
        return identifier.toLowerCase().trim();
248
      },
249
    }),
250
  ],
251
});
252
```
253

254
### Credentials Provider
255

256
Username/password authentication with custom validation logic.
257

258
```typescript { .api }
259
/**
260
 * Credentials provider configuration interface
261
 */
262
interface CredentialsConfig extends CommonProviderOptions {
263
  id: string;
264
  name: string;
265
  type: "credentials";
266
  /** Form field definitions */
267
  credentials: Record<string, CredentialInput>;
268
  /** Custom authorization function */
269
  authorize: (
270
    credentials: Record<string, string> | undefined,
271
    req: Pick<RequestInternal, "body" | "query" | "headers" | "method">
272
  ) => Awaitable<User | null>;
273
  /** Credentials provider options */
274
  options?: CredentialsUserConfig;
275
}
276

277
interface CredentialInput {
278
  /** Input field label */
279
  label?: string;
280
  /** Input field type */
281
  type?: string;
282
  /** Input field placeholder */
283
  placeholder?: string;
284
  /** Default input value */
285
  value?: string;
286
}
287

288
interface CredentialsUserConfig {
289
  name?: string;
290
  credentials: Record<string, CredentialInput>;
291
  authorize: (
292
    credentials: Record<string, string> | undefined,
293
    req: any
294
  ) => Awaitable<User | null>;
295
}
296
```
297

298
**Usage Examples:**
299

300
```typescript
301
// Basic credentials provider
302
import CredentialsProvider from "next-auth/providers/credentials";
303

304
export default NextAuth({
305
  providers: [
306
    CredentialsProvider({
307
      name: "Credentials",
308
      credentials: {
309
        username: { label: "Username", type: "text", placeholder: "jsmith" },
310
        password: { label: "Password", type: "password" }
311
      },
312
      async authorize(credentials, req) {
313
        // Validate credentials against your database
314
        const user = await validateUser(credentials?.username, credentials?.password);
315
        
316
        if (user) {
317
          return {
318
            id: user.id,
319
            name: user.name,
320
            email: user.email,
321
          };
322
        }
323
        
324
        return null;
325
      }
326
    })
327
  ],
328
});
329

330
// Advanced credentials provider with multiple fields
331
export default NextAuth({
332
  providers: [
333
    CredentialsProvider({
334
      name: "Company Login",
335
      credentials: {
336
        email: { 
337
          label: "Email", 
338
          type: "email", 
339
          placeholder: "user@company.com" 
340
        },
341
        password: { 
342
          label: "Password", 
343
          type: "password" 
344
        },
345
        domain: { 
346
          label: "Domain", 
347
          type: "text", 
348
          placeholder: "company.com" 
349
        },
350
      },
351
      async authorize(credentials, req) {
352
        // Custom validation with multiple fields
353
        const user = await validateCompanyUser({
354
          email: credentials?.email,
355
          password: credentials?.password,
356
          domain: credentials?.domain,
357
        });
358
        
359
        if (user) {
360
          return {
361
            id: user.id,
362
            name: user.name,
363
            email: user.email,
364
            domain: user.domain,
365
          };
366
        }
367
        
368
        throw new Error("Invalid credentials");
369
      }
370
    })
371
  ],
372
});
373

374
// API-based credentials validation
375
export default NextAuth({
376
  providers: [
377
    CredentialsProvider({
378
      name: "API Login",
379
      credentials: {
380
        apiKey: { label: "API Key", type: "password" },
381
        userId: { label: "User ID", type: "text" },
382
      },
383
      async authorize(credentials, req) {
384
        // Validate against external API
385
        const response = await fetch("https://api.example.com/validate", {
386
          method: "POST",
387
          headers: { "Content-Type": "application/json" },
388
          body: JSON.stringify({
389
            apiKey: credentials?.apiKey,
390
            userId: credentials?.userId,
391
          }),
392
        });
393
        
394
        const result = await response.json();
395
        
396
        if (response.ok && result.valid) {
397
          return {
398
            id: result.user.id,
399
            name: result.user.name,
400
            email: result.user.email,
401
            apiAccess: true,
402
          };
403
        }
404
        
405
        return null;
406
      }
407
    })
408
  ],
409
});
410
```
411

412
### Built-in OAuth Providers
413

414
NextAuth.js includes 67+ built-in OAuth providers with pre-configured settings.
415

416
```typescript { .api }
417
/**
418
 * Selection of popular built-in OAuth providers
419
 */
420
interface PopularOAuthProviders {
421
  Apple: typeof AppleProvider;
422
  Auth0: typeof Auth0Provider;
423
  AzureAD: typeof AzureADProvider;
424
  Cognito: typeof CognitoProvider;
425
  Discord: typeof DiscordProvider;
426
  Facebook: typeof FacebookProvider;
427
  GitHub: typeof GitHubProvider;
428
  GitLab: typeof GitLabProvider;
429
  Google: typeof GoogleProvider;
430
  LinkedIn: typeof LinkedInProvider;
431
  Okta: typeof OktaProvider;
432
  Spotify: typeof SpotifyProvider;
433
  Twitch: typeof TwitchProvider;
434
  Twitter: typeof TwitterProvider;
435
}
436
```
437

438
**Usage Examples:**
439

440
```typescript
441
// Multiple OAuth providers
442
import GoogleProvider from "next-auth/providers/google";
443
import GitHubProvider from "next-auth/providers/github";
444
import DiscordProvider from "next-auth/providers/discord";
445

446
export default NextAuth({
447
  providers: [
448
    GoogleProvider({
449
      clientId: process.env.GOOGLE_CLIENT_ID!,
450
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
451
    }),
452
    GitHubProvider({
453
      clientId: process.env.GITHUB_ID!,
454
      clientSecret: process.env.GITHUB_SECRET!,
455
    }),
456
    DiscordProvider({
457
      clientId: process.env.DISCORD_CLIENT_ID!,
458
      clientSecret: process.env.DISCORD_CLIENT_SECRET!,
459
    }),
460
  ],
461
});
462

463
// Apple Sign In with custom configuration
464
import AppleProvider from "next-auth/providers/apple";
465

466
export default NextAuth({
467
  providers: [
468
    AppleProvider({
469
      clientId: process.env.APPLE_ID!,
470
      clientSecret: process.env.APPLE_SECRET!,
471
      authorization: {
472
        params: {
473
          scope: "name email",
474
          response_mode: "form_post",
475
        },
476
      },
477
    }),
478
  ],
479
});
480

481
// Azure AD with tenant configuration
482
import AzureADProvider from "next-auth/providers/azure-ad";
483

484
export default NextAuth({
485
  providers: [
486
    AzureADProvider({
487
      clientId: process.env.AZURE_AD_CLIENT_ID!,
488
      clientSecret: process.env.AZURE_AD_CLIENT_SECRET!,
489
      tenantId: process.env.AZURE_AD_TENANT_ID,
490
      authorization: {
491
        params: {
492
          scope: "openid profile email User.Read",
493
        },
494
      },
495
    }),
496
  ],
497
});
498
```
499

500
### Custom Provider Configuration
501

502
Advanced patterns for creating custom providers and extending existing ones.
503

504
```typescript { .api }
505
/**
506
 * Custom provider creation utilities
507
 */
508
interface CustomProviderConfig {
509
  /** Create custom OAuth provider */
510
  createOAuthProvider: <P>(config: OAuthUserConfig<P>) => OAuthConfig<P>;
511
  /** Extend existing provider */
512
  extendProvider: <T extends Provider>(provider: T, overrides: Partial<T>) => T;
513
  /** Create provider with custom endpoints */
514
  createCustomProvider: (endpoints: CustomEndpoints) => Provider;
515
}
516

517
interface CustomEndpoints {
518
  authorization: string;
519
  token: string;
520
  userinfo: string;
521
  issuer?: string;
522
}
523
```
524

525
**Usage Examples:**
526

527
```typescript
528
// Custom OAuth provider
529
const CustomProvider = {
530
  id: "custom-oauth",
531
  name: "Custom OAuth Service",
532
  type: "oauth",
533
  authorization: "https://oauth.example.com/authorize",
534
  token: "https://oauth.example.com/token",
535
  userinfo: "https://oauth.example.com/userinfo",
536
  clientId: process.env.CUSTOM_CLIENT_ID,
537
  clientSecret: process.env.CUSTOM_CLIENT_SECRET,
538
  profile(profile) {
539
    return {
540
      id: profile.sub,
541
      name: profile.name,
542
      email: profile.email,
543
      image: profile.picture,
544
    };
545
  },
546
};
547

548
// Extend existing provider
549
import GoogleProvider from "next-auth/providers/google";
550

551
const ExtendedGoogleProvider = {
552
  ...GoogleProvider({
553
    clientId: process.env.GOOGLE_CLIENT_ID!,
554
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
555
  }),
556
  authorization: {
557
    params: {
558
      scope: "openid email profile https://www.googleapis.com/auth/calendar.readonly",
559
      prompt: "consent",
560
      access_type: "offline",
561
      response_type: "code",
562
    },
563
  },
564
  profile(profile) {
565
    return {
566
      id: profile.sub,
567
      name: profile.name,
568
      email: profile.email,
569
      image: profile.picture,
570
      locale: profile.locale,
571
    };
572
  },
573
};
574

575
// Provider with custom token handling
576
const CustomTokenProvider = {
577
  id: "custom-token",
578
  name: "Custom Token Provider",
579
  type: "oauth",
580
  authorization: "https://auth.example.com/oauth/authorize",
581
  token: {
582
    url: "https://auth.example.com/oauth/token",
583
    async request({ client, params, checks, provider }) {
584
      // Custom token request logic
585
      const response = await client.oauthCallback(
586
        provider.callbackUrl,
587
        params,
588
        checks
589
      );
590
      
591
      // Custom token processing
592
      return {
593
        tokens: response,
594
        profile: await fetchCustomProfile(response.access_token),
595
      };
596
    },
597
  },
598
  userinfo: "https://api.example.com/user",
599
  clientId: process.env.CUSTOM_CLIENT_ID,
600
  clientSecret: process.env.CUSTOM_CLIENT_SECRET,
601
};
602

603
export default NextAuth({
604
  providers: [
605
    CustomProvider,
606
    ExtendedGoogleProvider,
607
    CustomTokenProvider,
608
  ],
609
});
610
```
611

612
### Provider Styling and UI
613

614
Configuration options for customizing provider appearance in sign-in pages.
615

616
```typescript { .api }
617
/**
618
 * Provider styling configuration
619
 */
620
interface ProviderStyleConfig {
621
  /** Provider logo URL */
622
  logo?: string;
623
  /** Provider logo dark mode URL */
624
  logoDark?: string;
625
  /** Provider background color */
626
  bg?: string;
627
  /** Provider background dark mode color */
628
  bgDark?: string;
629
  /** Provider text color */
630
  text?: string;
631
  /** Provider text dark mode color */
632
  textDark?: string;
633
}
634
```
635

636
**Usage Example:**
637

638
```typescript
639
// Custom provider styling
640
import GoogleProvider from "next-auth/providers/google";
641

642
export default NextAuth({
643
  providers: [
644
    GoogleProvider({
645
      clientId: process.env.GOOGLE_CLIENT_ID!,
646
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
647
      style: {
648
        logo: "https://example.com/google-logo.png",
649
        bg: "#4285f4",
650
        text: "#fff",
651
        bgDark: "#1a73e8",
652
        textDark: "#fff",
653
      },
654
    }),
655
  ],
656
});
657
```
658

659
## Types
660

661
### Provider Interface Types
662

663
```typescript { .api }
664
interface AuthorizationEndpointHandler {
665
  url: string;
666
  params?: Record<string, string>;
667
  request?: (context: any) => Awaitable<any>;
668
}
669

670
interface TokenEndpointHandler {
671
  url: string;
672
  params?: Record<string, string>;
673
  request?: (context: any) => Awaitable<any>;
674
}
675

676
interface UserinfoEndpointHandler {
677
  url: string;
678
  params?: Record<string, string>;
679
  request?: (context: any) => Awaitable<any>;
680
}
681

682
interface ClientMetadata {
683
  client_id?: string;
684
  client_secret?: string;
685
  redirect_uris?: string[];
686
  response_types?: string[];
687
  grant_types?: string[];
688
  application_type?: string;
689
  contacts?: string[];
690
  client_name?: string;
691
  logo_uri?: string;
692
  client_uri?: string;
693
  policy_uri?: string;
694
  tos_uri?: string;
695
  jwks_uri?: string;
696
  jwks?: any;
697
  software_id?: string;
698
  software_version?: string;
699
}
700

701
interface TokenSet {
702
  access_token: string;
703
  expires_at?: number;
704
  id_token?: string;
705
  refresh_token?: string;
706
  scope?: string;
707
  session_state?: string;
708
  token_type?: string;
709
}
710
```
711

712
### Request Types
713

714
```typescript { .api }
715
interface RequestInternal {
716
  body?: any;
717
  query?: any;
718
  headers?: any;
719
  method?: string;
720
  cookies?: any;
721
  url?: string;
722
}
723

724
interface Theme {
725
  colorScheme?: "light" | "dark" | "auto";
726
  logo?: string;
727
  brandColor?: string;
728
  buttonText?: string;
729
}
730
```