Best Practices for Implementing Sign in with Google

Sign in with Google

Introduction

Sign in with Google (SiwG) is a fast and secure way for users to sign into your app or website. Implementing it properly not only simplifies the user registration process but also enhances the security of your application. This document outlines the best practices for integrating Sign in with Google across Web, Android, and iOS platforms. This documentation focuses solely on authentication. Authorization is beyond the scope of this document.

Integration milestone checklist

This checklist provides a high-level roadmap to guide you through the Sign in with Google integration process. It is organized into key phases, from initial setup to production launch. Use this list to track your progress and click the links to jump to the detailed guidance for each milestone.

Phase 0: Getting started (optional)

Jumpstart your integration with practical, step-by-step developer codelabs.

Web: Complete the One-Tap and Sign in with Google button codelab to build a basic web integration.

Android: Complete the Android codelab to learn the fundamentals on Android's Credential Manager.

iOS: Complete the iOS codelab for an introduction to the iOS SDK.

Phase 1: Google Cloud project & brand configuration

Ensure your project is set up for success from the start.

Structure Google Cloud projects for different environments and brands.

Complete the OAuth consent screen configuration with all required branding and support information.

Create the correct OAuth Client ID type for each platform (Web, Android, iOS).

Phase 2: Core development: frontend and backend

Build the secure server logic and the platform-specific user experience.

In your frontend development:

Review and apply the general User Experience (UX) best practices to maximize user adoption and trust.

Web: Use the official JavaScript library and integrate both Button and One Tap flows.

Android: Use the official Android SDK to integrate.

iOS: Use the official iOS SDK to integrate.

In your backend development:

Implement secure backend validation of Google ID tokens.

Use the sub claim as the unique and permanent user identifier in your system.

Plan for the separation of authentication and authorization scopes if applicable.

Phase 3: Security hardening & production launch

Ensure your integration is secure, compliant, and ready for production.

Review and implement security best practices.

Complete the OAuth App Verification process before launch.

Ensure your application correctly handles token revocation upon user account deletion.

General best practices (all platforms)

These practices apply regardless of the platform you are developing for. Developers should also review the general OAuth 2.0 Policies to ensure complete compliance.

This section outlines the best practices for structuring your Google Cloud projects and setting up your OAuth clients for security and branding compliance.

  • Use separate projects for testing and production

    Since some Google policies only apply to production applications, you must create separate projects in the Google Cloud Console for your different deployment environments, such as development, staging, and production. See this page for more details.

  • Use separate projects for each brand or domain

    If your organization manages multiple applications with distinct brands, each brand should have its own dedicated Google Cloud Project. The user-facing information shown on the consent screen, such as the application name, logo, support email, and links to the Terms of Service and Privacy Policy, is configured at the project level. This means that all OAuth client IDs created within a single project will share the same branding. Giving each brand its own project ensures that users see the correct branding and legal information for the specific application they are using.

  • Provide a generic support email

    The user support email address is displayed publicly on the OAuth consent screen. To maintain professionalism and ensure continuity, always configure a generic support email (e.g., support@yourdomain.com) in the Google Cloud Project's OAuth consent screen configuration instead of an individual employee's email address. See this page for more details.

  • OAuth client per platform

    You should create a separate OAuth client for each platform where your app runs (e.g., Web, Android, iOS), all within the same Google Cloud project. Using the correct client type for each platform is crucial for two main reasons:

    • Enhanced security: Each client type enables platform-specific security features. For example, an Android client can be locked down by its package name and signing certificate, preventing unauthorized use of your client ID.
    • Proper functionality: It ensures your application correctly integrates with platform-specific SDKs and features, like Credential Manager on Android or the Sign in with Google SDK for iOS.

    This structure also simplifies the user experience. Since consent is handled at the Google Cloud project level, users only need to grant it once to your application across all platforms. For more details, see the official OAuth 2.0 policies.

  • Completing OAuth app verification

    For your production app to display its name and logo, it must be verified. The type of verification depends on the data you request from the user.

    • Sign in with Google only requests authentication scopes (email, profile, and openid), it is subject to a simpler Brand Verification. This process is generally faster and focuses on confirming your brand's identity.

    To help you plan your launch timeline, Google provides a breakdown of the different verification types and their expected review times. For more details on the verification policies, see the OAuth App Verification Help Center.

Security & token handling

This section focuses on the runtime requirements and security measures developers must implement on their backend servers.

  • Integrate Google ID tokens with your backend

    • Verify the ID token: Always verify the integrity of the Google ID token on your backend server. Never trust a token just because it's sent from your client. It is recommended that you use a Google API client library for this verification. See Verify the Google ID token on your server side for more details.
    • Use the sub claim: Only use Google ID token sub field as identifier for the user as it is unique and stable among all Google Accounts and never reused. You should store the sub field and associate it with the user in your account management system. While you can use the email address from the ID token to check if the user has an existing account, don't use email address as an identifier because a Google Account can have multiple email addresses at different points in time.

  • Revoke tokens on account deletion

    It is highly recommended to provide users who sign in with Google the ability to disconnect their Google Account from your application. If a user chooses to delete their account, you must revoke all access and refresh tokens that your application has obtained.

    For details on client-side token revocation, visit Web, Android, iOS documentation. For server side revocation, visit Using OAuth 2.0 for Web Server Applications.

  • Separate authentication from authorization

    The Sign in with Google SDKs only request the scopes required for authentication. If your application needs access to other Google services (like Google Calendar or Drive), you should request those permissions separately and only when the user is trying to perform an action that requires them. See Separated authentication and authorization moments for more details.

  • Security best practices

    For a secure integration, always verify the ID token on your backend server using Google API client library. For more comprehensive protection against various threats, implement the Security Bundle and Cross-Account Protection (RISC). Additionally, for iOS apps, it is highly recommended to integrate App Check to ensure requests originate from your authentic app.

User experience (UX)

This section focuses on optimizing the user-facing elements and sign-in/sign-up flows.

  • Prominently display the button: The Sign in with Google button should be clearly visible and accessible on your sign-in and registration page.

  • Follow brand guidelines: Use the official Google-branded sign-in buttons to ensure a consistent and trustworthy user experience. Review the official Sign in with Google Branding Guidelines.

  • Frictionless sign-up: For new users, automatically create an account or direct users to new account creation flow upon their first successful Sign in with Google flow. On the backend, check if a user with the given sub ID exists; if not, create a new account. This minimizes registration effort.

  • Streamlined sign-in: For returning users, use the sub ID to identify and authenticate them into their existing account. Implement features like automatic sign-in for Web and Android to get them back into your app quickly and securely.

  • Manage Social Sign-In Methods: Provides a centralized "Connected Accounts" section in the user settings where users can manage various social sign-in methods (e.g. Google).

    • Linking: Provide a "Sign in with Google" button for existing users using other methods (e.g. username and password). Clicking this initiates the authentication flow to link their Google Account to their existing profile.

    • Unlinking: Provide an option to disconnect the account. To complete this, you must revoke tokens and remove the Google association from your database.

Android implementation (apps & games)

Standard Android apps

For Android implementations, you should use the Credential Manager. It is the recommended approach for handling user credentials and provides a unified, secure, and consistent sign-in experience on Android.

Use the OAuth Client ID for Android for implementation. If you already have Sign in with Google implementation in other platforms (e.g. Web, iOS), you should create a new OAuth Client ID Android type in the same Google Cloud project.

Implementation flows

A robust implementation should include both the Credential Manager's bottom sheet UI and a Sign in with Google Button.

  • Bottomsheet: This is a developer-driven, low-friction prompt presented by Credential Manager when a user lands on your sign-in screen.
  • Sign in with Google Button: This is the explicit, user-initiated sign-in flow that the user can tap to start.
  • A precise Google Cloud project configuration is essential. This involves creating the correct types of OAuth client IDs and providing specific details like your app's SHA-1 certificate fingerprint. To ensure a correct setup, follow the official Android developer guide precisely.

You should always include the Button flow as a user might dismiss the bottomsheet or have disabled it in their preferences. The Button ensures they can always initiate the sign-in process.

Placement strategy

  • Sign in with Google Button:

    • Location: Display the Sign in with Google button on your dedicated sign-up or sign-in pages.
    • Visibility: Place it prominently alongside other sign-in methods, such as username and password fields or other social sign-in providers.

  • Credential Manager Bottomsheet:

    • Trigger: The bottomsheet should be invoked automatically when your sign-in page launches or when the app starts. It shouldn't be triggered by a user tapping a button.
    • Automatic sign-in: For returning users, it is highly recommended to enable the automatic sign-in option within Credential Manager. This allows returning users (previously consented) to be signed back into your app without any interaction.

Android games

For Android games, Credential Manager is not the recommended approach. Instead, game developers should use the Google Play Games Services (PGS) approach which focuses on cross-platform Google identity using Sign in with Google. You can find more details in the Cross-platform Google identity using Sign in with Google documentation.

iOS implementation

Use the official Sign in with Google SDK

For iOS apps, you should use the official Sign in with Google for iOS and macOS SDK. This library provides the most secure and user-friendly way to integrate Sign in with Google.

Use the OAuth Client ID for iOS for implementation. If you already have Sign in with Google implementation in other platforms (e.g. Web, Android), you should create a new OAuth Client ID iOS type in the same Google Cloud project.

Add the "Sign in with Google" Button

  • Placement: Add the "Sign in with Google" button to your app's sign-in view, on both your sign-up and sign-in pages. Place it prominently alongside other sign-in methods, such as username and password fields or other social sign-in providers.
  • Use Recommended Components: Use the official button components provided by the SDK for both SwiftUI and UIKit. These components automatically generate a button that complies with Google's branding guidelines and are the recommended way to display the button.

Enhance security with App Check

Protect your backend resources from abuse by verifying that requests to your OAuth 2.0 client originate from your authentic app. App Check uses an attestation provider to verify that requests are from a genuine, untampered instance of your app, and rejects those that are not. See App Check for Google Sign-in on iOS for more details.

Web implementation

Guidance for websites and web applications.

Use the official Sign in with Google JavaScript library

For web implementations, you should use the official Sign in with Google JavaScript library. This is the latest generation of Google's identity libraries for the web and includes both the Button and One Tap features.

Use the OAuth Client ID for Web for implementation. If you already have Sign in with Google implementation in other platforms (e.g. Android, iOS), you should create a new OAuth Client ID Web type in the same Google Cloud project.

Implement both Button and One Tap flows

It is a best practice to implement both the "Sign in with Google" Button and the One Tap sign-in experience.

  • Sign in with Google Button: This is the explicit, user-initiated sign-in/up flow.
  • One Tap: This provides a frictionless, low-interruption sign-in or sign-up prompt.
  • Use the same OAuth Client ID for Web for both implementations.

You should always include the Button as a primary sign-in option. Users can dismiss or disable One Tap in their Google Account settings, but the Button will always be available, ensuring users are never blocked from signing in.

Placement strategy

  • Sign in with Google Button:

    • Location: Display the personalized Sign in with Google button on your dedicated sign-up or sign-in pages.
      • Note that there is no single pattern that works best for all sites (e.g. redirect versus popup). Your web design or UX team should test and optimize these flows to maximize completion rates for both sign-up and sign-in.
    • Visibility: Place it prominently alongside other sign-in methods, such as username and password fields or other social sign-in providers.
    • Review: The Sign in with Google button considerations section for optimal configuration and performance.

  • One Tap Prompt:

    • Location: Display the One Tap prompt on multiple pages of your website, such as individual product pages, article pages, even home page. The key benefit of One Tap is allowing users to sign in or create an account without navigating away from their current page.
    • Automatic sign-in: For returning users, it is highly recommended to enable the automatic sign-in option within One Tap. This allows returning users (previously consented) to be signed back into your app without any interaction.
    • Review: The One Tap considerations section for optimal configuration and performance.