Custom OAuth / SSO Provider

Plug in any provider not built in — Microsoft, Okta, Auth0, Discord, an internal SSO — with a full, end-to-end example.

Need Microsoft, Discord, Slack, Okta, Auth0, an internal enterprise SSO? Extend SocialAuthProvider, implement validate(), and pass an instance to the module. Nest Auth handles everything else — identity lookup, user creation, account linking, session, and events (see how SSO works).

Extend SocialAuthProvider, not BaseAuthProvider, for any provider whose validate() returns the provider's own user id (an OAuth sub, Discord id, …). SocialAuthProvider resolves the linked identity by that external subject (providerId). BaseAuthProvider resolves by our internal userId — a uuid column — so a non-UUID subject makes every login 500 on Postgres with invalid input syntax for type uuid (it silently returns INVALID_CREDENTIALS on SQLite). Use BaseAuthProvider only when your validate() returns our NestAuthUser.id.

Full example: a Discord provider, end to end

Five steps take you from nothing to a working "Sign in with Discord". Swap the URLs/fields for Microsoft, Okta, Auth0, or your internal IdP — the shape is identical.

1. Register the OAuth app with the provider

In the Discord Developer Portal → New Application → OAuth2. Add your redirect URI, select the identify + email scopes, and copy the Client ID and Client Secret. (Every provider has an equivalent console step — this is where you get the credentials.)

2. Write the provider

A SocialAuthProvider subclass needs exactly three things: providerName, getRequiredFields(), and validate(). validate() verifies the credential with the provider and returns a normalized user.

// src/auth/discord.provider.ts
import { SocialAuthProvider, AuthProviderUser } from '@ackplus/nest-auth';
import { UnauthorizedException } from '@nestjs/common';
 
interface DiscordOptions {
  clientId: string;
  clientSecret: string;
  redirectUri: string;
}
 
export class DiscordAuthProvider extends SocialAuthProvider {
  // The name you pass as `providerName` on POST /auth/login. (NOT `name`.)
  providerName = 'discord';
 
  // The user already authenticated with Discord — skip Nest Auth's own MFA
  // challenge. Omit (defaults false) to still require app-level MFA.
  skipMfa = true;
 
  constructor(private readonly opts: DiscordOptions) {
    // super() with no args — the provider registry injects the DB repositories
    // the base helpers need once the module boots.
    super();
  }
 
  // The credential fields the client MUST send (validated before validate()).
  getRequiredFields(): string[] {
    return ['token']; // switch to ['code'] to accept an auth code instead
  }
 
  async validate(credentials: { token?: string }): Promise<AuthProviderUser | null> {
    // 1. Verify the credential with the provider.
    const me = await fetch('https://discord.com/api/users/@me', {
      headers: { Authorization: `Bearer ${credentials.token}` },
    }).then((r) => r.json());
 
    if (!me?.id) throw new UnauthorizedException('Invalid Discord token');
 
    // 2. Return the normalized user.
    return {
      userId: me.id,                    // the PROVIDER's user id — field is `userId`, not `providerId`
      email: me.email,
      emailVerified: me.verified === true, // true ONLY if the provider attests it
      metadata: { username: me.username, avatarUrl: me.avatar },
    };
  }
}

3. Register it in the module

Pass a plain instance in customAuthProviders. That's it — the repositories are injected for you, so no forRootAsync or DI wiring is needed.

// app.module.ts
NestAuthModule.forRoot({
  session: { jwt: { secret: process.env.JWT_SECRET! } },
  customAuthProviders: [
    new DiscordAuthProvider({
      clientId: process.env.DISCORD_CLIENT_ID!,
      clientSecret: process.env.DISCORD_CLIENT_SECRET!,
      redirectUri: process.env.DISCORD_REDIRECT_URI!,
    }),
  ],
});

POST /auth/login with { providerName: 'discord', … } now works.

4. Call it from the frontend

Get a Discord access token with your OAuth flow, then log in. A first-time user needs createUserIfNotExists: true — the client SDK's socialLogin() sets it for you:

import { AuthClient } from '@ackplus/nest-auth-client';
const client = new AuthClient({ baseUrl: '/api' });
 
// socialLogin defaults createUserIfNotExists: true
const res = await client.socialLogin('discord', discordAccessToken);
// res is a normal auth response (session/tokens) — the user is signed in.

React (useNestAuth().login) — pass the flag yourself:

const { login } = useNestAuth();
await login({
  providerName: 'discord',
  credentials: { token: discordAccessToken },
  createUserIfNotExists: true,
});

5. Verify with curl

curl -X POST http://localhost:3000/auth/login \
  -H 'Content-Type: application/json' \
  -d '{
    "providerName": "discord",
    "credentials": { "token": "<a real discord access token>" },
    "createUserIfNotExists": true
  }'

A 2xx with a session/token body means it works. On the first call a NestAuthUser + identity row are created; subsequent logins with the same Discord id resolve to the same user.

The `AuthProviderUser` you return

Field	Meaning
`userId` (required)	The provider's stable user id (an OAuth `sub`, Discord `id`, …). Identities are keyed on this — not your local user id.
`email` / `phone`	Used to find/create the local user and to link to an existing account.
`emailVerified` / `phoneVerified`	Set `true` only when the provider proves it. Controls the linking gate and whether `emailVerifiedAt` is stamped.
`metadata`	Anything else (username, avatar, raw profile) — stored on the identity and available to your hooks.

Return null (or throw) when the credential is invalid.

What you get for free

Once validate() returns, the library:

Looks up the identity (nest_auth_identities for provider='discord' + the returned userId) → logs the existing user in.
Creates a new NestAuthUser + identity when the identity is new and createUserIfNotExists is set — emitting UserRegisteredEvent.
Links to an existing account when the email matches — but only when emailVerified: true (the verified-email gate; social.requireVerifiedEmailForLinking).
Issues the session / JWT and emits UserLoggedInEvent.

When the client sends an auth code instead of a token

If your provider hands the frontend a one-time authorization code, exchange it for a token inside validate() and declare getRequiredFields() as ['code']:

getRequiredFields() { return ['code']; }
 
async validate(credentials: { code?: string }): Promise<AuthProviderUser | null> {
  const tokenResp = await fetch('https://discord.com/api/oauth2/token', {
    method: 'POST',
    body: new URLSearchParams({
      client_id: this.opts.clientId,
      client_secret: this.opts.clientSecret,
      code: credentials.code!,
      grant_type: 'authorization_code',
      redirect_uri: this.opts.redirectUri,
    }),
  }).then((r) => r.json());
 
  const me = await fetch('https://discord.com/api/users/@me', {
    headers: { Authorization: `Bearer ${tokenResp.access_token}` },
  }).then((r) => r.json());
 
  if (!me?.id) return null;
  return { userId: me.id, email: me.email, emailVerified: me.verified === true };
}

Enterprise SSO (SAML / OIDC / IdP groups)

The same shape covers enterprise SSO — verify the assertion/id-token in validate() (for OIDC, validate the id_token signature against the IdP's JWKS and return its sub/email) and return the user. To map IdP groups → Nest Auth roles, see the external role resolver recipe.

Common mistakes

Symptom	Cause
`providerName` unknown on login	You set `name` instead of `providerName`, or forgot to add the instance to `customAuthProviders`.
First social login returns `401 INVALID_CREDENTIALS`	New user without `createUserIfNotExists: true` — use `socialLogin()` or pass the flag.
Login 500s on Postgres: `invalid input syntax for type uuid` (or existing users get `INVALID_CREDENTIALS` on SQLite)	Your provider extends `BaseAuthProvider` but returns the provider's subject as `userId`. Extend `SocialAuthProvider` so the identity lookup uses `providerId`, not the `uuid` userId column.
Social identity didn't link to the existing email account	`emailVerified` wasn't `true`, and `social.requireVerifiedEmailForLinking` is on (default). Set `emailVerified` when the provider proves it.
`MISSING_REQUIRED_FIELDS`	The client didn't send a field named in `getRequiredFields()`.

Social / SSO Login — how the universal flow works.
Google OAuth — a built-in, by example.
Custom OAuth provider recipe — a short copy-paste version.
Link multiple providers to one account.

Custom OAuth / SSO Provider

On this page