VK - hippogamesunity/SimpleSignIn GitHub Wiki

Welcome to Simple VK Sign-In wiki!

The asset provides VK (Vkontakte) sign-in with OAuth 2.0 for Android, iOS, Windows, Mac, 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
  • More security for client-server apps (get an access token on a client, get all user data on a server to avoid tampering)

Alternatives

  • VK SDK (native, not cross-platform)

Terminology

Understanding how it works

  • General workflow:

    • Your app navigates users to VK Authorization Endpoint using a default web browser (embedded webviews are not allowed)
    • Users perform sign-in using their login and password (if they are not signed in already)
    • VK 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, Universal Windows Platform (these platforms support deep linking):

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

  • For Windows, Mac, WebGL and Editor (these platforms don't support deep linking):

    • Redirect URI is empty (not used), in this case Authorization Middleware will temporarily save code that can be further requested by the app
    • 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. VK doesn't allow deep links for Authorized redirect URI (deep linking works for Android, iOS and UWP).
  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 VK Authorization Endpoint with state and Redirect URI parameters
  • redirect is called by VK 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 Secure key. Only the app itself can exchange code for access token.
  • You can implement your own trusted Authorization Middleware. Feel free to request source code (ASP.NET).
  • You can hire me to setup your own trusted Authorization Middleware (ASP.NET web-hosting required).

Preconditions

  • Pick your Custom URI scheme (or Protocol). In my example it is simple.oauth, but it can be myapp.auth (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: navigate to Player Settings > Other > Configuration and add your Custom URI scheme to Supported URL schemes.
  • 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.

Setup steps

  1. Visit VK Developers
  2. Create a new Standalone app
  3. Go to settings and enable Open API
  4. Set Website address as https://hippogames.dev
  5. Set Base domain as hippogames.dev
  6. Set Authorized redirect URI as https://hippogames.dev/api/oauth/redirect (add a new address)
  7. Copy App ID and Secure key

Usage

  1. Check our Example scene and C# code of Example.cs
  2. Configure Resources/Settings.asset
    • For Windows, Mac and WebGL: set App ID and Secure key
    • For Android, iOS, UWP: set Custom URI SCheme (Protocol) as well
  3. Call VKAuth.SignIn
  4. Create OnSignIn callback as the only argument for VKAuth.SignIn to obtain UserInfo
  5. Build and test
  6. Write a review on the Asset Store :)

Best practices

  • Before calling VKAuth.SignIn, check if a user is already signed in (VKAuth.SavedAuth != null)
  • If so, get VKAuth.SavedAuth.UserInfo and do not call VKAuth.SignIn
  • Create Sign out button if needed (call VKAuth.SignOut)
  • Remove debug logs in VKAuth.Log for production

Next steps (optional):

  • You can get more user fields in RequestUserInfo method, add them to the request URL and extend UserInfo class
  • Subscribe to VKAuth.OnTokenResponse event to get TokenResponse (alternatively, get it from VKAuth.SavedAuth.TokenResponse)
  • If you have a backend (server), send TokenResponse to it (to avoid tapmering user data when sending from clients to your server)
  • 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 App ID, Secure key 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 leave a review on the Asset Store

Known issues

Support

Links