diff --git a/docs/_partials/authentication/social-connections/enable-google-social-connection.mdx b/docs/_partials/authentication/social-connections/enable-google-social-connection.mdx new file mode 100644 index 0000000000..a2a1872ae7 --- /dev/null +++ b/docs/_partials/authentication/social-connections/enable-google-social-connection.mdx @@ -0,0 +1,5 @@ +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page. +1. Select **Add connection** and select **For all users**. +1. In the **Choose provider** dropdown, select **Google**. +1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. +1. Save the **Authorized Redirect URI** somewhere secure. Keep this modal and page open. diff --git a/docs/_partials/expo/use-sign-in-with-google-example.mdx b/docs/_partials/expo/use-sign-in-with-google-example.mdx new file mode 100644 index 0000000000..6a6811b985 --- /dev/null +++ b/docs/_partials/expo/use-sign-in-with-google-example.mdx @@ -0,0 +1,93 @@ +The following example demonstrates how to use the [`useSignInWithGoogle()`](/docs/reference/expo/use-sign-in-with-google) hook to manage the Google authentication flow. Because the `useSignInWithGoogle()` hook automatically manages the [transfer flow](!transfer-flow) between sign-up and sign-in, you can use this component for both your sign-up and sign-in pages. + +```tsx {{ filename: 'components/GoogleSignInButton.tsx', collapsible: true }} +import { useSignInWithGoogle } from '@clerk/clerk-expo' +import { useRouter } from 'expo-router' +import { Alert, Platform, StyleSheet, Text, TouchableOpacity, View } from 'react-native' + +interface GoogleSignInButtonProps { + onSignInComplete?: () => void + showDivider?: boolean +} + +export function GoogleSignInButton({ + onSignInComplete, + showDivider = true, +}: GoogleSignInButtonProps) { + const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + const router = useRouter() + + // Only render on iOS and Android + if (Platform.OS !== 'ios' && Platform.OS !== 'android') { + return null + } + + const handleGoogleSignIn = async () => { + try { + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() + + if (createdSessionId && setActive) { + await setActive({ session: createdSessionId }) + + if (onSignInComplete) { + onSignInComplete() + } else { + router.replace('/') + } + } + } catch (err: any) { + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + + Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') + console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) + } + } + + return ( + <> + + Sign in with Google + + + {showDivider && ( + + + OR + + + )} + + ) +} + +const styles = StyleSheet.create({ + googleButton: { + backgroundColor: '#4285F4', + padding: 15, + borderRadius: 8, + alignItems: 'center', + marginBottom: 10, + }, + googleButtonText: { + color: '#fff', + fontSize: 16, + fontWeight: '600', + }, + divider: { + flexDirection: 'row', + alignItems: 'center', + marginVertical: 20, + }, + dividerLine: { + flex: 1, + height: 1, + backgroundColor: '#ccc', + }, + dividerText: { + marginHorizontal: 10, + color: '#666', + }, +}) +``` diff --git a/docs/_partials/expo/web-client-id.mdx b/docs/_partials/expo/web-client-id.mdx new file mode 100644 index 0000000000..324d063212 --- /dev/null +++ b/docs/_partials/expo/web-client-id.mdx @@ -0,0 +1,7 @@ +#### Create a Web Client ID and Client Secret + +1. In the same project, create another client. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. +1. For the **Application type**, select **Web application**. +1. Add a name (e.g., "Web client for token verification"). +1. Under **Authorized redirect URIs**, select **Add URI** and paste the **Authorized Redirect URI** you saved from the Clerk Dashboard. +1. Select **Create**. A modal will open with your **Client ID** and **Client Secret**. Save these values somewhere secure. You'll need these for the following steps. diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx new file mode 100644 index 0000000000..63bef3cd39 --- /dev/null +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -0,0 +1,203 @@ +--- +title: Sign in with Google +description: Learn how to add Sign in with Google to your Expo app using Google's native SDK. +sdk: expo +--- + + + +This guide will teach you how to add [Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) to your Clerk Expo application using Google's native SDK. On Android, this shows a native account picker. On iOS, a web-based authentication sheet is presented. For the OAuth redirect flow, see the [dedicated guide](/docs/guides/configure/auth-strategies/social-connections/google). + +To make the setup process easier, it's recommended to keep two browser tabs open - one for the [Clerk Dashboard](https://dashboard.clerk.com/~/user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). + + + ## Enable Google as a social connection + + + + ## Configure Google Cloud Console + + Before you can use Google Sign-In in your app, you need to create OAuth 2.0 credentials in the Google Cloud Console. + + ### Create a Google Cloud Project + + 1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/). + 1. Select an existing project or [create a new one](https://console.cloud.google.com/projectcreate). You'll be redirected to your project's **Dashboard** page. + 1. Enable the [**Google+ API**](https://console.cloud.google.com/apis/library/plus.googleapis.com?project=expo-testing-480017) for your project. + + ### Create OAuth 2.0 credentials + + You'll need to create two sets of OAuth 2.0 credentials: one for your native platform and one for the web client. **Even if you are building a native app, you still need to create the web client for Clerk's token verification.** + + If you're building for both iOS and Android, ensure that you create all three sets of credentials (iOS, Android, and web). + + + + #### Create an iOS Client ID + + 1. Navigate to [**APIs & Services**](https://console.cloud.google.com/apis/dashboard). Then, in the left sidebar, select **Credentials**. + 1. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. You might need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849#userconsent). Otherwise, you'll be redirected to the **Create OAuth client ID** page. + 1. For the **Application type**, select **iOS**. + 1. Complete the required fields: + - **Name**: Add a name for your client. + - **Bundle ID**: Add your iOS **Bundle ID**. + 1. Select **Create**. A modal will open with your **Client ID**. Copy and save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID`. + + + + + + #### Create an Android Client ID + + 1. In the same project, create another client. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. + 1. For the **Application type**, select **Android**. + 1. Complete the required fields: + - **Package name**: Your package name is in your `app.json` or `app.config.ts`. + - **SHA-1 certificate fingerprint**: To get your SHA-1, run the following command in your terminal: + + ```sh {{ filename: 'terminal' }} + $ keytool -keystore path-to-debug-or-production-keystore -list -v + ``` + + > [!NOTE] + > Replace `path-to-debug-or-production-keystore` with the path to your debug or production keystore. By default, the debug keystore is located in `~/.android/debug.keystore`. It may ask for a keystore password, which is `android`. **Please note that Java is required to run the `keytool` command.** + 1. Select **Create**. A modal will open with your **Client ID**. + 1. Copy and save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_ANDROID_CLIENT_ID`. + + + + + + ## Set the Client ID and Client Secret (from your web client) in the Clerk Dashboard + + + + ## Add your native application to Clerk + + + + Add your iOS application to the [**Native Applications**](https://dashboard.clerk.com/~/native-applications) page in the Clerk Dashboard. You'll need your iOS app's **App ID Prefix** (Team ID) and **Bundle ID**. + + + + Add your Android application to the [**Native Applications**](https://dashboard.clerk.com/~/native-applications) page in the Clerk Dashboard. You'll need your Android app's **package name**. + + + + ## Configure environment variables + + Add the Google OAuth client IDs to your `.env` file. You'll have saved these values in the previous steps. + + ```bash {{ filename: '.env' }} + EXPO_PUBLIC_CLERK_GOOGLE_WEB_CLIENT_ID=your-web-client-id.apps.googleusercontent.com + EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID=your-ios-client-id.apps.googleusercontent.com + EXPO_PUBLIC_CLERK_GOOGLE_ANDROID_CLIENT_ID=your-android-client-id.apps.googleusercontent.com + + # (iOS only) + # EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME is the URL scheme for Google sign-in callback + # Replace your-ios-client-id with the same from EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID. It should only be the part of your iOS Client ID before ".apps.googleusercontent.com". + EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME=com.googleusercontent.apps.your-ios-client-id + ``` + + ## Set up native Sign in with Google (iOS only) + + This step is for **iOS only** and is **optional**. Currently, Sign in with Google will open a web browser to initiate the flow. If you'd rather have the app handle the flow natively and not open a web browser, follow this step. + + ### Configure the Clerk Expo plugin + + The `@clerk/clerk-expo` config plugin configures the URL scheme needed for Google's authentication callback. Add the plugin to your `app.json` or `app.config.ts`, depending on your app's configuration: + + > [!QUIZ] + > What is the difference between `app.json` and `app.config.ts`? + > + > --- + > + > `app.json` is for projects using static JSON configuration. `app.config.ts` is for projects that need dynamic configuration (environment variables, conditional logic, etc.). When both files exist, `app.config.ts` receives the values from `app.json` and can extend or override them. + + + + Replace `your-ios-client-id` with the same `` from your `EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID` environment variable (it should only be the part of your iOS Client ID before ".apps.googleusercontent.com"). + + ```json {{ filename: 'app.json' }} + { + "expo": { + "plugins": ["@clerk/clerk-expo"], + "extra": { + "EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME": "com.googleusercontent.apps.your-ios-client-id" + } + } + } + ``` + + + + ```ts {{ filename: 'app.config.ts' }} + export default { + expo: { + plugins: ['@clerk/clerk-expo'], + extra: { + EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME: process.env.EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME, + }, + }, + } + ``` + + + + The plugin resolves the `EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME` value from either of the following: + + 1. An environment variable (recommended for EAS builds, configured in `eas.json`). + 1. The `config.extra` field in your app config. + + For EAS builds, add the environment variable to your build profile in `eas.json`: + + ```json {{ filename: 'eas.json' }} + { + "build": { + "development": { + "env": { + "EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME": "com.googleusercontent.apps.your-ios-client-id" + } + } + } + } + ``` + + ### Create the Sign in with Google button + + The `` component from the Expo quickstart will open a web browser to initiate the Sign in with Google flow. Replace it with the `` component from the following example. + + + + ## Create a native build + + Create a native build with EAS Build or a local prebuild, since Google Authentication is not supported in Expo Go. + + ```bash {{ filename: 'terminal' }} + # Using EAS Build + eas build --platform ios + eas build --platform android + + # Or using local prebuild + npx expo prebuild && npx expo run:ios --device + npx expo prebuild && npx expo run:android --device + ``` + diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx index 17dc76cbc1..753a68085a 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx @@ -1,6 +1,6 @@ --- title: Sign in with Google -description: Learn how to configure Sign in with Google for your Clerk-powered Android app. +description: Learn how to use Clerk to natively Sign in with Google in your Android app. sdk: android --- @@ -15,24 +15,23 @@ sdk: android title: "A Google Developer account is required.", link: "https://console.developers.google.com/", icon: "user-circle", - } + }, + { + title: "Follow the Android quickstart", + link: "/docs/android/getting-started/quickstart", + icon: "android", + }, ]} /> -[Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) helps you easily and securely sign in to third-party apps or services with your Google Account, without having to enter a username and password repeatedly across different services. - -This guide will teach you how to add native Sign in with Google to your Clerk apps on Android platforms. This is different from Google OAuth - if you want to use Google OAuth, see the [dedicated guide](/docs/guides/configure/auth-strategies/social-connections/google). +This guide will teach you how to add native [Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) to your Clerk apps on Android platforms. This is different from Google OAuth - if you want to use Google OAuth, see the [dedicated guide](/docs/guides/configure/auth-strategies/social-connections/google). To make the setup process easier, it's recommended to keep two browser tabs open - one for the [Clerk Dashboard](https://dashboard.clerk.com/~/user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). ## Enable Google as a social connection - 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page. - 1. Select **Add connection** and select **For all users**. - 1. In the **Choose provider** dropdown, select **Google**. - 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. Save the **Authorized Redirect URI** somewhere secure. Keep this modal and page open. + ## Create the Google Developer Android client @@ -41,7 +40,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the top-left, select the menu icon (**≡**) and select **APIs & Services**. Then, select **Credentials**. 1. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID.** You might need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849#userconsent). Otherwise, you'll be redirected to the **Create OAuth client ID** page. 1. For the **Application type**, select **Android**. - 1. Complete the required fields. + 1. Complete the required fields: - **Package name**: Your package name is in your `build.gradle` file, formatted as `com.example.myclerkapp`. - **SHA-1 certificate fingerprint**: To get your SHA-1, run the following command in your terminal: diff --git a/docs/guides/configure/auth-strategies/social-connections/google.mdx b/docs/guides/configure/auth-strategies/social-connections/google.mdx index d98ccc6635..17d075602b 100644 --- a/docs/guides/configure/auth-strategies/social-connections/google.mdx +++ b/docs/guides/configure/auth-strategies/social-connections/google.mdx @@ -23,6 +23,11 @@ Enabling OAuth with [Google](https://developers.google.com/identity/protocols/oa > [!WARNING] > Google OAuth 2.0 **does not** allow apps to use WebViews for authentication. See the dedicated [Google blog post](https://developers.googleblog.com/en/modernizing-oauth-interactions-in-native-apps-for-better-usability-and-security) for more information. If your app requires users to sign in via in-app browsers, follow the setup instructions in the [Google Help guide](https://support.google.com/faqs/answer/12284343). + + > [!IMPORTANT] + > This guide explains how to configure Sign in with Google for web-based flows. To configure Sign in with Google on native applications (such as Android or Expo apps), see the [dedicated guide](/docs/guides/configure/auth-strategies/sign-in-with-google). + + ## Configure for your development instance For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. @@ -41,11 +46,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Enable Google as a social connection - 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page. - 1. Select **Add connection** and select **For all users**. - 1. In the **Choose provider** dropdown, select **Google**. - 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. Save the **Authorized Redirect URI** somewhere secure. Keep this modal and page open. + ### Create a Google Developer project diff --git a/docs/manifest.json b/docs/manifest.json index d225540163..266e52d1b8 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1717,6 +1717,10 @@ "title": "`useSignInWithApple()`", "href": "/docs/reference/expo/use-sign-in-with-apple" }, + { + "title": "`useSignInWithGoogle()`", + "href": "/docs/reference/expo/use-sign-in-with-google" + }, { "title": "`useSSO()`", "href": "/docs/reference/expo/use-sso" diff --git a/docs/reference/expo/use-sign-in-with-google.mdx b/docs/reference/expo/use-sign-in-with-google.mdx new file mode 100644 index 0000000000..cae5193ac0 --- /dev/null +++ b/docs/reference/expo/use-sign-in-with-google.mdx @@ -0,0 +1,149 @@ +--- +title: '`useSignInWithGoogle()`' +description: Clerk's useSignInWithGoogle() hook provides native Sign in with Google functionality for iOS and Android devices. +sdk: expo +--- + + + +> [!NOTE] +> This hook is available on iOS and Android devices and requires a native build. It will not work with Expo Go. + +The `useSignInWithGoogle()` hook provides native [Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) functionality for iOS and Android devices. It handles the ID token exchange with Clerk's backend and automatically manages the [transfer flow](!transfer-flow) between sign-up and sign-in. + +## Returns + +The `useSignInWithGoogle()` hook returns the `startGoogleAuthenticationFlow()` method, which you can use to initiate the native Google authentication flow. + +### `startGoogleAuthenticationFlow()` + +`startGoogleAuthenticationFlow()` has the following function signature: + +```ts +function startGoogleAuthenticationFlow( + startGoogleAuthenticationFlowParams?: StartGoogleAuthenticationFlowParams, +): Promise +``` + +#### Parameters + +`startGoogleAuthenticationFlow()` accepts the following parameters (`StartGoogleAuthenticationFlowParams`): + + + - `unsafeMetadata?` + - [`SignUpUnsafeMetadata`](/docs/reference/javascript/types/metadata#sign-up-unsafe-metadata) + + Metadata that can be read and set from the frontend and the backend. Once the authentication process is complete, the value of this field will be automatically copied to the created user's unsafe metadata (`User.unsafeMetadata`). One common use case is to collect custom information about the user during the authentication process and store it in this property. Read more about [unsafe metadata](/docs/guides/users/extending#unsafe-metadata). + + +#### Returns + +`startGoogleAuthenticationFlow()` returns the following: + + + - `createdSessionId` + - `string | null` + + The ID of the session that was created, if authentication is successful. + + --- + + - `setActive?` + - `(params: SetActiveParams) => Promise` + + A method used to set the active session and/or organization. Accepts a [`SetActiveParams`](/docs/reference/javascript/types/set-active-params) object. + + --- + + - `signIn?` + - [SignIn](/docs/reference/javascript/sign-in) | undefined + + The [`SignIn`](/docs/reference/javascript/sign-in) object that was created, which holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. + + --- + + - `signUp?` + - [SignUp](/docs/reference/javascript/sign-up) | undefined + + The [`SignUp`](/docs/reference/javascript/sign-up) object that was created, which holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process. + + +## Examples + +### Reusable component + + + +### With custom metadata + +The following example demonstrates how to pass custom metadata that will be saved to the user's [unsafe metadata](/docs/guides/users/extending#unsafe-metadata) during sign-up. + +```tsx {{ filename: 'app/(auth)/sign-in.tsx' }} +import { useRouter } from 'expo-router' +import { useSignInWithGoogle } from '@clerk/clerk-expo' +import { Alert, Platform, TouchableOpacity, Text } from 'react-native' + +export default function SignInPage() { + const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + const router = useRouter() + + // Only show on iOS and Android + if (Platform.OS !== 'ios' && Platform.OS !== 'android') { + return null + } + + const onGoogleSignInPress = async () => { + try { + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow({ + // Add information about the user to their unsafe metadata + unsafeMetadata: { + referralSource: 'mobile-app', + signupDate: new Date().toISOString(), + }, + }) + + if (createdSessionId && setActive) { + // Set the created session as the active session + await setActive({ session: createdSessionId }) + // Once the session is set as active, + // redirect the user to the home page + router.replace('/') + } + } catch (err: any) { + // User canceled the sign-in flow + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + + Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') + console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) + } + } + + return ( + + Sign in with Google + + ) +} +``` + +## Error handling + +The `useSignInWithGoogle()` hook may throw errors in the following scenarios: + +- **User cancellation**: The user cancels the authentication flow, resulting in an error with code `SIGN_IN_CANCELLED` or `-5`. +- **Platform error**: The hook is called on an unsupported platform (not iOS or Android). +- **Authentication failure**: Google authentication fails or the returned ID token is invalid. +- **Play Services error** (Android only): Google Play Services is not available or outdated on the device. + +> [!IMPORTANT] +> Always wrap calls to `startGoogleAuthenticationFlow()` in a `try/catch` block, and handle the `SIGN_IN_CANCELLED` and `-5` error codes separately.