From 523fcbab716b11ed1ad9accde56951d83d54fb1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Fri, 28 Apr 2023 16:52:00 +0200 Subject: [PATCH 1/9] fix(docs): document Callback URL for every provider --- docs/static/img/providers/authentik.svg | 1 + packages/core/src/providers/42-school.ts | 20 +++-- packages/core/src/providers/apple.ts | 13 +++- packages/core/src/providers/asgardeo.ts | 13 +++- packages/core/src/providers/atlassian.ts | 13 +++- packages/core/src/providers/auth0.ts | 13 +++- packages/core/src/providers/authentik.ts | 20 +++-- packages/core/src/providers/azure-ad-b2c.ts | 7 +- packages/core/src/providers/azure-ad.ts | 39 ++++++---- packages/core/src/providers/battlenet.ts | 16 ++-- packages/core/src/providers/beyondidentity.ts | 7 +- packages/core/src/providers/box.ts | 19 +++-- packages/core/src/providers/boxyhq-saml.ts | 36 +++++---- packages/core/src/providers/bungie.ts | 77 ++++++++++--------- packages/core/src/providers/cognito.ts | 19 +++-- packages/core/src/providers/coinbase.ts | 20 +++-- packages/core/src/providers/discord.ts | 15 ++-- packages/core/src/providers/dropbox.ts | 18 +++-- .../src/providers/duende-identity-server6.ts | 25 +++--- packages/core/src/providers/eveonline.ts | 17 ++-- packages/core/src/providers/facebook.ts | 25 +++--- packages/core/src/providers/faceit.ts | 18 +++-- packages/core/src/providers/foursquare.ts | 22 ++++-- packages/core/src/providers/freshbooks.ts | 18 +++-- packages/core/src/providers/fusionauth.ts | 23 +++--- packages/core/src/providers/github.ts | 23 ++++-- packages/core/src/providers/gitlab.ts | 19 +++-- packages/core/src/providers/google.ts | 39 ++++++---- packages/core/src/providers/hubspot.ts | 15 ++-- .../core/src/providers/identity-server4.ts | 19 +++-- packages/core/src/providers/instagram.ts | 22 ++++-- packages/core/src/providers/kakao.ts | 17 ++-- packages/core/src/providers/keycloak.ts | 29 ++++--- packages/core/src/providers/line.ts | 17 ++-- packages/core/src/providers/linkedin.ts | 15 ++-- packages/core/src/providers/mailchimp.ts | 18 +++-- packages/core/src/providers/mailru.ts | 18 +++-- packages/core/src/providers/mattermost.ts | 23 +++--- packages/core/src/providers/medium.ts | 18 +++-- packages/core/src/providers/naver.ts | 15 ++-- packages/core/src/providers/netlify.ts | 18 +++-- packages/core/src/providers/notion.ts | 9 +-- packages/core/src/providers/okta.ts | 16 ++-- packages/core/src/providers/onelogin.ts | 16 ++-- packages/core/src/providers/osso.ts | 15 ++-- packages/core/src/providers/osu.ts | 15 ++-- packages/core/src/providers/patreon.ts | 15 ++-- packages/core/src/providers/pinterest.ts | 23 +++--- packages/core/src/providers/pipedrive.ts | 15 ++-- packages/core/src/providers/reddit.ts | 15 ++-- packages/core/src/providers/salesforce.ts | 15 ++-- packages/core/src/providers/slack.ts | 17 ++-- packages/core/src/providers/spotify.ts | 15 ++-- packages/core/src/providers/strava.ts | 15 ++-- packages/core/src/providers/todoist.ts | 15 ++-- packages/core/src/providers/trakt.ts | 19 +++-- packages/core/src/providers/twitch.ts | 21 +++-- packages/core/src/providers/twitter.ts | 29 ++++--- packages/core/src/providers/united-effects.ts | 22 +++--- packages/core/src/providers/vk.ts | 15 ++-- packages/core/src/providers/wikimedia.ts | 26 ++++--- packages/core/src/providers/wordpress.ts | 15 ++-- packages/core/src/providers/workos.ts | 35 +++++---- packages/core/src/providers/yandex.ts | 5 +- packages/core/src/providers/zitadel.ts | 21 +++-- packages/core/src/providers/zoho.ts | 15 ++-- packages/core/src/providers/zoom.ts | 15 ++-- 67 files changed, 808 insertions(+), 485 deletions(-) create mode 100644 docs/static/img/providers/authentik.svg diff --git a/docs/static/img/providers/authentik.svg b/docs/static/img/providers/authentik.svg new file mode 100644 index 00000000..517eb179 --- /dev/null +++ b/docs/static/img/providers/authentik.svg @@ -0,0 +1 @@ + diff --git a/packages/core/src/providers/42-school.ts b/packages/core/src/providers/42-school.ts index 59ce0a63..76f0e519 100644 --- a/packages/core/src/providers/42-school.ts +++ b/packages/core/src/providers/42-school.ts @@ -1,13 +1,11 @@ /** - *
+ *
* Built-in 42School integration. - * TODO: SVG logo * * * *
* - * --- * @module providers/42-school */ import type { OAuthConfig, OAuthUserConfig } from "./index.js" @@ -167,9 +165,15 @@ export interface FortyTwoProfile extends UserData, Record { /** * Add 42School login to your page. * - * @example + * ### Setup * - * ```js + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/42-school + * ``` + * + * #### Configuration + *```js * import Auth from "@auth/core" * import 42School from "@auth/core/providers/42-school" * @@ -179,13 +183,13 @@ export interface FortyTwoProfile extends UserData, Record { * }) * ``` * - * ## Resources + * ### Resources * * - [42School OAuth documentation](https://api.intra.42.fr/apidoc/guides/web_application_flow) * - * ## Notes + * ### Notes + * * - * * :::note * 42 returns a field on `Account` called `created_at` which is a number. See the [docs](https://api.intra.42.fr/apidoc/guides/getting_started#make-basic-requests). Make sure to add this field to your database schema, in case if you are using an [Adapter](https://authjs.dev/reference/adapters). * ::: diff --git a/packages/core/src/providers/apple.ts b/packages/core/src/providers/apple.ts index ed71dcc7..9391cf4c 100644 --- a/packages/core/src/providers/apple.ts +++ b/packages/core/src/providers/apple.ts @@ -97,7 +97,14 @@ export interface AppleProfile extends Record { } /** - * ## Setup + * ### Setup + * + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/apple + * ``` + * + * #### Configuration * * Import the provider and configure it in your **Auth.js** initialization file: * @@ -115,14 +122,14 @@ export interface AppleProfile extends Record { * }) * ``` * - * ## Resources + * ### Resources * * - Sign in with Apple [Overview](https://developer.apple.com/sign-in-with-apple/get-started/) * - Sign in with Apple [REST API](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api) * - [How to retrieve](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api/authenticating_users_with_sign_in_with_apple#3383773) the user's information from Apple ID servers * - [Learn more about OAuth](https://authjs.dev/concepts/oauth) - * ## Notes + * ### Notes * * The Apple provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/apple.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options). * diff --git a/packages/core/src/providers/asgardeo.ts b/packages/core/src/providers/asgardeo.ts index 2acf5514..2b8fb4db 100644 --- a/packages/core/src/providers/asgardeo.ts +++ b/packages/core/src/providers/asgardeo.ts @@ -35,7 +35,14 @@ export interface AsgardeoProfile extends Record { /** * - * ## Setup + * ### Setup + * + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/asgardeo + * ``` + * + * #### Configuration * * Import the provider and configure it in your **Auth.js** initialization file: * @@ -75,12 +82,12 @@ export interface AsgardeoProfile extends Record { * ASGARDEO_ISSUER="Copy the issuer url from the info tab here" * ``` * - * ## Resources + * ### Resources * * - [Asgardeo - Authentication Guide](https://wso2.com/asgardeo/docs/guides/authentication) * - [Learn more about OAuth](https://authjs.dev/concepts/oauth) * - * ## Notes + * ### Notes * * The Asgardeo provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/asgardeo.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options). * diff --git a/packages/core/src/providers/atlassian.ts b/packages/core/src/providers/atlassian.ts index 38daa260..c3f4daef 100644 --- a/packages/core/src/providers/atlassian.ts +++ b/packages/core/src/providers/atlassian.ts @@ -33,7 +33,14 @@ export interface AtlassianProfile extends Record { } /** - * ## Setup + * ### Setup + * + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/atlassian + * ``` + * + * #### Configuration * * Import the provider and configure it in your **Auth.js** initialization file: * @@ -51,11 +58,11 @@ export interface AtlassianProfile extends Record { * }) * ``` * - * ## Resources + * ### Resources * * - [Atlassian docs](https://developer.atlassian.com/server/jira/platform/oauth/) * - * ## Notes + * ### Notes * * The Atlassian provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/atlassian.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options). * diff --git a/packages/core/src/providers/auth0.ts b/packages/core/src/providers/auth0.ts index cf0aa8ba..956ddca3 100644 --- a/packages/core/src/providers/auth0.ts +++ b/packages/core/src/providers/auth0.ts @@ -75,7 +75,14 @@ export interface Auth0Profile extends Record { } /** - * ## Setup + * ### Setup + * + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/auth0 + * ``` + * + * #### Configuration * * Import the provider and configure it in your **Auth.js** initialization file: * @@ -93,11 +100,11 @@ export interface Auth0Profile extends Record { * }) * ``` * - * ## Resources + * ### Resources * * - [Auth0 docs](https://auth0.com/docs/authenticate) * - * ## Notes + * ### Notes * * The Auth0 provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/auth0.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options). * diff --git a/packages/core/src/providers/authentik.ts b/packages/core/src/providers/authentik.ts index 948c6a9c..767998bb 100644 --- a/packages/core/src/providers/authentik.ts +++ b/packages/core/src/providers/authentik.ts @@ -1,13 +1,11 @@ /** - *
+ *
* Built-in Authentik integration. - * TODO: SVG logo * * * *
* - * --- * @module providers/authentik */ import type { OAuthConfig, OAuthUserConfig } from "./index.js" @@ -36,9 +34,15 @@ export interface AuthentikProfile extends Record { /** * Add Authentik login to your page. * - * @example + * ### Setup * - * ```js + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/authentik + * ``` + * + * #### Configuration + *```js * import Auth from "@auth/core" * import Authentik from "@auth/core/providers/authentik" * @@ -47,16 +51,16 @@ export interface AuthentikProfile extends Record { * providers: [Authentik({ clientId: AUTHENTIK_CLIENT_ID, clientSecret: AUTHENTIK_CLIENT_SECRET, issuer: AUTHENTIK_ISSUER })], * }) * ``` - * + * * :::note * issuer should include the slug without a trailing slash – e.g., https://my-authentik-domain.com/application/o/My_Slug * ::: * - * ## Resources + * ### Resources * * - [Authentik OAuth documentation](https://goauthentik.io/docs/providers/oauth2) * - * ## Notes + * ### Notes * * By default, Auth.js assumes that the Authentik provider is * based on the [Open ID Connect](https://openid.net/specs/openid-connect-core-1_0.html) specification. diff --git a/packages/core/src/providers/azure-ad-b2c.ts b/packages/core/src/providers/azure-ad-b2c.ts index 3d341794..c817346d 100644 --- a/packages/core/src/providers/azure-ad-b2c.ts +++ b/packages/core/src/providers/azure-ad-b2c.ts @@ -6,7 +6,6 @@ * *
* - * --- * @module providers/azure-ad-b2c */ @@ -60,7 +59,7 @@ export interface AzureADB2CProfile { * - Identity Provider Access Token * - User's Object ID * - * ## Example + * @example * * ```ts * import { Auth } from "@auth/core" @@ -75,13 +74,13 @@ export interface AzureADB2CProfile { * * --- * - * ## Resources + * ### Resources * * - [Azure Active Directory B2C documentation](https://learn.microsoft.com/en-us/azure/active-directory-b2c) * * --- * - * ## Notes + * ### Notes * * By default, Auth.js assumes that the Azure AD B2C provider is * based on the [OIDC](https://openid.net/specs/openid-connect-core-1_0.html) specification. diff --git a/packages/core/src/providers/azure-ad.ts b/packages/core/src/providers/azure-ad.ts index 9e38d39c..6ac6bbde 100644 --- a/packages/core/src/providers/azure-ad.ts +++ b/packages/core/src/providers/azure-ad.ts @@ -6,7 +6,6 @@ * *
* - * --- * @module providers/azure-ad */ import type { OAuthConfig, OAuthUserConfig } from "./index.js" @@ -21,9 +20,15 @@ export interface AzureADProfile extends Record { /** * Add AzureAd login to your page. * - * @example + * ### Setup * - * ```js + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/azure-ad + * ``` + * + * #### Configuration + *```js * import Auth from "@auth/core" * import AzureAd from "@auth/core/providers/azure-ad" * @@ -33,15 +38,15 @@ export interface AzureADProfile extends Record { * }) * ``` * - * ## Resources + * ### Resources * * - [AzureAd OAuth documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow/) * - [AzureAd OAuth apps](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app/) * - * ## Example - * + * @example + * * ### To allow specific Active Directory users access: - * + * * - In https://portal.azure.com/ search for "Azure Active Directory", and select your organization. * - Next, go to "App Registration" in the left menu, and create a new one. * - Pay close attention to "Who can use this application or access this API?" @@ -53,26 +58,26 @@ export interface AzureADProfile extends Record { * - Application (client) ID * - Directory (tenant) ID * - Client secret (value) - * + * * In `.env.local` create the following entries: - * + * * ``` * AZURE_AD_CLIENT_ID= * AZURE_AD_CLIENT_SECRET= * AZURE_AD_TENANT_ID= * ``` - * + * * That will default the tenant to use the `common` authorization endpoint. [For more details see here](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols#endpoints). - * + * * :::note * Azure AD returns the profile picture in an ArrayBuffer, instead of just a URL to the image, so our provider converts it to a base64 encoded image string and returns that instead. See: https://docs.microsoft.com/en-us/graph/api/profilephoto-get?view=graph-rest-1.0#examples. The default image size is 48x48 to avoid [running out of space](https://next-auth.js.org/faq#:~:text=What%20are%20the%20disadvantages%20of%20JSON%20Web%20Tokens%3F) in case the session is saved as a JWT. * ::: - * + * * In `pages/api/auth/[...nextauth].js` find or add the `AzureAD` entries: - * + * * ```js * import AzureADProvider from "next-auth/providers/azure-ad"; - * + * * ... * providers: [ * AzureADProvider({ @@ -82,10 +87,10 @@ export interface AzureADProfile extends Record { * }), * ] * ... - * + * * ``` - * - * ## Notes + * + * ### Notes * * By default, Auth.js assumes that the AzureAd provider is * based on the [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) specification. diff --git a/packages/core/src/providers/battlenet.ts b/packages/core/src/providers/battlenet.ts index b06aa9fb..36712359 100644 --- a/packages/core/src/providers/battlenet.ts +++ b/packages/core/src/providers/battlenet.ts @@ -1,13 +1,11 @@ /** *
* Built-in Battle.net integration. - * TODO: SVG logo * * * *
* - * --- * @module providers/battlenet */ import type { OAuthConfig, OAuthUserConfig } from "./index.js" @@ -25,9 +23,15 @@ export type BattleNetIssuer = /** * Add Battle.net login to your page. * - * @example + * ### Setup * - * ```js + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/battlenet + * ``` + * + * #### Configuration + *```js * import Auth from "@auth/core" * import BattleNet from "@auth/core/providers/battlenet" * @@ -46,11 +50,11 @@ export type BattleNetIssuer = * | "https://tw.battle.net/oauth" * ``` * - * ## Resources + * ### Resources * * - [BattleNet OAuth documentation](https://develop.battle.net/documentation/guides/using-oauth) * - * ## Notes + * ### Notes * * By default, Auth.js assumes that the BattleNet provider is * based on the [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) specification. diff --git a/packages/core/src/providers/beyondidentity.ts b/packages/core/src/providers/beyondidentity.ts index b26b1859..8b39a377 100644 --- a/packages/core/src/providers/beyondidentity.ts +++ b/packages/core/src/providers/beyondidentity.ts @@ -6,7 +6,6 @@ * * * - * --- * @module providers/beyondidentity */ @@ -27,7 +26,7 @@ export interface BeyondIdentityProfile { /** * Add Beyond Identity login to your page. * - * ## Example + * @example * * ```ts * import { Auth } from "@auth/core" @@ -41,13 +40,13 @@ export interface BeyondIdentityProfile { * * --- * - * ## Resources + * ### Resources * * - [Beyond Identity Developer Docs](https://developer.beyondidentity.com/) * * --- * - * ## Notes + * ### Notes * * By default, Auth.js assumes that the BeyondIdentity provider is * based on the [OIDC](https://openid.net/specs/openid-connect-core-1_0.html) specification. diff --git a/packages/core/src/providers/box.ts b/packages/core/src/providers/box.ts index 490fa59d..d0e55721 100644 --- a/packages/core/src/providers/box.ts +++ b/packages/core/src/providers/box.ts @@ -1,13 +1,11 @@ /** *
* Built-in Box integration. - * TODO: SVG logo * * * *
* - * --- * @module providers/box */ import type { OAuthConfig, OAuthUserConfig } from "./index.js" @@ -15,9 +13,15 @@ import type { OAuthConfig, OAuthUserConfig } from "./index.js" /** * Add Box login to your page. * - * @example + * ### Setup * - * ```js + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/box + * ``` + * + * #### Configuration + *```js * import Auth from "@auth/core" * import Box from "@auth/core/providers/box" * @@ -27,12 +31,12 @@ import type { OAuthConfig, OAuthUserConfig } from "./index.js" * }) * ``` * - * ## Resources + * ### Resources * * - [Box developers documentation](https://developer.box.com/reference/) * - [Box OAuth documentation](https://developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-box/) * - * ## Notes + * ### Notes * * By default, Auth.js assumes that the Box provider is * based on the [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) specification. @@ -54,7 +58,8 @@ import type { OAuthConfig, OAuthUserConfig } from "./index.js" * * ::: */ -export default function Box(options: OAuthUserConfig> +export default function Box( + options: OAuthUserConfig> ): OAuthConfig> { return { id: "box", diff --git a/packages/core/src/providers/boxyhq-saml.ts b/packages/core/src/providers/boxyhq-saml.ts index 3bf0ca93..e53b8701 100644 --- a/packages/core/src/providers/boxyhq-saml.ts +++ b/packages/core/src/providers/boxyhq-saml.ts @@ -1,13 +1,11 @@ /** *
* Built-in BoxyHQ SAML integration. - * TODO: SVG logo * * * *
* - * --- * @module providers/boxyhq-saml */ import type { OAuthConfig, OAuthUserConfig } from "./index.js" @@ -23,12 +21,18 @@ export interface BoxyHQSAMLProfile extends Record { * Add BoxyHQ SAML login to your page. * * BoxyHQ SAML is an open source service that handles the SAML login flow as an OAuth 2.0 flow, abstracting away all the complexities of the SAML protocol. - * - * You can deploy BoxyHQ SAML as a separate service or embed it into your app using our NPM library. [Check out the documentation for more details](https://boxyhq.com/docs/jackson/deploy) - * - * @example * - * ```js + * You can deploy BoxyHQ SAML as a separate service or embed it into your app using our NPM library. [Check out the documentation for more details](https://boxyhq.com/docs/jackson/deploy) + * + * ### Setup + * + * #### Callback URL + * ``` + * https://example.com/api/auth/callback/boxyhq-saml + * ``` + * + * #### Configuration + *```js * import Auth from "@auth/core" * import BoxyHQ from "@auth/core/providers/boxyhq-saml" * @@ -38,23 +42,23 @@ export interface BoxyHQSAMLProfile extends Record { * }) * ``` * - * ## Resources + * ### Resources * * - [BoxyHQ OAuth documentation](https://example.com) * * ## Configuration - * + * * SAML login requires a configuration for every tenant of yours. One common method is to use the domain for an email address to figure out which tenant they belong to. You can also use a unique tenant ID (string) from your backend for this, typically some kind of account or organization ID. - * + * * Check out the [documentation](https://boxyhq.com/docs/jackson/saml-flow#2-saml-config-api) for more details. - * - * + * + * * On the client side you'll need to pass additional parameters `tenant` and `product` to the `signIn` function. This will allow BoxyHQL SAML to figure out the right SAML configuration and take your user to the right SAML Identity Provider to sign them in. - * + * * ```tsx * import { signIn } from "next-auth/react"; * ... - * + * * // Map your users's email to a tenant and product * const tenant = email.split("@")[1]; * const product = 'my_awesome_product'; @@ -62,12 +66,12 @@ export interface BoxyHQSAMLProfile extends Record { *