From 0859917485dc14c512785beec0b0dcd2e31a7ee1 Mon Sep 17 00:00:00 2001 From: Elias Schneider Date: Tue, 3 Dec 2024 11:41:30 +0100 Subject: [PATCH] Deploy website - based on 168038eae72ef32f4619e8af2329ecd2e1e0d160 --- 404.html | 2 +- assets/js/3f2e6990.282c7570.js | 1 - assets/js/3f2e6990.ab92dfca.js | 1 + ...in.41e47575.js => runtime~main.98b93266.js} | 2 +- help-out/contribute/index.html | 2 +- help-out/translate/index.html | 2 +- index.html | 2 +- introduction/index.html | 2 +- setup/configuration/index.html | 2 +- setup/installation/index.html | 2 +- setup/integrations/index.html | 2 +- setup/oauth2login/index.html | 18 +++++++++--------- setup/upgrading/index.html | 2 +- 13 files changed, 20 insertions(+), 20 deletions(-) delete mode 100644 assets/js/3f2e6990.282c7570.js create mode 100644 assets/js/3f2e6990.ab92dfca.js rename assets/js/{runtime~main.41e47575.js => runtime~main.98b93266.js} (96%) diff --git a/404.html b/404.html index bfad235..2c09783 100644 --- a/404.html +++ b/404.html @@ -4,7 +4,7 @@ Pingvin Share - + diff --git a/assets/js/3f2e6990.282c7570.js b/assets/js/3f2e6990.282c7570.js deleted file mode 100644 index e273d4a..0000000 --- a/assets/js/3f2e6990.282c7570.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkpingvindocs=self.webpackChunkpingvindocs||[]).push([[819],{3403:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>d,default:()=>h,frontMatter:()=>t,metadata:()=>s,toc:()=>l});var o=i(4848),r=i(8453);const t={id:"oauth2login"},d="OAuth 2 Login Guide",s={id:"setup/oauth2login",title:"OAuth 2 Login Guide",description:"Config Built-in OAuth 2 Providers",source:"@site/docs/setup/oauth2login.md",sourceDirName:"setup",slug:"/setup/oauth2login",permalink:"/pingvin-share/setup/oauth2login",draft:!1,unlisted:!1,editUrl:"https://github.com/stonith404/pingvin-share/edit/main/docs/docs/setup/oauth2login.md",tags:[],version:"current",frontMatter:{id:"oauth2login"},sidebar:"docsSidebar",previous:{title:"Integrations",permalink:"/pingvin-share/setup/integrations"},next:{title:"Upgrading",permalink:"/pingvin-share/setup/upgrading"}},c={},l=[{value:"Config Built-in OAuth 2 Providers",id:"config-built-in-oauth-2-providers",level:2},{value:"GitHub",id:"github",level:3},{value:"Google",id:"google",level:3},{value:"Microsoft",id:"microsoft",level:3},{value:"Discord",id:"discord",level:3},{value:"OpenID Connect",id:"openid-connect",level:3},{value:"Custom your OAuth 2 Provider",id:"custom-your-oauth-2-provider",level:2},{value:"1. Create config",id:"1-create-config",level:3},{value:"2. Create provider class",id:"2-create-provider-class",level:3},{value:"Generic OpenID Connect",id:"generic-openid-connect",level:4},{value:"OAuth 2",id:"oauth-2",level:4},{value:"3. Register provider",id:"3-register-provider",level:3},{value:"4. Add frontend icon",id:"4-add-frontend-icon",level:3},{value:"5. Add i18n text",id:"5-add-i18n-text",level:3}];function a(e){const n={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"oauth-2-login-guide",children:"OAuth 2 Login Guide"})}),"\n",(0,o.jsx)(n.h2,{id:"config-built-in-oauth-2-providers",children:"Config Built-in OAuth 2 Providers"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#github",children:"GitHub"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#google",children:"Google"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#microsoft",children:"Microsoft"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#discord",children:"Discord"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#openid-connect",children:"OpenID Connect"})}),"\n"]}),"\n",(0,o.jsx)(n.h3,{id:"github",children:"GitHub"}),"\n",(0,o.jsxs)(n.p,{children:["Please follow the ",(0,o.jsx)(n.a,{href:"https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app",children:"official guide"})," to create an OAuth app."]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URL: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/github"})]}),"\n",(0,o.jsx)(n.h3,{id:"google",children:"Google"}),"\n",(0,o.jsxs)(n.p,{children:["Please follow the ",(0,o.jsx)(n.a,{href:"https://developers.google.com/identity/protocols/oauth2/web-server#prerequisites",children:"official guide"})," to create an OAuth 2.0 App."]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URL: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/google"})]}),"\n",(0,o.jsx)(n.h3,{id:"microsoft",children:"Microsoft"}),"\n",(0,o.jsxs)(n.p,{children:["Please follow the ",(0,o.jsx)(n.a,{href:"https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app",children:"official guide"})," to register an application."]}),"\n",(0,o.jsxs)(n.blockquote,{children:["\n",(0,o.jsxs)(n.p,{children:["[!IMPORTANT] > ",(0,o.jsx)(n.strong,{children:"Microsoft Tenant"})," you set in the admin panel must match the ",(0,o.jsx)(n.strong,{children:"supported account types"})," you set in the Microsoft Entra admin center, otherwise the OAuth login will not work. Refer to the ",(0,o.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#find-your-apps-openid-configuration-document-uri",children:"official documentation"})," for more details."]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URL: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/microsoft"})]}),"\n",(0,o.jsx)(n.h3,{id:"discord",children:"Discord"}),"\n",(0,o.jsxs)(n.p,{children:["Create an application on ",(0,o.jsx)(n.a,{href:"https://discord.com/developers/applications",children:"Discord Developer Portal"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URL: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/discord"})]}),"\n",(0,o.jsx)(n.h3,{id:"openid-connect",children:"OpenID Connect"}),"\n",(0,o.jsxs)(n.p,{children:["Generic OpenID Connect provider is also supported, we have tested it on Keycloak, Authentik, Casdoor and ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pocket-id",children:"Pocket ID"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URI: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/oidc"})]}),"\n",(0,o.jsxs)(n.p,{children:["Post Logout Redirect URI: ",(0,o.jsx)(n.code,{children:"https://"})]}),"\n",(0,o.jsx)(n.h2,{id:"custom-your-oauth-2-provider",children:"Custom your OAuth 2 Provider"}),"\n",(0,o.jsx)(n.p,{children:"If our built-in providers don't meet your needs, you can create your own OAuth 2 provider."}),"\n",(0,o.jsx)(n.h3,{id:"1-create-config",children:"1. Create config"}),"\n",(0,o.jsxs)(n.p,{children:["Add your config (client id, client secret, etc.) in ",(0,o.jsx)(n.a,{href:"../backend/prisma/seed/config.seed.ts",children:(0,o.jsx)(n.code,{children:"config.seed.ts"})}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-ts",children:'const configVariables: ConfigVariables = {\n // ...\n oauth: {\n // ...\n "YOUR_PROVIDER_NAME-enabled": {\n type: "boolean",\n defaultValue: "false",\n },\n "YOUR_PROVIDER_NAME-clientId": {\n type: "string",\n defaultValue: "",\n },\n "YOUR_PROVIDER_NAME-clientSecret": {\n type: "string",\n defaultValue: "",\n obscured: true,\n },\n },\n};\n'})}),"\n",(0,o.jsx)(n.h3,{id:"2-create-provider-class",children:"2. Create provider class"}),"\n",(0,o.jsx)(n.h4,{id:"generic-openid-connect",children:"Generic OpenID Connect"}),"\n",(0,o.jsxs)(n.p,{children:["If your provider supports OpenID connect, it's extremely easy to extend ",(0,o.jsx)(n.a,{href:"../backend/src/oauth/provider/genericOidc.provider.ts",children:(0,o.jsx)(n.code,{children:"GenericOidcProvider"})})," to add a new OpenID Connect provider."]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.a,{href:"../backend/src/oauth/provider/google.provider.ts",children:"Google provider"})," and ",(0,o.jsx)(n.a,{href:"../backend/src/oauth/provider/microsoft.provider.ts",children:"Microsoft provider"})," are good examples."]}),"\n",(0,o.jsx)(n.p,{children:"Here are some discovery URIs for popular providers:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["Microsoft: ",(0,o.jsx)(n.code,{children:"https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Google: ",(0,o.jsx)(n.code,{children:"https://accounts.google.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Apple: ",(0,o.jsx)(n.code,{children:"https://appleid.apple.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Gitlab: ",(0,o.jsx)(n.code,{children:"https://gitlab.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Huawei: ",(0,o.jsx)(n.code,{children:"https://oauth-login.cloud.huawei.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Paypal: ",(0,o.jsx)(n.code,{children:"https://www.paypal.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Yahoo: ",(0,o.jsx)(n.code,{children:"https://api.login.yahoo.com/.well-known/openid-configuration"})]}),"\n"]}),"\n",(0,o.jsx)(n.h4,{id:"oauth-2",children:"OAuth 2"}),"\n",(0,o.jsxs)(n.p,{children:["If your provider only supports OAuth 2, you can implement ",(0,o.jsx)(n.a,{href:"../backend/src/oauth/provider/oauthProvider.interface.ts",children:(0,o.jsx)(n.code,{children:"OAuthProvider"})})," interface to add a new OAuth 2 provider."]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.a,{href:"../backend/src/oauth/provider/github.provider.ts",children:"GitHub provider"})," and ",(0,o.jsx)(n.a,{href:"../backend/src/oauth/provider/discord.provider.ts",children:"Discord provider"})," are good examples."]}),"\n",(0,o.jsx)(n.h3,{id:"3-register-provider",children:"3. Register provider"}),"\n",(0,o.jsxs)(n.p,{children:["Register your provider in ",(0,o.jsx)(n.a,{href:"../backend/src/oauth/oauth.module.ts",children:(0,o.jsx)(n.code,{children:"OAuthModule"})})," and ",(0,o.jsx)(n.a,{href:"../backend/src/oauth/dto/oauthSignIn.dto.ts",children:(0,o.jsx)(n.code,{children:"OAuthSignInDto"})}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-ts",children:'@Module({\n providers: [\n GitHubProvider,\n // your provider\n {\n provide: "OAUTH_PROVIDERS",\n useFactory(\n github: GitHubProvider /* your provider */\n ): Record> {\n return {\n github,\n /* your provider */\n };\n },\n inject: [GitHubProvider /* your provider */],\n },\n ],\n})\nexport class OAuthModule {}\n'})}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-ts",children:'export interface OAuthSignInDto {\n provider:\n | "github"\n | "google"\n | "microsoft"\n | "discord"\n | "oidc" /* your provider*/;\n providerId: string;\n providerUsername: string;\n email: string;\n}\n'})}),"\n",(0,o.jsx)(n.h3,{id:"4-add-frontend-icon",children:"4. Add frontend icon"}),"\n",(0,o.jsxs)(n.p,{children:["Add an icon in ",(0,o.jsx)(n.a,{href:"../frontend/src/utils/oauth.util.tsx",children:(0,o.jsx)(n.code,{children:"oauth.util.tsx"})}),"."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-tsx",children:"const getOAuthIcon = (provider: string) => {\n return {\n github: ,\n /* your provider */\n }[provider];\n};\n"})}),"\n",(0,o.jsx)(n.h3,{id:"5-add-i18n-text",children:"5. Add i18n text"}),"\n",(0,o.jsxs)(n.p,{children:["Add keys below to your i18n text in ",(0,o.jsx)(n.a,{href:"../frontend/src/i18n/translations/en-US.ts",children:"locale file"}),"."]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"signIn.oauth.YOUR_PROVIDER_NAME"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"account.card.oauth.YOUR_PROVIDER_NAME"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"admin.config.oauth.YOUR_PROVIDER_NAME-enabled"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"admin.config.oauth.YOUR_PROVIDER_NAME-client-id"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"admin.config.oauth.YOUR_PROVIDER_NAME-client-secret"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"error.param.provider_YOUR_PROVIDER_NAME"})}),"\n",(0,o.jsx)(n.li,{children:"Other config keys you defined in step 1"}),"\n"]}),"\n",(0,o.jsx)(n.p,{children:"Congratulations! \ud83c\udf89 You have successfully added a new OAuth 2 provider! Pull requests are welcome if you want to share your provider with others."})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(a,{...e})}):a(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>d,x:()=>s});var o=i(6540);const r={},t=o.createContext(r);function d(e){const n=o.useContext(t);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function s(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:d(e.components),o.createElement(t.Provider,{value:n},e.children)}}}]); \ No newline at end of file diff --git a/assets/js/3f2e6990.ab92dfca.js b/assets/js/3f2e6990.ab92dfca.js new file mode 100644 index 0000000..d93b583 --- /dev/null +++ b/assets/js/3f2e6990.ab92dfca.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkpingvindocs=self.webpackChunkpingvindocs||[]).push([[819],{3403:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>s,default:()=>a,frontMatter:()=>t,metadata:()=>d,toc:()=>l});var o=i(4848),r=i(8453);const t={id:"oauth2login"},s="OAuth 2 Login Guide",d={id:"setup/oauth2login",title:"OAuth 2 Login Guide",description:"Config Built-in OAuth 2 Providers",source:"@site/docs/setup/oauth2login.md",sourceDirName:"setup",slug:"/setup/oauth2login",permalink:"/pingvin-share/setup/oauth2login",draft:!1,unlisted:!1,editUrl:"https://github.com/stonith404/pingvin-share/edit/main/docs/docs/setup/oauth2login.md",tags:[],version:"current",frontMatter:{id:"oauth2login"},sidebar:"docsSidebar",previous:{title:"Integrations",permalink:"/pingvin-share/setup/integrations"},next:{title:"Upgrading",permalink:"/pingvin-share/setup/upgrading"}},c={},l=[{value:"Config Built-in OAuth 2 Providers",id:"config-built-in-oauth-2-providers",level:2},{value:"GitHub",id:"github",level:3},{value:"Google",id:"google",level:3},{value:"Microsoft",id:"microsoft",level:3},{value:"Discord",id:"discord",level:3},{value:"OpenID Connect",id:"openid-connect",level:3},{value:"Custom your OAuth 2 Provider",id:"custom-your-oauth-2-provider",level:2},{value:"1. Create config",id:"1-create-config",level:3},{value:"2. Create provider class",id:"2-create-provider-class",level:3},{value:"Generic OpenID Connect",id:"generic-openid-connect",level:4},{value:"OAuth 2",id:"oauth-2",level:4},{value:"3. Register provider",id:"3-register-provider",level:3},{value:"4. Add frontend icon",id:"4-add-frontend-icon",level:3},{value:"5. Add i18n text",id:"5-add-i18n-text",level:3}];function h(e){const n={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"oauth-2-login-guide",children:"OAuth 2 Login Guide"})}),"\n",(0,o.jsx)(n.h2,{id:"config-built-in-oauth-2-providers",children:"Config Built-in OAuth 2 Providers"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#github",children:"GitHub"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#google",children:"Google"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#microsoft",children:"Microsoft"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#discord",children:"Discord"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"#openid-connect",children:"OpenID Connect"})}),"\n"]}),"\n",(0,o.jsx)(n.h3,{id:"github",children:"GitHub"}),"\n",(0,o.jsxs)(n.p,{children:["Please follow the ",(0,o.jsx)(n.a,{href:"https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app",children:"official guide"})," to create an OAuth app."]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URL: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/github"})]}),"\n",(0,o.jsx)(n.h3,{id:"google",children:"Google"}),"\n",(0,o.jsxs)(n.p,{children:["Please follow the ",(0,o.jsx)(n.a,{href:"https://developers.google.com/identity/protocols/oauth2/web-server#prerequisites",children:"official guide"})," to create an OAuth 2.0 App."]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URL: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/google"})]}),"\n",(0,o.jsx)(n.h3,{id:"microsoft",children:"Microsoft"}),"\n",(0,o.jsxs)(n.p,{children:["Please follow the ",(0,o.jsx)(n.a,{href:"https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app",children:"official guide"})," to register an application."]}),"\n",(0,o.jsxs)(n.blockquote,{children:["\n",(0,o.jsxs)(n.p,{children:["[!IMPORTANT] > ",(0,o.jsx)(n.strong,{children:"Microsoft Tenant"})," you set in the admin panel must match the ",(0,o.jsx)(n.strong,{children:"supported account types"})," you set in the Microsoft Entra admin center, otherwise the OAuth login will not work. Refer to the ",(0,o.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#find-your-apps-openid-configuration-document-uri",children:"official documentation"})," for more details."]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URL: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/microsoft"})]}),"\n",(0,o.jsx)(n.h3,{id:"discord",children:"Discord"}),"\n",(0,o.jsxs)(n.p,{children:["Create an application on ",(0,o.jsx)(n.a,{href:"https://discord.com/developers/applications",children:"Discord Developer Portal"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URL: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/discord"})]}),"\n",(0,o.jsx)(n.h3,{id:"openid-connect",children:"OpenID Connect"}),"\n",(0,o.jsxs)(n.p,{children:["Generic OpenID Connect provider is also supported, we have tested it on Keycloak, Authentik, Casdoor and ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pocket-id",children:"Pocket ID"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["Redirect URI: ",(0,o.jsx)(n.code,{children:"https:///api/oauth/callback/oidc"})]}),"\n",(0,o.jsxs)(n.p,{children:["Post Logout Redirect URI: ",(0,o.jsx)(n.code,{children:"https://"})]}),"\n",(0,o.jsx)(n.h2,{id:"custom-your-oauth-2-provider",children:"Custom your OAuth 2 Provider"}),"\n",(0,o.jsx)(n.p,{children:"If our built-in providers don't meet your needs, you can create your own OAuth 2 provider."}),"\n",(0,o.jsx)(n.h3,{id:"1-create-config",children:"1. Create config"}),"\n",(0,o.jsxs)(n.p,{children:["Add your config (client id, client secret, etc.) in ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/backend/prisma/seed/config.seed.ts",children:(0,o.jsx)(n.code,{children:"config.seed.ts"})}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-ts",children:'const configVariables: ConfigVariables = {\n // ...\n oauth: {\n // ...\n "YOUR_PROVIDER_NAME-enabled": {\n type: "boolean",\n defaultValue: "false",\n },\n "YOUR_PROVIDER_NAME-clientId": {\n type: "string",\n defaultValue: "",\n },\n "YOUR_PROVIDER_NAME-clientSecret": {\n type: "string",\n defaultValue: "",\n obscured: true,\n },\n },\n};\n'})}),"\n",(0,o.jsx)(n.h3,{id:"2-create-provider-class",children:"2. Create provider class"}),"\n",(0,o.jsx)(n.h4,{id:"generic-openid-connect",children:"Generic OpenID Connect"}),"\n",(0,o.jsxs)(n.p,{children:["If your provider supports OpenID connect, it's extremely easy to extend ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/backend/src/oauth/provider/genericOidc.provider.ts",children:(0,o.jsx)(n.code,{children:"GenericOidcProvider"})})," to add a new OpenID Connect provider."]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/backend/src/oauth/provider/google.provider.ts",children:"Google provider"})," and ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/backend/src/oauth/provider/microsoft.provider.ts",children:"Microsoft provider"})," are good examples."]}),"\n",(0,o.jsx)(n.p,{children:"Here are some discovery URIs for popular providers:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["Microsoft: ",(0,o.jsx)(n.code,{children:"https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Google: ",(0,o.jsx)(n.code,{children:"https://accounts.google.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Apple: ",(0,o.jsx)(n.code,{children:"https://appleid.apple.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Gitlab: ",(0,o.jsx)(n.code,{children:"https://gitlab.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Huawei: ",(0,o.jsx)(n.code,{children:"https://oauth-login.cloud.huawei.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Paypal: ",(0,o.jsx)(n.code,{children:"https://www.paypal.com/.well-known/openid-configuration"})]}),"\n",(0,o.jsxs)(n.li,{children:["Yahoo: ",(0,o.jsx)(n.code,{children:"https://api.login.yahoo.com/.well-known/openid-configuration"})]}),"\n"]}),"\n",(0,o.jsx)(n.h4,{id:"oauth-2",children:"OAuth 2"}),"\n",(0,o.jsxs)(n.p,{children:["If your provider only supports OAuth 2, you can implement ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/backend/src/oauth/provider/oauthProvider.interface.ts",children:(0,o.jsx)(n.code,{children:"OAuthProvider"})})," interface to add a new OAuth 2 provider."]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/backend/src/oauth/provider/github.provider.ts",children:"GitHub provider"})," and ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/backend/src/oauth/provider/discord.provider.ts",children:"Discord provider"})," are good examples."]}),"\n",(0,o.jsx)(n.h3,{id:"3-register-provider",children:"3. Register provider"}),"\n",(0,o.jsxs)(n.p,{children:["Register your provider in ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/backend/src/oauth/oauth.module.ts",children:(0,o.jsx)(n.code,{children:"OAuthModule"})})," and ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/backend/src/oauth/dto/oauthSignIn.dto.ts",children:(0,o.jsx)(n.code,{children:"OAuthSignInDto"})}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-ts",children:'@Module({\n providers: [\n GitHubProvider,\n // your provider\n {\n provide: "OAUTH_PROVIDERS",\n useFactory(\n github: GitHubProvider /* your provider */\n ): Record> {\n return {\n github,\n /* your provider */\n };\n },\n inject: [GitHubProvider /* your provider */],\n },\n ],\n})\nexport class OAuthModule {}\n'})}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-ts",children:'export interface OAuthSignInDto {\n provider:\n | "github"\n | "google"\n | "microsoft"\n | "discord"\n | "oidc" /* your provider*/;\n providerId: string;\n providerUsername: string;\n email: string;\n}\n'})}),"\n",(0,o.jsx)(n.h3,{id:"4-add-frontend-icon",children:"4. Add frontend icon"}),"\n",(0,o.jsxs)(n.p,{children:["Add an icon in ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/frontend/src/utils/oauth.util.tsx",children:(0,o.jsx)(n.code,{children:"oauth.util.tsx"})}),"."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-tsx",children:"const getOAuthIcon = (provider: string) => {\n return {\n github: ,\n /* your provider */\n }[provider];\n};\n"})}),"\n",(0,o.jsx)(n.h3,{id:"5-add-i18n-text",children:"5. Add i18n text"}),"\n",(0,o.jsxs)(n.p,{children:["Add keys below to your i18n text in ",(0,o.jsx)(n.a,{href:"https://github.com/stonith404/pingvin-share/blob/main/frontend/src/i18n/translations/en-US.ts",children:"locale file"}),"."]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"signIn.oauth.YOUR_PROVIDER_NAME"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"account.card.oauth.YOUR_PROVIDER_NAME"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"admin.config.oauth.YOUR_PROVIDER_NAME-enabled"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"admin.config.oauth.YOUR_PROVIDER_NAME-client-id"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"admin.config.oauth.YOUR_PROVIDER_NAME-client-secret"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.code,{children:"error.param.provider_YOUR_PROVIDER_NAME"})}),"\n",(0,o.jsx)(n.li,{children:"Other config keys you defined in step 1"}),"\n"]}),"\n",(0,o.jsx)(n.p,{children:"Congratulations! \ud83c\udf89 You have successfully added a new OAuth 2 provider! Pull requests are welcome if you want to share your provider with others."})]})}function a(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(h,{...e})}):h(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>s,x:()=>d});var o=i(6540);const r={},t=o.createContext(r);function s(e){const n=o.useContext(t);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:s(e.components),o.createElement(t.Provider,{value:n},e.children)}}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.41e47575.js b/assets/js/runtime~main.98b93266.js similarity index 96% rename from assets/js/runtime~main.41e47575.js rename to assets/js/runtime~main.98b93266.js index f2727ca..b9c45c8 100644 --- a/assets/js/runtime~main.41e47575.js +++ b/assets/js/runtime~main.98b93266.js @@ -1 +1 @@ -(()=>{"use strict";var e,t,r,a,o,n={},i={};function d(e){var t=i[e];if(void 0!==t)return t.exports;var r=i[e]={id:e,loaded:!1,exports:{}};return n[e].call(r.exports,r,r.exports,d),r.loaded=!0,r.exports}d.m=n,d.c=i,e=[],d.O=(t,r,a,o)=>{if(!r){var n=1/0;for(u=0;u=o)&&Object.keys(d.O).every((e=>d.O[e](r[c])))?r.splice(c--,1):(i=!1,o0&&e[u-1][2]>o;u--)e[u]=e[u-1];e[u]=[r,a,o]},d.n=e=>{var t=e&&e.__esModule?()=>e.default:()=>e;return d.d(t,{a:t}),t},r=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,d.t=function(e,a){if(1&a&&(e=this(e)),8&a)return e;if("object"==typeof e&&e){if(4&a&&e.__esModule)return e;if(16&a&&"function"==typeof e.then)return e}var o=Object.create(null);d.r(o);var n={};t=t||[null,r({}),r([]),r(r)];for(var i=2&a&&e;"object"==typeof i&&!~t.indexOf(i);i=r(i))Object.getOwnPropertyNames(i).forEach((t=>n[t]=()=>e[t]));return n.default=()=>e,d.d(o,n),o},d.d=(e,t)=>{for(var r in t)d.o(t,r)&&!d.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},d.f={},d.e=e=>Promise.all(Object.keys(d.f).reduce(((t,r)=>(d.f[r](e,t),t)),[])),d.u=e=>"assets/js/"+({48:"a94703ab",98:"a7bd4aaa",99:"a8c31fc1",126:"d131c913",235:"a7456010",361:"3205bd6d",401:"17896441",537:"a0d20388",583:"1df93b7f",647:"5e95c892",723:"91b3cb8d",742:"aba21aa0",819:"3f2e6990",862:"7cbc9cee",863:"63b14240",899:"a09c2993"}[e]||e)+"."+{48:"78fc18a9",98:"3d51fbb4",99:"c26fc8a4",126:"815d9a2f",235:"91f0b3e9",237:"f947e7e3",361:"ecb21caf",401:"402e11f1",537:"9147194f",583:"2d1029fa",647:"59168106",723:"073a48e1",742:"ad2b3c84",819:"282c7570",862:"af2bf09d",863:"e94c1db4",899:"e0cc7812"}[e]+".js",d.miniCssF=e=>{},d.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),d.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),a={},o="pingvindocs:",d.l=(e,t,r,n)=>{if(a[e])a[e].push(t);else{var i,c;if(void 0!==r)for(var f=document.getElementsByTagName("script"),u=0;u{i.onerror=i.onload=null,clearTimeout(s);var o=a[e];if(delete a[e],i.parentNode&&i.parentNode.removeChild(i),o&&o.forEach((e=>e(r))),t)return t(r)},s=setTimeout(b.bind(null,void 0,{type:"timeout",target:i}),12e4);i.onerror=b.bind(null,i.onerror),i.onload=b.bind(null,i.onload),c&&document.head.appendChild(i)}},d.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},d.p="/pingvin-share/",d.gca=function(e){return e={17896441:"401",a94703ab:"48",a7bd4aaa:"98",a8c31fc1:"99",d131c913:"126",a7456010:"235","3205bd6d":"361",a0d20388:"537","1df93b7f":"583","5e95c892":"647","91b3cb8d":"723",aba21aa0:"742","3f2e6990":"819","7cbc9cee":"862","63b14240":"863",a09c2993:"899"}[e]||e,d.p+d.u(e)},(()=>{var e={354:0,869:0};d.f.j=(t,r)=>{var a=d.o(e,t)?e[t]:void 0;if(0!==a)if(a)r.push(a[2]);else if(/^(354|869)$/.test(t))e[t]=0;else{var o=new Promise(((r,o)=>a=e[t]=[r,o]));r.push(a[2]=o);var n=d.p+d.u(t),i=new Error;d.l(n,(r=>{if(d.o(e,t)&&(0!==(a=e[t])&&(e[t]=void 0),a)){var o=r&&("load"===r.type?"missing":r.type),n=r&&r.target&&r.target.src;i.message="Loading chunk "+t+" failed.\n("+o+": "+n+")",i.name="ChunkLoadError",i.type=o,i.request=n,a[1](i)}}),"chunk-"+t,t)}},d.O.j=t=>0===e[t];var t=(t,r)=>{var a,o,n=r[0],i=r[1],c=r[2],f=0;if(n.some((t=>0!==e[t]))){for(a in i)d.o(i,a)&&(d.m[a]=i[a]);if(c)var u=c(d)}for(t&&t(r);f{"use strict";var e,t,r,a,o,n={},i={};function d(e){var t=i[e];if(void 0!==t)return t.exports;var r=i[e]={id:e,loaded:!1,exports:{}};return n[e].call(r.exports,r,r.exports,d),r.loaded=!0,r.exports}d.m=n,d.c=i,e=[],d.O=(t,r,a,o)=>{if(!r){var n=1/0;for(u=0;u=o)&&Object.keys(d.O).every((e=>d.O[e](r[c])))?r.splice(c--,1):(i=!1,o0&&e[u-1][2]>o;u--)e[u]=e[u-1];e[u]=[r,a,o]},d.n=e=>{var t=e&&e.__esModule?()=>e.default:()=>e;return d.d(t,{a:t}),t},r=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,d.t=function(e,a){if(1&a&&(e=this(e)),8&a)return e;if("object"==typeof e&&e){if(4&a&&e.__esModule)return e;if(16&a&&"function"==typeof e.then)return e}var o=Object.create(null);d.r(o);var n={};t=t||[null,r({}),r([]),r(r)];for(var i=2&a&&e;"object"==typeof i&&!~t.indexOf(i);i=r(i))Object.getOwnPropertyNames(i).forEach((t=>n[t]=()=>e[t]));return n.default=()=>e,d.d(o,n),o},d.d=(e,t)=>{for(var r in t)d.o(t,r)&&!d.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},d.f={},d.e=e=>Promise.all(Object.keys(d.f).reduce(((t,r)=>(d.f[r](e,t),t)),[])),d.u=e=>"assets/js/"+({48:"a94703ab",98:"a7bd4aaa",99:"a8c31fc1",126:"d131c913",235:"a7456010",361:"3205bd6d",401:"17896441",537:"a0d20388",583:"1df93b7f",647:"5e95c892",723:"91b3cb8d",742:"aba21aa0",819:"3f2e6990",862:"7cbc9cee",863:"63b14240",899:"a09c2993"}[e]||e)+"."+{48:"78fc18a9",98:"3d51fbb4",99:"c26fc8a4",126:"815d9a2f",235:"91f0b3e9",237:"f947e7e3",361:"ecb21caf",401:"402e11f1",537:"9147194f",583:"2d1029fa",647:"59168106",723:"073a48e1",742:"ad2b3c84",819:"ab92dfca",862:"af2bf09d",863:"e94c1db4",899:"e0cc7812"}[e]+".js",d.miniCssF=e=>{},d.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),d.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),a={},o="pingvindocs:",d.l=(e,t,r,n)=>{if(a[e])a[e].push(t);else{var i,c;if(void 0!==r)for(var f=document.getElementsByTagName("script"),u=0;u{i.onerror=i.onload=null,clearTimeout(s);var o=a[e];if(delete a[e],i.parentNode&&i.parentNode.removeChild(i),o&&o.forEach((e=>e(r))),t)return t(r)},s=setTimeout(b.bind(null,void 0,{type:"timeout",target:i}),12e4);i.onerror=b.bind(null,i.onerror),i.onload=b.bind(null,i.onload),c&&document.head.appendChild(i)}},d.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},d.p="/pingvin-share/",d.gca=function(e){return e={17896441:"401",a94703ab:"48",a7bd4aaa:"98",a8c31fc1:"99",d131c913:"126",a7456010:"235","3205bd6d":"361",a0d20388:"537","1df93b7f":"583","5e95c892":"647","91b3cb8d":"723",aba21aa0:"742","3f2e6990":"819","7cbc9cee":"862","63b14240":"863",a09c2993:"899"}[e]||e,d.p+d.u(e)},(()=>{var e={354:0,869:0};d.f.j=(t,r)=>{var a=d.o(e,t)?e[t]:void 0;if(0!==a)if(a)r.push(a[2]);else if(/^(354|869)$/.test(t))e[t]=0;else{var o=new Promise(((r,o)=>a=e[t]=[r,o]));r.push(a[2]=o);var n=d.p+d.u(t),i=new Error;d.l(n,(r=>{if(d.o(e,t)&&(0!==(a=e[t])&&(e[t]=void 0),a)){var o=r&&("load"===r.type?"missing":r.type),n=r&&r.target&&r.target.src;i.message="Loading chunk "+t+" failed.\n("+o+": "+n+")",i.name="ChunkLoadError",i.type=o,i.request=n,a[1](i)}}),"chunk-"+t,t)}},d.O.j=t=>0===e[t];var t=(t,r)=>{var a,o,n=r[0],i=r[1],c=r[2],f=0;if(n.some((t=>0!==e[t]))){for(a in i)d.o(i,a)&&(d.m[a]=i[a]);if(c)var u=c(d)}for(t&&t(r);f Contributing | Pingvin Share - + diff --git a/help-out/translate/index.html b/help-out/translate/index.html index e31af78..a067b79 100644 --- a/help-out/translate/index.html +++ b/help-out/translate/index.html @@ -4,7 +4,7 @@ Translating | Pingvin Share - + diff --git a/index.html b/index.html index 70b5f7b..394de8b 100644 --- a/index.html +++ b/index.html @@ -4,7 +4,7 @@ Pingvin Share - + diff --git a/introduction/index.html b/introduction/index.html index 96b3764..dcbbb67 100644 --- a/introduction/index.html +++ b/introduction/index.html @@ -4,7 +4,7 @@ Introduction | Pingvin Share - + diff --git a/setup/configuration/index.html b/setup/configuration/index.html index e119318..8181ccc 100644 --- a/setup/configuration/index.html +++ b/setup/configuration/index.html @@ -4,7 +4,7 @@ Configuration | Pingvin Share - + diff --git a/setup/installation/index.html b/setup/installation/index.html index 3bd8177..21f8d3e 100644 --- a/setup/installation/index.html +++ b/setup/installation/index.html @@ -4,7 +4,7 @@ Installation | Pingvin Share - + diff --git a/setup/integrations/index.html b/setup/integrations/index.html index d3bcc66..bf54bb6 100644 --- a/setup/integrations/index.html +++ b/setup/integrations/index.html @@ -4,7 +4,7 @@ Integrations | Pingvin Share - + diff --git a/setup/oauth2login/index.html b/setup/oauth2login/index.html index 8d02eea..d8ddf49 100644 --- a/setup/oauth2login/index.html +++ b/setup/oauth2login/index.html @@ -4,7 +4,7 @@ OAuth 2 Login Guide | Pingvin Share - + @@ -39,12 +39,12 @@

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:

+

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.

+

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
    • @@ -56,17 +56,17 @@
  • 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.

+

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:

+

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.

+

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.

+

Add keys below to your i18n text in locale file.

  • signIn.oauth.YOUR_PROVIDER_NAME
  • account.card.oauth.YOUR_PROVIDER_NAME
    • diff --git a/setup/upgrading/index.html b/setup/upgrading/index.html index 2baf09b..acc368b 100644 --- a/setup/upgrading/index.html +++ b/setup/upgrading/index.html @@ -4,7 +4,7 @@ Upgrading | Pingvin Share - +