pingvin-share/docs/oauth2-guide.md

OAuth 2 Login Guide

Config Built-in OAuth 2 Providers

• GitHub
• Google
• Microsoft
• Discord
• OpenID Connect

GitHub

Please follow the official guide to create an OAuth app.

Redirect URL: https://<your-domain>/api/oauth/callback/github

Google

Please follow the official guide to create an OAuth 2.0 App.

Redirect URL: https://<your-domain>/api/oauth/callback/google

Microsoft

Please follow the official guide to register an application.

Important

Microsoft Tenant you set in the admin panel must match the supported account types you set in the Microsoft Entra admin center, otherwise the OAuth login will not work. Refer to the official documentation for more details.

Redirect URL: https://<your-domain>/api/oauth/callback/microsoft

Discord

Create an application on Discord Developer Portal.

Redirect URL: https://<your-domain>/api/oauth/callback/discord

OpenID Connect

Generic OpenID Connect provider is also supported, we have tested it on Keycloak, Authentik and Casdoor.

Redirect URL: https://<your-domain>/api/oauth/callback/oidc

Custom your OAuth 2 Provider

If our built-in providers don't meet your needs, you can create your own OAuth 2 provider.

1. Create config

Add your config (client id, client secret, etc.) in config.seed.ts:

const configVariables: ConfigVariables = {
  // ...
  oauth: {
    // ...
    "YOUR_PROVIDER_NAME-enabled": {
      type: "boolean",
      defaultValue: "false",
    },
    "YOUR_PROVIDER_NAME-clientId": {
      type: "string",
      defaultValue: "",
    },
    "YOUR_PROVIDER_NAME-clientSecret": {
      type: "string",
      defaultValue: "",
      obscured: true,
    },
  }
}

2. Create provider class

Generic OpenID Connect

If your provider supports OpenID connect, it's extremely easy to extend GenericOidcProvider to add a new OpenID Connect provider.

The Google provider and Microsoft provider are good examples.

Here are some discovery URIs for popular providers:

• Microsoft: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
• Google: https://accounts.google.com/.well-known/openid-configuration
• Apple: https://appleid.apple.com/.well-known/openid-configuration
• Gitlab: https://gitlab.com/.well-known/openid-configuration
• Huawei: https://oauth-login.cloud.huawei.com/.well-known/openid-configuration
• Paypal: https://www.paypal.com/.well-known/openid-configuration
• Yahoo: https://api.login.yahoo.com/.well-known/openid-configuration

OAuth 2

If your provider only supports OAuth 2, you can implement OAuthProvider interface to add a new OAuth 2 provider.

The GitHub provider and Discord provider are good examples.

3. Register provider

Register your provider in OAuthModule and OAuthSignInDto:

@Module({
  providers: [
    GitHubProvider,
    // your provider
    {
      provide: "OAUTH_PROVIDERS",
      useFactory(github: GitHubProvider, /* your provider */): Record<string, OAuthProvider<unknown>> {
        return {
          github,
          /* your provider */
        };
      },
      inject: [GitHubProvider, /* your provider */],
    },
  ],
})
export class OAuthModule {
}

export interface OAuthSignInDto {
  provider: 'github' | 'google' | 'microsoft' | 'discord' | 'oidc' /* your provider*/;
  providerId: string;
  providerUsername: string;
  email: string;
}

4. Add frontend icon

Add an icon in oauth.util.tsx.

const getOAuthIcon = (provider: string) => {
  return {
    'github': <SiGithub />,
    /* your provider */
  }[provider];
}

5. Add i18n text

Add keys below to your i18n text in locale file.

• signIn.oauth.YOUR_PROVIDER_NAME
• account.card.oauth.YOUR_PROVIDER_NAME
• admin.config.oauth.YOUR_PROVIDER_NAME-enabled
• admin.config.oauth.YOUR_PROVIDER_NAME-client-id
• admin.config.oauth.YOUR_PROVIDER_NAME-client-secret
• error.param.provider_YOUR_PROVIDER_NAME
• Other config keys you defined in step 1

Congratulations! 🎉 You have successfully added a new OAuth 2 provider! Pull requests are welcome if you want to share your provider with others.