diff --git a/docs/content/docs/concepts/oauth.mdx b/docs/content/docs/concepts/oauth.mdx index 1bee2ffffe..3ffcda3970 100644 --- a/docs/content/docs/concepts/oauth.mdx +++ b/docs/content/docs/concepts/oauth.mdx @@ -5,13 +5,13 @@ description: How Better Auth handles OAuth Better Auth comes with built-in support for OAuth 2.0 and OpenID Connect. This allows you to authenticate users via popular OAuth providers like Google, Facebook, GitHub, and more. -If your desired provider isn’t directly supported, you can use the [Generic OAuth Plugin](/docs/plugins/generic-oauth) for custom integrations. +If your desired provider isn't directly supported, you can use the [Generic OAuth Plugin](/docs/plugins/generic-oauth) for custom integrations. ## Configuring Social Providers To enable a social provider, you need to provide `clientId` and `clientSecret` for the provider. -Here’s an example of how to configure Google as a provider: +Here's an example of how to configure Google as a provider: ```ts title="auth.ts" import { betterAuth } from "better-auth"; @@ -37,17 +37,17 @@ export const auth = betterAuth({ **disableSignUp:** Disables sign-up for new users. -**disableIdTokenSignIn:** Disables the use of the ID token for sign-in. By default, it’s enabled for some providers like Google and Apple. +**disableIdTokenSignIn:** Disables the use of the ID token for sign-in. By default, it's enabled for some providers like Google and Apple. **verifyIdToken** A custom function to verify the ID token. -**getUserInfo** A custom function to fetch user information from the provider. Given the tokens returned from the provider, this function should return the user’s information. +**getUserInfo** A custom function to fetch user information from the provider. Given the tokens returned from the provider, this function should return the user's information. **mapProfileToUser** A custom function to map the user profile returned from the provider to the user object in your database. -**refreshAccessToken**: A custom function to refresh the token. Given the default implementation, you can provide a custom function to refresh the token. +**refreshAccessToken**: A custom function to refresh the token. This feature is only supported for built-in social providers (Google, Facebook, GitHub, etc.) and is not currently supported for custom OAuth providers configured through the Generic OAuth Plugin. For built-in providers, you can provide a custom function to refresh the token if needed. -Useful, if you have additional fields in your user object you want to populate from the provider’s profile. Or if you want to change how by default the user object is mapped. +Useful, if you have additional fields in your user object you want to populate from the provider's profile. Or if you want to change how by default the user object is mapped. ```ts title="auth.ts" import { betterAuth } from "better-auth"; @@ -71,14 +71,14 @@ export const auth = betterAuth({ ## How OAuth Works in Better Auth -Here’s what happens when a user selects a provider to authenticate with: +Here's what happens when a user selects a provider to authenticate with: 1. **Configuration Check:** Ensure the necessary provider details (e.g., client ID, secret) are configured. 2. **State Generation:** Generate and save a state token in your database for CSRF protection. 3. **PKCE Support:** If applicable, create a PKCE code challenge and verifier for secure exchanges. -4. **Authorization URL Construction:** Build the provider’s authorization URL with parameters like client ID, redirect URI, state, etc. The callback URL usually follows the pattern `/api/auth/callback/${providerName}`. +4. **Authorization URL Construction:** Build the provider's authorization URL with parameters like client ID, redirect URI, state, etc. The callback URL usually follows the pattern `/api/auth/callback/${providerName}`. 5. **User Redirection:** - - If redirection is enabled, users are redirected to the provider’s login page. + - If redirection is enabled, users are redirected to the provider's login page. - If redirection is disabled, the authorization URL is returned for the client to handle the redirection. ### Post-Login Flow @@ -87,7 +87,7 @@ After the user completes the login process, the provider redirects them back to 1. **Token Exchange:** The code is exchanged for an access token and user information. 2. **User Handling:** - - If the user doesn’t exist, a new account is created. + - If the user doesn't exist, a new account is created. - If the user exists, they are logged in. - If the user has multiple accounts across providers, Better Auth links them based on your configuration. Learn more about [account linking](/docs/concepts/users-accounts#account-linking). 3. **Session Creation:** A new session is created for the user.