Google OAuth Setup Guide

This guide will walk you through setting up Google OAuth for your React Native app on both iOS and Android.

Prerequisites

• A Google Cloud Console account
• Your React Native app's bundle identifier (iOS) and package name (Android)

Step 1: Create Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to APIs & Services → Credentials

Step 2: Configure OAuth Consent Screen

1. Click OAuth consent screen in the left sidebar
2. Select External (or Internal if using Google Workspace)
3. Fill in the required information:
   • App name
   • User support email
   • Developer contact information
4. Add scopes (at minimum):
   • openid
   • profile
   • email
5. Save and continue

Step 3: Create OAuth 2.0 Credentials

You need to create THREE different OAuth client IDs for your app:

Using Firebase?

When Google is enabled as a sign-in provider in Firebase Authentication and the SHA-1 fingerprints are added to the Firebase Android app, Firebase creates the web, Android and iOS OAuth clients for you. Download GoogleService-Info.plist and google-services.json again afterwards: they contain the ids, and the library can read them (see Step 4). You can skip to Step 4.

3.1. Web Application Client ID (Required)

This is the webClientId in your React Native code: Android passes it to Credential Manager, and iOS uses it as the default serverClientId (the idToken audience your backend verifies, and serverAuthCode).

1. Click Create Credentials → OAuth client ID
2. Select Web application
3. Name it (e.g., "My App - Web Client")
4. No need to add Authorized redirect URIs
5. Click Create
6. Copy the Client ID - it is your webClientId

3.2. iOS Client ID

1. Click Create Credentials → OAuth client ID
2. Select iOS
3. Name it (e.g., "My App - iOS")
4. Enter your iOS Bundle ID (e.g., com.yourcompany.yourapp)
   • Find this in your Info.plist or Xcode project settings
5. Click Create
6. Copy the iOS Client ID - it is your iosClientId, and its reversed form is the iOS URL scheme

3.3. Android Client ID

1. Click Create Credentials → OAuth client ID

2. Select Android

3. Name it (e.g., "My App - Android")

4. Enter your Android Package name (e.g., com.yourcompany.yourapp)

   • Find this in android/app/build.gradle under applicationId

5. Enter your SHA-1 certificate fingerprint. Create one Android client per signing key: debug, release (upload) and the Play App Signing key (Play Console > Setup > App signing), or Google Sign-In fails in the Play Store build. cd android && ./gradlew signingReport prints the debug and release fingerprints:

   For Development (Debug):

   # macOS/Linux
   keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
   
   # Windows
   keytool -list -v -keystore %USERPROFILE%\.android\debug.keystore -alias androiddebugkey -storepass android -keypass android

   For Production (Release):

   keytool -list -v -keystore /path/to/your/release.keystore -alias your-key-alias

6. Click Create

7. You never pass the Android Client ID in code. Google only checks that one exists for your package name and signature

Step 4: Configure Your React Native App

4.1. Provide the client ids

In the app config (recommended). Put the ids in the native config (4.2, 4.3), or let the Expo config plugin write them, and call the methods without client ids:

import { googleSignIn } from 'react-native-oauth-essentials';

const credential = await googleSignIn(); // or googleSignIn({ mode: 'button' })

When the client id is not passed, each platform reads it in this order:

• iOS client id: GIDClientID in Info.plist, then CLIENT_ID of the Firebase GoogleService-Info.plist bundled in the app. serverClientId (idToken audience): the serverClientId option, then webClientId, then GIDServerClientID in Info.plist.
• Android web client id: the com.oauthessentials.GOOGLE_WEB_CLIENT_ID meta-data of AndroidManifest.xml, then the default_web_client_id string generated by the Firebase google-services Gradle plugin from google-services.json.

When none is found, the call rejects with CONFIGURATION_ERROR and the message lists these sources.

In code. Pass { iosClientId, webClientId }; each platform picks the id it needs, and a passed id wins over the config:

const GOOGLE_CLIENT_IDS = {
  iosClientId: 'YOUR_IOS_CLIENT_ID.apps.googleusercontent.com',
  webClientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com',
};

const credential = await googleSignIn(GOOGLE_CLIENT_IDS);

• iOS uses iosClientId and webClientId as the default serverClientId.
• Android uses webClientId.

Either id can be omitted to read only that one from the config. A single string still works, but it is used as is: it must be the iOS client id on iOS and the web client id on Android. The Android client id is never passed.

4.2. iOS Configuration (Info.plist)

You need to add a URL scheme to your iOS app's Info.plist file: the iOS client id split by ., reversed and joined (it is REVERSED_CLIENT_ID in Firebase's GoogleService-Info.plist). It is required even when the client id comes from GoogleService-Info.plist. With Expo, the config plugin google option does it for you.

When the scheme is missing, googleSignIn and googleSilentSignIn reject with CONFIGURATION_ERROR and the error message contains the exact scheme to add.

Location: ios/YourAppName/Info.plist

Add the following configuration:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <!-- This is your iOS Client ID in reverse notation -->
      <string>com.googleusercontent.apps.YOUR_IOS_CLIENT_ID</string>
    </array>
  </dict>
</array>

Info.plist Generator

Use this tool to generate the correct Info.plist entry:

Info.plist Entry Generator

iOS Client ID:

Copy this to your Info.plist:

Manual Steps:

1. Open ios/YourAppName/Info.plist in Xcode or text editor
2. Find the <dict> section (usually near the top)
3. Add the generated CFBundleURLTypes configuration
4. Replace YOUR_IOS_CLIENT_ID with your actual iOS Client ID (without the .apps.googleusercontent.com part)

Example:

If your iOS Client ID is:

1234567890-abcdefghijklmnop.apps.googleusercontent.com

Your reversed URL scheme should be:

com.googleusercontent.apps.1234567890-abcdefghijklmnop

To call googleSignIn() without client ids, add them to Info.plist too (or add the Firebase GoogleService-Info.plist to the app target, which gives the iOS client id but not GIDServerClientID):

<key>GIDClientID</key>
<string>1234567890-abcdefghijklmnop.apps.googleusercontent.com</string>
<key>GIDServerClientID</key>
<string>YOUR_WEB_CLIENT_ID.apps.googleusercontent.com</string>

4.3. Android Configuration

To call googleSignIn() without client ids, add the web client id to android/app/src/main/AndroidManifest.xml, inside <application>:

<application>
  <meta-data
    android:name="com.oauthessentials.GOOGLE_WEB_CLIENT_ID"
    android:value="YOUR_WEB_CLIENT_ID.apps.googleusercontent.com" />
</application>

With Firebase, the google-services Gradle plugin already generates the default_web_client_id string from google-services.json, which the library reads when the meta-data is missing. Nothing else to add to the native project.

Make sure:

• You use the Web client id (not the Android one), in the config or as webClientId
• You created the Android OAuth client ID in Google Cloud Console
• You added the SHA-1 of every signing key, including Play App Signing
• Your package name matches

Step 5: Verify Setup

iOS Verification

1. Open Xcode
2. Select your target → Info tab
3. Expand "URL Types"
4. You should see your reversed client ID as a URL scheme

Android Verification

1. Run your app on an Android device/emulator
2. Make sure Google Play Services is installed and updated
3. Test the sign-in flow

Common Issues

iOS: CONFIGURATION_ERROR

• The message says what is missing: the iOS client id (pass iosClientId, set GIDClientID or add GoogleService-Info.plist to the app target) or the exact URL scheme to add to CFBundleURLSchemes
• Make sure iosClientId is the iOS client id: a web client id there produces a scheme that does not match
• Rebuild the iOS app after changing Info.plist (or run npx expo prebuild with Expo)

Android: CONFIGURATION_ERROR

• The web client id is missing: pass { webClientId }, add the com.oauthessentials.GOOGLE_WEB_CLIENT_ID meta-data or use google-services.json with the google-services Gradle plugin (the web client id, not the Android one)
• Rebuild the Android app after changing AndroidManifest.xml (or run npx expo prebuild with Expo)

Both: native module "OauthEssentials" not found

• The app binary does not contain the library: rebuild it after installing (pod install in ios/, then build again; reloading Metro is not enough) and make sure the New Architecture is enabled
• In Expo Go the error says the library does not work there: use a development build (see Expo)

iOS: "No application found to handle URL"

• Verify your CFBundleURLSchemes matches your reversed iOS Client ID exactly
• Make sure there are no typos or extra spaces
• Rebuild your iOS app after making changes

Android: "NOT_SUPPORTED_ERROR"

• Install Google Play Services on your device/emulator
• Update Google Play Services to the latest version
• Use a device with Google Play Store (not AOSP builds)

Android: "DEVELOPER_ERROR"

• Verify your SHA-1 certificate fingerprint is correct
• Make sure package name matches exactly
• Wait a few minutes after creating credentials (Google takes time to propagate changes)

Both: "Invalid Client ID"

• Double-check iosClientId is the iOS client id and webClientId the Web client id
• Verify the client ID is copied correctly with no extra spaces
• Make sure the iOS/Android client IDs are created and active in Google Cloud Console

Security Best Practices

1. Never commit client IDs to public repositories

   • Use environment variables or config files (added to .gitignore)
   • Example: .env file with GOOGLE_WEB_CLIENT_ID=...

2. Use different credentials for development and production

   • Create separate Google Cloud projects or OAuth clients
   • Use different SHA-1 fingerprints for debug and release builds

3. Verify tokens on your backend

   • Always validate the idToken server-side
   • See Google Identity: Authenticate with a backend server

Reference Links

• Google Cloud Console
• Google Sign-In for iOS Documentation
• Google Sign-In for Android Documentation
• OAuth 2.0 Client IDs
• Backend Token Verification

Complete Example

import React from 'react';
import { Button, View, Text } from 'react-native';
import {
  googleSignIn,
  isCredentialError,
  GOOGLE_ID_SUPPORTED,
  CredentialsType,
  CredentialError,
} from 'react-native-oauth-essentials';

// Your OAuth 2.0 client ids from Google Cloud Console
const GOOGLE_CLIENT_IDS = {
  iosClientId: 'YOUR_IOS_CLIENT_ID.apps.googleusercontent.com',
  webClientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com',
};

export default function GoogleSignInExample() {
  const [user, setUser] = React.useState(null);

  async function handleGoogleSignIn() {
    // Android: false without Google Play Services
    if (!GOOGLE_ID_SUPPORTED) {
      alert('Google Sign-In is not available on this device');
      return;
    }

    try {
      const credential = await googleSignIn(GOOGLE_CLIENT_IDS, {
        authorizedAccounts: true,  // Android only
        autoSelectEnabled: false,  // Android only
      });

      if (credential.type === CredentialsType.GOOGLE_ID) {
        setUser(credential.data);
        console.log('User signed in:', credential.data);

        // Send idToken to your backend for verification
        await verifyWithBackend(credential.data.idToken);
      } else if (credential.type === CredentialsType.CANCELLED) {
        console.log('User cancelled sign-in');
      }
    } catch (error) {
      if (isCredentialError(error, CredentialError.CONFIGURATION_ERROR)) {
        console.error(error.message); // setup problem: missing client id or iOS URL scheme
      }
      console.error('Google Sign-In Error:', error);
      alert('Sign-in failed');
    }
  }

  async function verifyWithBackend(idToken: string) {
    try {
      const response = await fetch('https://yourapi.com/auth/google', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ idToken }),
      });

      const data = await response.json();
      console.log('Backend verification:', data);
    } catch (error) {
      console.error('Backend verification failed:', error);
    }
  }

  return (
    <View style={{ padding: 20 }}>
      {user ? (
        <View>
          <Text>Welcome, {user.displayName}!</Text>
          <Text>Email: {user.email}</Text>
        </View>
      ) : (
        <Button title="Sign in with Google" onPress={handleGoogleSignIn} />
      )}
    </View>
  );
}

Next Steps

After successfully setting up Google OAuth:

1. Test on both iOS and Android devices
2. Implement backend token verification
3. Handle user data securely
4. Set up proper error handling
5. Consider adding other sign-in methods (Apple, Password)

Need help? Check the Usage Guide for more examples.