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.

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 and Authentik.

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

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,
          google,
          oidc,
        };
      },
      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
• 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.