Skip to content

Home

Jump to bottom
Nate River edited this page Oct 16, 2023 · 150 revisions
Clone this wiki locally

Welcome to Simple Google Sign-In wiki!

The asset provides Google sign-in with OAuth 2.0 for Android, iOS, Windows, macOS, Universal Windows Platform (UWP) and WebGL apps made with Unity.

Benefits

  • Cross-platform user auth for cross-platform games and apps
  • No plugins, no 3rd party libs, no dependencies
  • No impact to build size
  • Get access tokens for integration with other Google services
  • More security for client-server apps (get an access token on a client, get all user data on a server to avoid tampering)
  • JSON Web Tokens (JWT) validation
  • SFSafariViewController is used on iOS (required by App Store review)
  • Deep linking for Windows (UNITY_STANDALONE_WIN)

Alternatives

  • Sign-in with Play Games for Android (a part of Google Play Game Services, difficult to setup, super massive with a lot of dependencies, you can't get user email anymore in last versions)
  • Sign-in with Apple for iOS (native, but there are issues with getting user emails)
  • 3rd party SDK for other platforms

Terminology

  • URI is a uniform resource identifier.
  • URL is a uniform resource locator. URL is the subset of URI, it identifies the web address or location of a unique resource.
  • Custom URI scheme is the first part of a URI before :, it's used to determine an app that should be activated with deep linking. The second part of a URI is path, it can be used to pass additional parameters to the app. For example, simple.oauth:/oauth2callback/google has simple.oauth scheme and /oauth2callback/google path. Note that path should begin with a single slash, which is different from regular HTTP URLs.
  • Protocol for Universal Windows Platform is the same thing as Custom URI scheme for Android and iOS.
  • OAuth is Open Authorization protocol.
  • Google Authorization Endpoint is Google OAuth service where users can safely sign in.
  • Redirect URI is used by Google Authorization Endpoint to safely return data to your app (like auth codes, access tokens).
  • OAuth Redirect is a process of passing parameters with Redirect URI, it's considered to be a more secure way to transfer data.
  • Authorization Middleware is my implementation of an intermediary between Google and your app. It's used to workaround WebGL platform limitations.

Understanding how it works

  • Generic workflow (for platforms that support deep linking):

    • Your app navigates users to Google Authorization Endpoint using a default web browser (embedded webviews are not allowed)
    • Users perform sign-in using their login and password
    • Google Authorization Endpoint redirects users to Redirect URI (this can be a deep link when possible) and provides an authorization code to the app (as URI parameters)
    • The app is activated and obtains code
    • The app exchanges code for access token
    • The app requests user data with access token (ID, name, email and other data according access scope defined)

  • For Android, iOS, macOS, Windows and Universal Windows Platform (platforms that support deep linking):

    • Redirect URI is a deep link which activates the app and provides code in URI parameters

  • Loopback flow for Editor and Windows (optional):

    • This flow is optional for Windows (the generic workflow is used by default)
    • Redirect URI is http://localhost:PORT/ with a random unused port
    • The app listens to localhost using System.Net.HttpListener
    • The app obtains code and asks a user to close the browser tab and to return to the app
    • Further workflow is the same (exchanging code for access token, requesting user data)

  • Middleware flow for WebGL (the platform doesn't support deep linking and loopback):

    • OAuth Redirect to Authorization Middleware is used to temporary save code
    • The app obtains code from Authorization Middleware with a POST request
    • Further workflow is the same (exchanging code for access token, requesting user data)

Preconditions

  • For Android, iOS, macOS, Windows and UWP (platforms that support deep linking): COME UP WITH your Custom URI scheme (or Protocol). It MUST contain the period symbol .. In my example it is simple.oauth, but it can be jelly.bean (note that Custom URI scheme is not the same as your actual package name or bundle id).
  • For Android, iOS, UWP: enable deep linking as described in Unity documentation or as described below.
  • For Android: create AndroidManifest.xml inside Assets/Plugins/Android/, SET your Custom URI scheme inside, like <data android:scheme="simple.oauth" />. You can use AndroidManifestExample.xml from the asset as an example, just copy, rename and edit. AGAIN, DON'T FORGET TO REPLACE simple.oauth with your Custom URI scheme!
  • For iOS and macOS: navigate to Player Settings > Other > Configuration and add your Custom URI scheme to Supported URL schemes. In Xcode, make sure that the URL scheme is added (Register your URL scheme).
  • For Universal Windows Platform: navigate to Player Settings > Publishing Settings and set Protocol (it MUST contain a period symbol, for example simple.oauth), then enable InternetClient in Capabilities.
  • For Windows: refer to Settings for Windows section

Setup steps

  1. Visit https://console.cloud.google.com/apis/credentials
  2. Create a new app if needed
  3. Create OAuth client ID
    • For Android, iOS, macOS, Windows and UWP: select iOS (for all 3 platforms, it's not a typo) and fill Bundle ID with your app Custom URI scheme or Protocol (see Preconditions). AGAIN, IT SHOULD BE EXACTLY iOS (this is the most common mistake)! CredentialsUniversal
    • For Editor and Windows (optional): select Desktop app CredentialsDesktop
    • For WebGL select Web application and provide "Authorized JavaScript origins" (the URL of your published app) and "Authorized redirect URIs" (SET Authorization Middleware URL: https://hippogames.dev/api/oauth/redirect) CredentialsWebGL
  4. Copy Client ID
    • For Windows, WebGL and Editor: copy Client secret as well

Checklist

  • Custom URI scheme is picked, and it has a different value than simple.oauth
  • Custom URI scheme is set in 3 places: [1] Google Cloud credentials (Bundle ID), [2] Resources/GoogleAuthSettings.asset, [3] your application manifest (AndroidManifest.xml for Android, Supported URL schemes for iOS, Protocol for UWP)

Usage

  1. Check our Example scene and C# code of Example.cs
  2. Configure Resources/GoogleAuthSettings.asset
    • For Android, iOS, macOS, Windows and UWP: set Client ID and Custom URI scheme (or Protocol)
    • For WebGL, Editor and Windows (optional): set Client ID and Client secret
    • Check Access Scopes (openid, email, profile are required to get UserInfo)
  3. Create an instance of GoogleAuth and pass GoogleAuthSettings to the constructor
  4. Create a new instance of GoogleAuth and call GoogleAuth.SignIn
  5. Create OnSignIn callback as the first argument for GoogleAuth.SignIn to obtain UserInfo
  6. Build and test
  7. Write a review on the Asset Store :)

Best practices

  • Call GoogleAuth.SignIn with caching: true to return cached UserInfo
  • Call GoogleAuth.SignIn with caching: false to request UserInfo from Google
  • Call GoogleAuth.GetAccessToken instead of GoogleAuth.SignIn if you need an access token only (and don't need UserInfo)
  • You can use GoogleAuth.SavedAuth to get TokenResponse or UserInfo (don't forget to check all values for null)
  • Call GoogleAuth.SignOut when 'Sign out` button is pressed (optional)
  • Disable debug logs for production by setting GoogleAuth.DebugLog = false

Next steps (optional)

  • You can add extra access scopes in Resources/GoogleAuthSettings.asset
  • If you have a backend (server), send TokenResponse to it (to avoid tapmering user data when sending from clients to your server)
  • Validate JSON Web Token (JWT) encoded in TokenResponse.IdToken on your server (refer to JWT class for parsing and signature validation example)
  • For Editor and Windows (optional), you can modify StandaloneTemplate.html (used by the loopback flow) to edit the message "Success! Please close the browser tab and return to the app."
  • For Windows, check Settings for Windows
  • For WebGL, consider deploying your own Authorization Middleware

Can I trust to Authorization Middleware? Is it secure to use a 3rd party service?

  • Authorization Middleware can't exchange code for access token without knowing both client secret and code verifier. Only the app itself can exchange code for access token.
  • You can implement your own trusted Authorization Middleware. Please feel free to request ASP.NET source codes from me.
  • You can hire me to setup your own trusted Authorization Middleware.

Notes

  • Google OpenID is not the same as Play Games ID (Google Play Game Services), but they both have the same user email
  • Don't use default credentials that come with the asset in production, they are for test purposes only and can be disabled/blocked
  • You can use the same iOS credentials for Android, iOS, Windows and UWP

Known issues

  • AndroidManifest.xml workaround for Unity 2022
  • Some web browsers may block deep links by default. Test on another device or browser if redirecting doesn't happen.
  • For security reasons Google allows OAuth in trusted browsers only. Requests from embedded browsers (web views) and emulators may be blocked.
  • When using deep linking for Windows, Force Single Instance should be enabled in Player Settings.
  • When using the loopback flow for Editor and Windows (optional), HttpListener is blocking the main thread if Run In Background is unset. To avoid this, set Run In Background in Player Settings.
  • The App Store review team may reject your app with the reason "poor user experience" if you're using Sign in with Google as a primary method. Implement Sign in with Apple a primary method or implement the functionality to create user accounts inside the app.

Support

Links