Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

(/authenticate-with-redirect-callback) update reference guide #1621

Merged
merged 6 commits into from
Oct 11, 2024
Merged

(/authenticate-with-redirect-callback) update reference guide #1621

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9926557
update reference
alexisintech Oct 10, 2024
36a908e
update example explanation
alexisintech Oct 10, 2024
3363d75
move props above usage
alexisintech Oct 10, 2024
d295304
add collapsible:true
alexisintech Oct 10, 2024
c6dfdb7
Merge branch 'main' into aa/DOCS-9162
victoriaxyz Oct 10, 2024
3af78cd
Update docs/components/control/authenticate-with-callback.mdx
alexisintech Oct 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
246 changes: 123 additions & 123 deletions docs/components/control/authenticate-with-callback.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,131 +1,11 @@
---
title: <code>\<AuthenticateWith<wbr />RedirectCallback /></code>
description: The `<AuthenticateWithRedirectCallback />` 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 `<AuthenticateWithRedirectCallback />` component is used to implement custom OAuth flows. It handles the OAuth callback and completes the authentication process.
---

The `<AuthenticateWithRedirectCallback />` is used to complete a custom OAuth flow. Simply render the component under the route you passed as `redirectUrl` to the `authenticateWithRedirect` methods.
The `<AuthenticateWithRedirectCallback />` 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

<Tabs type="framework" items={["Next.js", "React"]}>
<Tab>
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<string> = []

const SignInOAuthButtons = () => {
const { signIn, isLoaded } = useSignIn()
if (!isLoaded) {
return null
}
const signInWithGoogle = () =>
signIn.authenticateWithRedirect({
strategy: 'oauth_google',
redirectUrl: '/sso-callback',
redirectUrlComplete: '/',
})
return <button onClick={signInWithGoogle}>Sign in with Google</button>
}
function MyApp({ Component, pageProps }: AppProps) {
const { pathname } = useRouter()
const isPublicPage = publicPages.includes(pathname)

return (
<ClerkProvider {...pageProps}>
{isPublicPage ? (
<Component {...pageProps} />
) : (
<>
<SignedIn>
<Component {...pageProps} />
</SignedIn>
<SignedOut>
<SignInOAuthButtons />
</SignedOut>
</>
)}
</ClerkProvider>
)
}

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 <AuthenticateWithRedirectCallback />
}
```
</Tab>

<Tab>
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 (
<ClerkProvider publishableKey={`{{pub_key}}`}>
{/* Define a / route that displays the OAuth button */}
<Routes>
<Route path="/" element={<HomePages />} />

<Route path="/sso-callback" element={<AuthenticateWithRedirectCallback />} />
</Routes>
</ClerkProvider>
)
}

function HomePages() {
return (
<>
<SignedOut>
<SignInOAuthButtons />
</SignedOut>
<SignedIn>
<div>Hello! You are Signed In!</div>
</SignedIn>
</>
)
}

function SignInOAuthButtons() {
const { signIn, isLoaded } = useSignIn()
if (!isLoaded) {
return null
}
const signInWithGoogle = () =>
signIn.authenticateWithRedirect({
strategy: 'oauth_google',
redirectUrl: '/sso-callback',
redirectUrlComplete: '/',
})
return <button onClick={signInWithGoogle}>Sign in with Google</button>
}

export default App
```
</Tab>
</Tabs>
This component automatically handles the OAuth callback, completing the authentication process and managing the user's session.

## Properties

Expand Down Expand Up @@ -233,3 +113,123 @@ The `<AuthenticateWithRedirectCallback />` 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.**
</Properties>

## 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 `<AuthenticateWithRedirectCallback />` component is automatically rendered. This component handles the OAuth callback, completes the authentication process, and manages the user's session.

<Tabs items={["Next.js", "React"]}>
<Tab>
```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 <button onClick={signInWithGoogle}>Sign in with Google</button>
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<ClerkProvider>
<html lang="en">
<body>
<header>
<SignedOut>
<SignInOAuthButtons />
</SignedOut>
<SignedIn>
<UserButton />
</SignedIn>
</header>
<main>{children}</main>
</body>
</html>
</ClerkProvider>
)
}
```

Once you have implemented your sign in flow, you can implement the callback page.
alexisintech marked this conversation as resolved.
Show resolved Hide resolved

```tsx {{ filename: 'app/sso-callback/page.tsx' }}
import { AuthenticateWithRedirectCallback } from '@clerk/nextjs'

export default function Page() {
return <AuthenticateWithRedirectCallback />
}
```
</Tab>

<Tab>
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 (
<ClerkProvider publishableKey={'{{pub_key}}'}>
{/* Define a / route that displays the OAuth button */}
<Routes>
<Route path="/" element={<HomePages />} />

{/* Define a /sso-callback route that renders the <AuthenticateWithRedirectCallback /> component */}
<Route path="/sso-callback" element={<AuthenticateWithRedirectCallback />} />
</Routes>
</ClerkProvider>
)
}

function HomePages() {
return (
<>
<SignedOut>
<SignInOAuthButtons />
</SignedOut>
<SignedIn>
<div>You are signed in</div>
</SignedIn>
</>
)
}

function SignInOAuthButtons() {
const { signIn, isLoaded } = useSignIn()
if (!isLoaded) {
return null
}
const signInWithGoogle = () =>
signIn.authenticateWithRedirect({
strategy: 'oauth_google',
redirectUrl: '/sso-callback',
redirectUrlComplete: '/',
})
return <button onClick={signInWithGoogle}>Sign in with Google</button>
}

export default App
```
</Tab>
</Tabs>
Loading