![Sign in with Google](https://developers.google.com/static/identity/assets/images/samples/siwg-case-studies.jpg)

## 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](https://developers.google.com/identity/protocols/oauth2) 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.

> [!IMPORTANT]
> **Important:** This checklist tracks only the major milestones and is **not** a substitute for the main [best practices](https://developers.google.com/identity/siwg/best-practices#best-practices-all) document. To ensure you are meeting all security and user experience requirements, it is essential to review the detailed guidance for each item.

### Phase 0: Getting started (optional)

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

Web: Complete the
[One-Tap](https://codelabs.developers.google.com/codelabs/google-one-tap#0) and
[Sign in with Google button](https://codelabs.developers.google.com/codelabs/sign-in-with-google-button#0) codelab to build a basic
web integration.

Android: Complete
the [Android](https://codelabs.developers.google.com/sign-in-with-google-android#0) codelab to learn the fundamentals on Android's
Credential Manager.

iOS: Complete the
[iOS](https://codelabs.developers.google.com/codelabs/sign-in-with-google-ios#0) 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](https://developers.google.com/identity/siwg/best-practices#gcp-environments) and
[brands](https://developers.google.com/identity/siwg/best-practices#gcp-brands).

Complete the
[OAuth consent screen](https://developers.google.com/identity/siwg/best-practices#oauth-consent-screen) configuration with all required
branding and support information.

Create the correct
[OAuth Client ID type](https://developers.google.com/identity/siwg/best-practices#oauth-client-id) 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](https://developers.google.com/identity/siwg/best-practices#ux-best-practices) to maximize
user adoption and trust.

Web: Use the
[official JavaScript library](https://developers.google.com/identity/siwg/best-practices#web-js-library) and integrate both Button and
One Tap flows.

Android: Use the
[official Android SDK](https://developers.google.com/identity/siwg/best-practices#android-sdk) to integrate.

iOS: Use the
[official iOS SDK](https://developers.google.com/identity/siwg/best-practices#ios-sdk) to integrate.

In your backend development:

Implement
[secure backend validation of Google ID tokens](https://developers.google.com/identity/siwg/best-practices#backend-validation).

Use the
[`sub` claim](https://developers.google.com/identity/siwg/best-practices#sub-claim) as the unique and permanent user identifier in your
system.

Plan for the
[separation of authentication and authorization](https://developers.google.com/identity/siwg/best-practices#auth-separation) 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](https://developers.google.com/identity/siwg/best-practices#security-practices).

Complete the
[OAuth App Verification](https://developers.google.com/identity/siwg/best-practices#oauth-verification) process before launch.

Ensure your
application correctly handles [token revocation](https://developers.google.com/identity/siwg/best-practices#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](https://developers.google.com/identity/protocols/oauth2/policies)
to ensure complete compliance.

### Google Cloud project setup

This section outlines the best practices for structuring your Google Cloud
projects and [setting up](https://support.google.com/cloud/answer/15544987) 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](https://developers.google.com/identity/protocols/oauth2/policies#separate-projects) 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](https://support.google.com/cloud/answer/15544987?ref_topic=15540269&sjid=4436809796326311712-NA#zippy=%2Cuser-support-email) 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](https://developers.google.com/identity/protocols/oauth2/policies#register).
- **Completing OAuth app verification**

  For your production app to display its name and logo, it must be
  [verified](https://support.google.com/cloud/answer/9110914). The type of verification depends
  on the data you request from the user.
  - **Sign in with Google** only requests [authentication scopes](https://developers.google.com/identity/protocols/oauth2/scopes#oauth2) (`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](https://developers.google.com/identity/protocols/oauth2/policies#app-identity).

  To help you plan your launch timeline, Google provides a
  [breakdown](https://support.google.com/cloud/answer/13463817?ref_topic=13460882&sjid=5557944111643869906-NA#zippy=%2Cwhat-are-the-different-types-of-verification-that-google-requires-for-accessing-user-data-via-oauth) of the different verification
  types and their expected review times. For more details on the verification
  policies, see the [OAuth App Verification Help Center](https://support.google.com/cloud/answer/13463073).

### 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](https://developers.google.com/identity/sign-in/ios/backend-auth#java) for more details.
  - **Use the `sub` claim** : Only use [Google ID token](https://developers.google.com/identity/gsi/web/reference/js-reference#credential) `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](https://developers.google.com/identity/gsi/web/guides/revoke), [Android](https://developers.google.com/android/reference/com/google/android/gms/auth/api/identity/AuthorizationClient#public-abstract-taskvoid-revokeaccess-revokeaccessrequest-request), [iOS](https://developers.google.com/identity/sign-in/ios/disconnect)
  documentation. For server side revocation, visit
  [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server#tokenrevoke).
- **Separate authentication from authorization**

  The Sign in with Google SDKs only request the [scopes](https://developers.google.com/identity/protocols/oauth2/scopes#oauth2)
  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](https://developers.google.com/identity/gsi/web/guides/overview#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](https://developers.google.com/identity/sign-in/web/backend-auth). For more
  comprehensive protection against various threats, implement the
  [Security Bundle](https://developers.google.com/identity/siwg/security-bundle) and
  [Cross-Account Protection (RISC)](https://developers.google.com/identity/protocols/risc). Additionally, for iOS
  apps, it is highly recommended to integrate [App Check](https://developers.google.com/identity/sign-in/ios/appcheck) 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](https://developers.google.com/identity/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](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out) and
  [Android](https://developer.android.com/identity/sign-in/credential-manager-siwg-implementation#use-previously), and [state restoration](https://developers.google.com/identity/sign-in/ios/sign-in#2_attempt_to_restore_the_users_sign-in_state)
  for iOS 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](https://developers.google.com/identity/siwg/best-practices#token-revocation) and remove the Google
    association from your database.

## Android implementation (apps \& games)

### Standard Android apps

For Android implementations, you should use the [Credential Manager](https://developer.android.com/identity/credential-manager).
It is the recommended approach for handling user credentials and provides a
unified, secure, and consistent sign-in experience on Android.

> [!IMPORTANT]
> **Important:** Google **does not support** the use of embedded webviews for sign-in. Using embedded webviews (e.g., `WebView` on Android) exposes users to security risks and is blocked by Google's OAuth 2.0 policies. For more information, see this [blog post](https://developers.googleblog.com/en/upcoming-security-changes-to-googles-oauth-20-authorization-endpoint-in-embedded-webviews/).

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](https://developer.android.com/identity/sign-in/credential-manager-siwg#use-credential): 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](https://developer.android.com/identity/sign-in/credential-manager-siwg#use-sign): 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](https://developer.android.com/identity/sign-in/credential-manager-siwg#prerequisites) 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](https://developer.android.com/identity/sign-in/credential-manager-siwg-implementation#create-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](https://developer.android.com/identity/sign-in/credential-manager-siwg-implementation#create-bottom) 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](https://developer.android.com/identity/sign-in/credential-manager-siwg-implementation#use-previously) 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 information in the
[Cross-platform continuity with SiWG](https://developer.android.com/games/pgs/platform-authentication#cross-os-continuity)
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](https://developers.google.com/identity/sign-in/ios/start-integrating).
This library provides the most secure and user-friendly way to integrate Sign
in with Google.

> [!IMPORTANT]
> **Important:** Google **does not support** the use of embedded webviews for sign-in. Using embedded webviews (e.g., `WKWebView` on iOS) exposes users to security risks and is blocked by Google's OAuth 2.0 policies. For more information, see this [blog post](https://developers.googleblog.com/en/upcoming-security-changes-to-googles-oauth-20-authorization-endpoint-in-embedded-webviews/).

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](https://developers.google.com/identity/sign-in/ios/sign-in#3_add_a_google_sign-in_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.

### Restore user sign-in state

- **Seamless return** : When your app starts up, call `restorePreviousSignIn` to [attempt to restore](https://developers.google.com/identity/sign-in/ios/sign-in#2_attempt_to_restore_the_users_sign-in_state) the sign-in state of users who have already authenticated using Google. This ensures returning users don't have to sign in every time they open your app, providing a frictionless experience comparable to automatic sign-in on other platforms.

### 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](https://developers.google.com/identity/sign-in/ios/appcheck) 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](https://developers.google.com/identity/gsi/web/guides/overview). This is the latest
generation of Google's identity libraries for the web and includes both the
[Button](https://developers.google.com/identity/gsi/web/guides/personalized-button) and [One Tap](https://developers.google.com/identity/gsi/web/guides/features) 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](https://developers.google.com/identity/gsi/web/guides/personalized-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](https://developers.google.com/identity/gsi/web/guides/display-button#redirect_mode) versus [popup](https://developers.google.com/identity/gsi/web/guides/display-button#popup_mode)). 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](https://developers.google.com/identity/gsi/web/guides/integrate#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](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out) 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](https://developers.google.com/identity/gsi/web/guides/integrate#one_tap_considerations) section for optimal configuration and performance.