-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Nate River edited this page May 26, 2024
·
171 revisions
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.
- 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)
-
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
-
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 ispath
, it can be used to pass additional parameters to the app. For example,simple.oauth:/oauth2/google
hassimple.oauth
scheme and/oauth2/google
path. Note thatpath
should begin with a single slash, which is different from regular HTTP URLs. -
Protocol
for Universal Windows Platform is the same thing asCustom 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 GoogleAuthorization Endpoint
to safely return data to your app (like auth codes, access tokens). -
OAuth Redirect
is a process of passing parameters withRedirect 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.
-
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 toRedirect URI
(this can be a deep link when possible) and provides an authorizationcode
to the app (as URI parameters) - The app is activated and obtains
code
- The app exchanges
code
foraccess token
- The app requests user data with
access token
(ID, name, email and other data according access scope defined)
- Your app navigates users to Google
-
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 providescode
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
ishttp://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
foraccess token
, requesting user data)
-
Middleware flow for WebGL (the platform doesn't support deep linking and loopback):
-
OAuth Redirect
toAuthorization Middleware
is used to temporary savecode
- The app obtains
code
fromAuthorization Middleware
with a POST request - Further workflow is the same (exchanging
code
foraccess token
, requesting user data)
-
- For Android, iOS, macOS, Windows and UWP (platforms that support deep linking): COME UP WITH your
Custom URI scheme
(orProtocol
). It MUST contain the period symbol.
and small alphanumeric symbols only (no spaces, no undercores). In my example it issimple.oauth
, but it can bejelly.bean
(note thatCustom 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
insideAssets/Plugins/Android/
, SET yourCustom URI scheme
inside, like<data android:scheme="simple.oauth" />
. You can useAndroidManifestExample.xml
from the asset as an example, just copy, rename and edit. AGAIN, DON'T FORGET TO REPLACEsimple.oauth
with yourCustom URI scheme
! - For iOS and macOS: navigate to
Player Settings > Other > Configuration
and add yourCustom URI scheme
toSupported 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 setProtocol
(it MUST contain a period symbol, for examplesimple.oauth
), then enableInternetClient
inCapabilities
. - For Windows: refer to Settings for Windows section
- For Editor: Set
Allow downloads over HTTP = Always allowed
(Unity 2022+)
- Visit https://console.cloud.google.com/apis/credentials
- Create a new app if needed
- Create OAuth client ID
- For Android, iOS, macOS, Windows and UWP: select
iOS
(for all 3 platforms, it's not a typo) and fillBundle ID
with your appCustom URI scheme
orProtocol
(see Preconditions). AGAIN, IT SHOULD BE EXACTLYiOS
(this is the most common mistake)! - For Editor and Windows (optional): select
Desktop app
- For WebGL select
Web application
and provide "Authorized JavaScript origins" (the URL of your published app) and "Authorized redirect URIs" (SETAuthorization Middleware
URL:https://hippogames.dev/api/oauth/redirect
)
- For Android, iOS, macOS, Windows and UWP: select
- Copy
Client ID
(check if you didn't copy it with extra spaces)- For Windows, WebGL and Editor: copy
Client secret
as well
- For Windows, WebGL and Editor: copy
- Configure
Resources/GoogleAuthSettings.asset
- For Android, iOS, macOS, Windows and UWP: set
Client ID
andCustom URI scheme
(orProtocol
) - For WebGL, Editor and Windows (optional): set
Client ID
andClient secret
- Check
Access Scopes
(openid
,email
,profile
are required to getUserInfo
)
- For Android, iOS, macOS, Windows and UWP: set
-
Custom URI scheme
is picked, and it has a different value thansimple.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) -
ClientId
is copied to Resources/GoogleAuthSettings.asset (check if you didn't paste it with extra spaces)
- Check our
Example
scene and C# code ofExample.cs
- Create an instance of
GoogleAuth
- Call
GoogleAuth.SignIn
orGoogleAuth.GetAccessToken
- Create
OnSignIn
orOnGetAccessToken
callbacks - Build and test
- Write a review on the Asset Store :)
- Call
GoogleAuth.SignIn
withcaching: true
to return cachedUserInfo
- Call
GoogleAuth.SignIn
withcaching: false
to requestUserInfo
from Google - Call
GoogleAuth.GetAccessToken
instead ofGoogleAuth.SignIn
if you need an access token only (and don't needUserInfo
) - You can use
GoogleAuth.SavedAuth
to getTokenResponse
orUserInfo
(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
- 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 inTokenResponse.IdToken
on your server (refer toJWT
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
- You can use this asset with
async
methods, just refer toGoogleAuthAsync.cs
for examples
-
Authorization Middleware
can't exchangecode
foraccess token
without knowing bothclient secret
andcode verifier
. Only the app itself can exchangecode
foraccess token
. - It's recommended to deploy your own trusted
Authorization Middleware
to handle sensitive data. Please refer to Authorization Middleware article.
- 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 - Check Manual cancellation if needed