{"id":286,"date":"2016-03-18T07:15:10","date_gmt":"2016-03-18T07:15:10","guid":{"rendered":"http:\/\/is.ieis.tue.nl\/research\/hc\/gamebus\/?page_id=286"},"modified":"2016-03-18T07:15:10","modified_gmt":"2016-03-18T07:15:10","slug":"gamebus-oauth-token-manual","status":"publish","type":"page","link":"https:\/\/blog.gamebus.eu\/index.php\/gamebus-oauth-token-manual\/","title":{"rendered":"GameBus OAuth Token Manual"},"content":{"rendered":"<p>This is a page for developers who wish to leverage the <a title=\"API for pushing GameSessions\" href=\"http:\/\/is.ieis.tue.nl\/research\/hc\/gamebus\/?page_id=198\">GameBus Open API<\/a>. The page focuses on security aspects. Please contact us if you want to learn more about API functionality beyond what is documented <a title=\"API for pushing GameSessions\" href=\"http:\/\/is.ieis.tue.nl\/research\/hc\/gamebus\/?page_id=198\">here<\/a>. The\u00a0API should be accessed via\u00a0 HTTPS REST calls\u00a0with JSON payload and an <a href=\"https:\/\/tools.ietf.org\/html\/rfc6749\" target=\"_blank\" rel=\"noopener\">OAuth 2 token<\/a> in the <a href=\"https:\/\/tools.ietf.org\/html\/rfc7235#section-4.2\" target=\"_blank\" rel=\"noopener\">Authorization header<\/a>. In the following, we describe how to get a user-specific token for your app\/website\/device.<\/p>\n<p>Section 1 describes an approach to read the token from an app-specific file on the end user&#8217;s device. Section 2 describes an approach which sends GameBus tokens directly to your server. Section 3 describes how to decrypt the token values mentioned in sections 2 and 3.<\/p>\n<h3><strong>1. Reading GameBus Tokens from the end user Phone\/Tablet<\/strong><\/h3>\n<p>If you are a developer of a mobile health app (or any app that can benefit from the GameBus leaderboards) then you may want to access the GameBus API directly from the end user&#8217;s mobile device. We can make available an app-specific token on the end user&#8217;s file system. This approach only works on Android since iOS apps cannot access the full filesystem.<\/p>\n<p><a href=\"http:\/\/is.ieis.tue.nl\/research\/hc\/gamebus\/wp-content\/uploads\/2016\/03\/SDapp.png\" target=\"_blank\" rel=\"noopener\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter wp-image-289 size-medium\" src=\"http:\/\/is.ieis.tue.nl\/research\/hc\/gamebus\/wp-content\/uploads\/2016\/03\/SDapp-300x205.png\" alt=\"SDapp\" width=\"300\" height=\"205\" \/><\/a><\/p>\n<p>For the sake of prototyping, you can rely on the following example file content:<\/p>\n<pre>{\n \"playerId\":100023,\n \"token\":\"c7665dad-cbae-4037-a49a-c19b86fea1a0\"\n}<\/pre>\n<p>If you manage to push activity data for this test user with name &#8220;Fien&#8221;, then\u00a0please <a href=\"https:\/\/twitter.com\/gamebusapp\">send us<\/a>\u00a0the name of your app, an app logo as well as a short description. We will check the maturity of your integration and<\/p>\n<ul>\n<li>provide a &#8220;connect&#8221; button for your app in the GameBus base app, and<\/li>\n<li>provide you with the exact location of the GameBus token file corresponding to your app, and<\/li>\n<li>provide you with an app key to decrypt the token value in the\u00a0token file dedicated to your app (see <a name=\"#decrypting\"><\/a>the decryption section).<\/li>\n<\/ul>\n<h3><strong>2. Receiving the GameBus Token\u00a0on your API\/server<\/strong><\/h3>\n<p>If you are not providing an app on the end user&#8217;s device, we can provide from within the GameBus base app a &#8220;connect&#8221; button which will send the OAuth token to your app&#8217;s API server. The token will then be sent in encrypted form (see\u00a0<a name=\"#decrypting\"><\/a>the decryption section). When receiving such a request call, your server is expected to provide a user login page. When users authenticate successfully to your app, then:<\/p>\n<ol>\n<li>you should store the player ID and the token for future use for that user (note that you should also store the user ID which identifies the user in your app&#8217;s database), and<\/li>\n<li>you should return and end user oriented page which clarifies that\u00a0from now on\u00a0sessions will be sent to the user&#8217;s GameBus account.<\/li>\n<\/ol>\n<p>When users fail to authenticate, you may want to provide instructive feedback, also describing\u00a0options\u00a0to retry.<\/p>\n<p>If you wish to leverage this approach then please\u00a0<a href=\"https:\/\/twitter.com\/gamebusapp\">send us<\/a>:<\/p>\n<ul>\n<li>end-user friendly info:\n<ul>\n<li>the name of your app\/website,<\/li>\n<li>an app logo, as well as<\/li>\n<li>a short description, and<\/li>\n<li>the URL of a page with further information on your app\/website;<\/li>\n<\/ul>\n<\/li>\n<li>technical info:\n<ul>\n<li>the URL of the page where the users can connect after authenticating to your service (e.g.,\u00a0https:\/\/yourserver.org\/connect?userid={userId}&amp;token={gamebusToken});<\/li>\n<li>the URL of the page to disconnect previously connected users (e.g.,\u00a0https:\/\/yourserver.org\/disconnect?userid={userId}&amp;token={gamebusToken});<\/li>\n<li>the URL of the endpoint which we can call to test whether or not a specific GameBus user is connected successfully to your app\/website (e.g., https:\/\/yourserver.org\/status?userid={userId}&amp;token={gamebusToken}).<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p>Note that when you are developing an integration in between the GameBus API and a third party API then the URL for the \/connect endpoint should go to that third party API first and you should specify within that URL a\u00a0redirect URI\u00a0pointing to\u00a0your integration server. For example, the GameBus integration for <a href=\"http:\/\/www.moves-app.com\">http:\/\/www.moves-app.com<\/a> uses for \/connect a URL like:<\/p>\n<pre><code>https:\/\/api.moves-app.com\/oauth\/v1\/authorize?response_type=code&amp;client_id=1234&amp;scope=activity\n&amp;redirect_uri=https:\/\/integration-server.org\/api\/callback\/{dataProviderId}\/{userId}\/{gamebusToken}<\/code><\/pre>\n<p>In case you manage both the integration server as well as the game server\/API then you don&#8217;t have to use this redirect approach. Put differently, if the developers of\u00a0http:\/\/www.moves-app.com themselves would have implemented the GameBus&lt;&gt;Moves integration then the GameBus \/connect URL could have been as simple as:<\/p>\n<pre><code>https:\/\/api.moves-app.com\/api\/connectToGameBus\/{userId}\/{gamebusToken}<\/code><\/pre>\n<p><strong><a name=\"decrypting\"><\/a>Decrypting GameBus tokens<\/strong><\/p>\n<p>GameBus tokens are always encrypted,\u00a0both when storing them on the end user&#8217;s filesystem (cf,. section\u00a01) as well as when sending them to your\u00a0app&#8217;s server (cf., section 2). Furthermore,\u00a0in approach 2, the token value will be Base64-encoded (since the encryption may produce URL unsafe characters).<\/p>\n<p>Therefore, in order to get access to GameBus tokens, apps\/websites will always have to decode using their app-specific app key. \u00a0More specifically, tokens are\u00a0encrypted by 128-bit AES\/CFB8\/NoPadding (see\u00a0<a href=\"http:\/\/aesencryption.net]\/\">http:\/\/aesencryption.net]<\/a>\u00a0to test.) \u00a0Furthermore, when following the approach from section 2, implementations of the \/connect, \/disconnect and \/status endpoints will first have to run a Base64 decoding before even trying to run the AES decoding (see\u00a0<a href=\"https:\/\/www.base64decode.org\/\">https:\/\/www.base64decode.org<\/a>\u00a0to test).<\/p>\n","protected":false},"excerpt":{"rendered":"<p>This is a page for developers who wish to leverage the GameBus Open API. The page focuses on security aspects. Please contact us if you want to learn more about API functionality beyond what is documented here. The\u00a0API should be accessed via\u00a0 HTTPS REST calls\u00a0with JSON payload and an OAuth 2 token in the Authorization &hellip; <\/p>\n<p class=\"link-more\"><a href=\"https:\/\/blog.gamebus.eu\/index.php\/gamebus-oauth-token-manual\/\" class=\"more-link\">Continue reading<span class=\"screen-reader-text\"> &#8220;GameBus OAuth Token Manual&#8221;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"categories":[],"tags":[],"class_list":["post-286","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/blog.gamebus.eu\/index.php\/wp-json\/wp\/v2\/pages\/286","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.gamebus.eu\/index.php\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/blog.gamebus.eu\/index.php\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/blog.gamebus.eu\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.gamebus.eu\/index.php\/wp-json\/wp\/v2\/comments?post=286"}],"version-history":[{"count":0,"href":"https:\/\/blog.gamebus.eu\/index.php\/wp-json\/wp\/v2\/pages\/286\/revisions"}],"wp:attachment":[{"href":"https:\/\/blog.gamebus.eu\/index.php\/wp-json\/wp\/v2\/media?parent=286"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.gamebus.eu\/index.php\/wp-json\/wp\/v2\/categories?post=286"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.gamebus.eu\/index.php\/wp-json\/wp\/v2\/tags?post=286"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}