diff --git a/docs/components/control/authenticate-with-callback.mdx b/docs/components/control/authenticate-with-callback.mdx index b1b4d8c8cc..50f8a0741d 100644 --- a/docs/components/control/authenticate-with-callback.mdx +++ b/docs/components/control/authenticate-with-callback.mdx @@ -1,131 +1,11 @@ --- title: \RedirectCallback /> -description: The `` is used to complete a custom OAuth flow. Simply render the component under the route you passed as `redirectUrl` to the `authenticateWithRedirect` methods. +description: Clerk's `` component is used to implement custom OAuth flows. It handles the OAuth callback and completes the authentication process. --- -The `` is used to complete a custom OAuth flow. Simply render the component under the route you passed as `redirectUrl` to the `authenticateWithRedirect` methods. +The `` component is a crucial part of implementing custom OAuth flows in your application. It serves as the callback handler for the authentication process initiated by the `authenticateWithRedirect()` method. Render it on the route specified as the `redirectUrl` in your `authenticateWithRedirect()` call. -## Usage - - - - This example below uses built in Next.js pages, but you could use any routing library you want. - - ```tsx {{ filename: 'app.tsx' }} - import '@/styles/globals.css' - import { ClerkProvider, SignedIn, SignedOut, useSignIn } from '@clerk/nextjs' - import { AppProps } from 'next/app' - import { useRouter } from 'next/router' - - const publicPages: Array = [] - - const SignInOAuthButtons = () => { - const { signIn, isLoaded } = useSignIn() - if (!isLoaded) { - return null - } - const signInWithGoogle = () => - signIn.authenticateWithRedirect({ - strategy: 'oauth_google', - redirectUrl: '/sso-callback', - redirectUrlComplete: '/', - }) - return - } - function MyApp({ Component, pageProps }: AppProps) { - const { pathname } = useRouter() - const isPublicPage = publicPages.includes(pathname) - - return ( - - {isPublicPage ? ( - - ) : ( - <> - - - - - - - - )} - - ) - } - - export default MyApp - ``` - - Once you have implemented your sign in flow, you can implement the callback page. - - ```tsx {{ filename: '/pages/sso-callback.tsx' }} - import { AuthenticateWithRedirectCallback } from '@clerk/nextjs' - - export default function SSOCallBack() { - return - } - ``` - - - - This example below is using the `react-router-dom` library. You can use any routing library you want. - - ```tsx {{ filename: 'app.tsx' }} - import { - ClerkProvider, - AuthenticateWithRedirectCallback, - SignedOut, - useSignIn, - SignedIn, - } from '@clerk/clerk-react' - - import { Route, Routes } from 'react-router-dom' - - function App() { - return ( - - {/* Define a / route that displays the OAuth button */} - - } /> - - } /> - - - ) - } - - function HomePages() { - return ( - <> - - - - -
Hello! You are Signed In!
-
- - ) - } - - function SignInOAuthButtons() { - const { signIn, isLoaded } = useSignIn() - if (!isLoaded) { - return null - } - const signInWithGoogle = () => - signIn.authenticateWithRedirect({ - strategy: 'oauth_google', - redirectUrl: '/sso-callback', - redirectUrlComplete: '/', - }) - return - } - - export default App - ``` -
-
+This component automatically handles the OAuth callback, completing the authentication process and managing the user's session. ## Properties @@ -233,3 +113,123 @@ The `` is used to complete a custom OAuth fl Full URL or path to navigate after successful sign in or sign up. This is the same as setting `afterSignInUrl` and `afterSignUpUrl` to the same value. The **`signXfallbackRedirectUrl` and `signXforceRedirectUrl` props have priority over the deprecated `redirectUrl` and should be used instead.** + +## Usage + +In the following example, when a user selects the "Sign in with Google" button, they are redirected to Google for authentication. After successful authentication, Google redirects the user back to your application at the `/sso-callback` route, where the `` component is automatically rendered. This component handles the OAuth callback, completes the authentication process, and manages the user's session. + + + + ```tsx {{ filename: 'app/layout.tsx', collapsible: true }} + 'use client' + + import { ClerkProvider, SignedIn, SignedOut, UserButton, useSignIn } from '@clerk/nextjs' + + const SignInOAuthButtons = () => { + const { signIn, isLoaded } = useSignIn() + + if (!isLoaded) { + return null + } + + const signInWithGoogle = () => + signIn.authenticateWithRedirect({ + strategy: 'oauth_google', + redirectUrl: '/sso-callback', + redirectUrlComplete: '/', + }) + + return + } + + export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + +
+ + + + + + +
+
{children}
+ + +
+ ) + } + ``` + + Once you have implemented your sign-in flow, you can implement the callback page. + + ```tsx {{ filename: 'app/sso-callback/page.tsx' }} + import { AuthenticateWithRedirectCallback } from '@clerk/nextjs' + + export default function Page() { + return + } + ``` +
+ + + The following example is using the `react-router-dom` library, but you can use any routing library you want. + + ```tsx {{ filename: 'app.tsx', collapsible: true }} + import { + ClerkProvider, + AuthenticateWithRedirectCallback, + SignedOut, + useSignIn, + SignedIn, + } from '@clerk/clerk-react' + + import { Route, Routes } from 'react-router-dom' + + function App() { + return ( + + {/* Define a / route that displays the OAuth button */} + + } /> + + {/* Define a /sso-callback route that renders the component */} + } /> + + + ) + } + + function HomePages() { + return ( + <> + + + + +
You are signed in
+
+ + ) + } + + function SignInOAuthButtons() { + const { signIn, isLoaded } = useSignIn() + if (!isLoaded) { + return null + } + const signInWithGoogle = () => + signIn.authenticateWithRedirect({ + strategy: 'oauth_google', + redirectUrl: '/sso-callback', + redirectUrlComplete: '/', + }) + return + } + + export default App + ``` +
+