Facebook

Welcome to Simple Facebook Sign-In wiki!

The asset provides Facebook sign-in with OAuth 2.0 for Android, iOS, Windows, Mac, Universal Windows Platform (UWP) and WebGL apps made with Unity. You can also get access tokens to make REST API calls to other Facebook services.

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 to make Facebook API calls
• 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

Alternatives

• Facebook SDK for Unity (massive, Standalone and WebGL not supported)

Terminology

• Please visit Terminology section

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:

  • 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)

Authorization Middleware

Authorization Middleware is used to workaround 2 issues:

1. Facebook doesn't allow deep links for Valid OAuth Redirect URIs (deep linking works for Android, iOS, macOS, UWP and ~Windows).
2. Standalone platforms (Windows and Mac) and WebGL don't support deep linking (direct OAuth Redirect is not possible in this case). Authorization Middleware handles OAuth Redirect and temporarily saves code that can be further requested by the app using POST.

Authorization Middleware has the following URL https://hippogames.dev/api/oauth/ and contains 3 methods:

• init should be called before navigating to Facebook Authorization Endpoint with state and Redirect URI parameters
• redirect is called by Facebook Authorization Endpoint with state and code after users perform sign-in
• getcode should be called from Standalone platforms (Windows and Mac) and WebGL to obtain code

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

• Authorization Middleware can't exchange code for access token without knowing code verifier. It's generated by your app and kept in secret. Only the app itself can exchange code for access token.
• It's recommended to deploy your own trusted Authorization Middleware to handle sensitive data. Please refer to Authorization Middleware article.

Preconditions

• Pick your Custom URI scheme (or Protocol). In my example it is simple.auth, 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.auth" />. You can use AndroidManifestExample.xml from the asset as an example, just copy, rename and edit. AGAIN, DON'T FORGET TO REPLACE simple.auth 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.auth), then enable InternetClient in Capabilities.
• For Windows: navigate to Player Settings and enable Resolution and Presentation > Force Single Instance and set Other Settings > Api Compatibility Level = .NET Framework

Setup steps

1. Visit Meta for Developers
2. Create a new app if needed (type: Authenticate and request data from users with Facebook Login)
3. Make sure that Facebook Login is added Use cases > Customize
4. Navigate to Facebook Login > Settings > Valid OAuth Redirect URIs and add https://hippogames.dev/api/oauth/redirect
5. Copy App ID
6. Set App Mode: Live and prepare your app for review (optional)
7. Return to Unity and configure Resources/FacebookAuthSettings.asset
   • For Android, iOS, macOS, Windows and UWP: set Client ID (which is App ID) and Custom URI scheme (or Protocol)
   • For WebGL: set Client ID (which is App ID) only

Usage

1. Check our Example scene and C# code of Example.cs
2. Create a new instance of FacebookAuth
3. Call FacebookAuth.SignIn or FacebookAuth.GetAccessToken (for further API calls)
4. Create OnSignIn or OnGetAccessToken callbacks
5. Build and test
6. Write a review on the Asset Store :)

Best practices

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

Next steps (optional)

• You can add extra access scopes in Resources/FacebookAuthSettings.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, 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."
• Consider deploying your own Authorization Middleware

Notes

• Please refer to User data disclosure
• Don't use the default App ID and Custom URI scheme that come with the asset in production, they are for test purposes only and can be disabled/blocked
• Don't forget to send your Facebook app for review to remove limitations
• Don't forget to leave a review on the Asset Store

Known issues

• Please visit Common issues section

Support

• FAQ & Troubleshooting
• Discord

Links

• Meta for Developers
• OIDC Code Flow with PKCE for Manually Built Facebook Login Flows
• OAuth 2.0