diff --git a/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx new file mode 100644 index 0000000000..93cbb3f682 --- /dev/null +++ b/docs/guides/development/custom-flows/authentication/last-authentication-strategy.mdx @@ -0,0 +1,144 @@ +--- +title: Build a custom flow for displaying the last authentication method +description: Learn how to use the Clerk API to build a custom flow for displaying the `lastAuthenticationStrategy` property and highlighting the last used OAuth provider with a badge. +--- + + + +The `Client` object includes a `lastAuthenticationStrategy` property that tracks the last authentication method used by the user. This is useful for improving the user experience by showing a "Last used" badge on OAuth buttons, helping returning users quickly identify their preferred sign-in method. + +## Access the last authentication strategy + +The `lastAuthenticationStrategy` property is available on the [`Client`](/docs/reference/javascript/client) object. You can access it through the `client` property of the [`Clerk`](/docs/reference/javascript/clerk) instance. + + + + This example is written for Next.js App Router but it can be adapted for any React-based framework. + + The following example demonstrates how to: + + 1. Access the `client` object using the [`useClerk()`](/docs/reference/hooks/use-clerk) hook. + 1. Check the `lastAuthenticationStrategy` property to identify which OAuth provider was last used. + 1. Display a badge next to the corresponding OAuth button. + + ```tsx {{ filename: 'app/sign-in/page.tsx' }} + 'use client' + + import * as React from 'react' + import { OAuthStrategy } from '@clerk/types' + import { useSignIn, useClerk } from '@clerk/nextjs' + + export default function Page() { + const { signIn } = useSignIn() + const { client } = useClerk() + + if (!signIn) return null + + const lastStrategy = client?.lastAuthenticationStrategy + + const signInWith = (strategy: OAuthStrategy) => { + return signIn.authenticateWithRedirect({ + strategy, + redirectUrl: '/sign-in/sso-callback', + redirectUrlComplete: '/', + }) + } + + const providers = [ + { strategy: 'oauth_google' as const, name: 'Google' }, + { strategy: 'oauth_github' as const, name: 'GitHub' }, + ] + + return ( +
+

Sign in

+ {providers.map((provider) => ( + + ))} +
+ ) + } + ``` +
+ + + The following example demonstrates how to: + + 1. Access the `client` object from the `Clerk` instance. + 1. Check the `lastAuthenticationStrategy` property to identify which OAuth provider was last used. + 1. Display a badge next to the corresponding OAuth button. + + ```html {{ filename: 'index.html', collapsible: true }} + + + + + + Clerk + JavaScript App + + +
+ + + + + ``` + + ```js {{ filename: 'main.js', collapsible: true }} + import { Clerk } from '@clerk/clerk-js' + + const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(pubKey) + await clerk.load() + + if (clerk.user) { + // User is already signed in + document.getElementById('app').innerHTML = ` +
+ ` + clerk.mountUserButton(document.getElementById('user-button')) + } else { + const lastStrategy = clerk.client?.lastAuthenticationStrategy + + const providers = [ + { strategy: 'oauth_google', name: 'Google' }, + { strategy: 'oauth_github', name: 'GitHub' }, + ] + + const buttons = providers + .map( + (provider) => ` + + `, + ) + .join('') + + document.getElementById('app').innerHTML = ` +

Sign in

+ ${buttons} + ` + + providers.forEach((provider) => { + document.getElementById(provider.strategy)?.addEventListener('click', async () => { + try { + await clerk.client.signIn.authenticateWithRedirect({ + strategy: provider.strategy, + redirectUrl: '/sso-callback', + redirectUrlComplete: '/', + }) + } catch (error) { + console.error('Error:', error) + } + }) + }) + } + ``` +
+
diff --git a/docs/manifest.json b/docs/manifest.json index c935a3fba2..5fefc009de 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -979,6 +979,10 @@ "title": "OAuth connections", "href": "/docs/guides/development/custom-flows/authentication/oauth-connections" }, + { + "title": "Add a badge to show the last authentication strategy", + "href": "/docs/guides/development/custom-flows/authentication/last-authentication-strategy" + }, { "title": "Enterprise connections", "href": "/docs/guides/development/custom-flows/authentication/enterprise-connections"