Discord - hippogamesunity/SimpleSignIn GitHub Wiki

Welcome to Simple Discord Sign-In wiki!

The asset provides [Sign in with Discord] using 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 auth libs, no dependencies
  • No impact to build size
  • Get access tokens to make Discord 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

  • Your app navigates users to Discord Authorization Endpoint in a web browser
  • Users perform sign-in using their login and password
  • Discord Authorization Endpoint redirects users to Redirect URI (which is Authorization Middleware) and provides an authorization code
  • Authorization Middleware transmits code to your app (using deep linking when possible)
  • The app exchanges code for access token and requests user info with it

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 Discord for developers / Applications, create a new account if needed
  2. Create a new app if needed, or use an existing app
  3. Navigate to OAuth2 tab and copy Client ID and Client Secret
  4. Add https://hippogames.dev/api/oauth/redirect to Redirects (for Editor mode, add http://localhost:20561/ as well)
  5. Return to Unity and configure Resources/DiscordAuthSettings.asset
    • set Client ID and Client Secret
    • set Custom URI Scheme from Preconditions
    • set Access Scopes (optional)

Checklist

  • Custom URI scheme is picked, and it has a different value than simple.oauth
  • Custom URI scheme is set in 2 places: [1] Resources/DiscordAuthSettings.asset, [2] your application manifest (AndroidManifest.xml for Android, Supported URL schemes for iOS, Protocol for UWP)
  • Resources/DiscordAuthSettings.asset contains valid settings different from that come with the asset

Usage

  1. Check our Example scene and C# code of Example.cs
  2. Create an instance of DiscordAuth
  3. Call DiscordAuth.SignIn or DiscordAuth.GetTokenResponse
  4. Create OnSignIn or OnGetTokenResponse callbacks
  5. Build and test
  6. Write a review on the Asset Store :)

API reference for DiscordAuth class

Method Arguments Description
DiscordAuth (constructor) DiscordAuthSettings settings = null A constructor that accepts an instance of DiscordAuthSettings. If Null is passed, it will load default settings from Resources (DiscordAuthSettings scriptable object).
SignIn Action<bool, string, UserInfo> callback, bool caching = true Performs sign-in and returns an instance of UserInfo with callback. If caching is True, it will return the previously saved UserInfo.
SignOut bool revokeAccessToken = false Performs sign-out. Can revoke Access Token if requested.
GetTokenResponse Action<bool, string, TokenResponse> callback Returns an instance of TokenResponse which contains AccessToken and other related information (expiration, type and other). It may also contain IdToken (JWT), if requested with openid scope, which contains information about the user.
TryResume Refer to code This can be called on app startup to continue OAuth. In some scenarios, the app may be terminated while the user performs sign-in on Discord website.
SignInAsync Async version of SignIn.
GetTokenResponseAsync Async version of GetTokenResponse.

Best practices

  • Call DiscordAuth.SignIn with caching: true to return cached UserInfo.
  • Call DiscordAuth.GetTokenResponse instead of DiscordAuth.SignIn if you need an access token only (and don't need UserInfo).
  • You can use DiscordAuth.SavedAuth to get TokenResponse or UserInfo (don't forget to check all values for null).
  • Disable debug logs for production by setting DiscordAuth.DebugLog = false.
  • Check Manual cancellation if needed.

Security concerns

  • Please refer to User data disclosure.
  • It's recommended to deploy your own trusted Authorization Middleware to handle sensitive data. Please refer to Authorization Middleware article.
  • We have to store Secret Key inside the client app. If it's important for you, you can migrate all C# code to your ASP.NET backend.

Known issues

Support

Links