X - hippogamesunity/SimpleSignIn GitHub Wiki

Welcome to Simple X Sign-In wiki!

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

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 X 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)
  • SFSafariViewController is used on iOS (required by App Store review)
  • Deep linking for Windows (UNITY_STANDALONE_WIN)

Terminology

Understanding how it works

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

    • Your app navigates users to X Authorization Endpoint using a default web browser (embedded webviews are not allowed)
    • Users perform sign-in using their login and password
    • X 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

  • Middleware flow for WebGL and Editor (platforms don'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 . and small alphanumeric symbols only (no spaces, no undercores). 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: 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 X Developer Portal and register
  2. Create a new app if needed (there may be a default app already, just rename it)
  3. Go to Keys and tokens > OAuth 2.0 Client ID and Client Secret, copy and save them
  4. Navigate to User authentication settings
    • Set App permissions (read is recommended)
    • Set Type of App (Native App is recommended)
    • Set App info > Callback URI / Redirect URL (add https://hippogames.dev/api/oauth/redirect and [Custom URI scheme]://oauth2/x (two slashes, replace the scheme by yours)
    • Add Website URL (put yours, create a one pager if needed)
    • Set Organization name, Terms of service and Privacy policy (optional, but recommended)
    • Press Save
  5. Navigate to Products section and enable X API v2
  6. Return to Unity and configure Resources/XAuthSettings.asset
    • Set Client Id and Client Secret obtained in step 3
    • Set Custom Uri Scheme (refer to Preconditions)
    • Make sure tweet.read and users.read added to Access Scopes

Checklist

  • Custom URI scheme is picked, and it has a different value than simple.oauth
  • Custom URI scheme is set in 3 places: [1] X Developer Portal (Callback URI / Redirect URL), [2] Resources/XAuthSettings.asset, [3] your application manifest (AndroidManifest.xml for Android, Supported URL schemes for iOS, Protocol for UWP)
  • Resources/XAuthSettings.asset contains valid settings

Usage

  1. Check our Example scene and C# code of Example.cs
  2. Create a new instance of XAuth, pass XAuthSettings to the constructor (optional)
  3. Call XAuth.SignIn or XAuth.GetAccessToken
  4. Create callbacks OnSignIn or OnGetAccessToken
  5. Build and test
  6. Write a review on the Asset Store :)

Best practices

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

Next steps (optional)

  • You can add extra access scopes in Resources/XAuthSettings.asset
  • If you have a backend (server), send TokenResponse to it (to avoid tapmering user data when sending from clients to your server)
  • For Windows, check Settings for Windows
  • For WebGL, consider deploying your own Authorization Middleware
  • You can use this asset with async methods, just refer to XAuthAsync.cs for examples

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 Client 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.

Notes

  • Please refer to User data disclosure
  • Don't use default credentials that come with the asset in production, they are for test purposes only and can be disabled/blocked
  • Check Manual cancellation if needed

Known issues

  • Please visit Common issues section
  • X may temporary block API calls if you make too many of them in a short period of time.
  • Refreshing access tokens doesn't work at the moment (community). Also note that offline.access scope is required to receive refresh tokens.
  • JWT are not supported by X.
  • You can't get user emails with X API v2 (community), even if Request email from users is set in App permissions.

Support

Links