OAuth Authentication

The OAuth Authorization Flow

In order to use Mobage RESTful API, your app server must first authenticate itself and the user with the Mobage platform. Mobage uses the OAuth sequence to grant RESTful API access to app server. Below diagram summarizes the full OAuth authorization sequence.

Here are the actors that participate in the flow:

Game: Your game which is usually an app running on an iOS or Android device.
Game Server: Your game server which the game connects to. It can be as simple as an application server that stores and returns game data but it must be able to run code and make connection to the Mobage Platform.
Mobage Platform: The Mobage Platform that provides the RESTful API.
Mobage SDK: The Mobage SDK that is integrated in the Game.

1-4. Request and returning of temporary credentials:
Any time after user logged in to the game, the game can initialize an authorizaton sequence by first requesting a temporary token from the game server. The game server then send a signed request for temporary token to Mobage platform. Mobage platform returns a pair of temporary token and temporary token secret to the game server. Game server should return ONLY the token to the game client.

For security reason, return ONLY the temporary token and NEVER return temporary token secret.

5-8. Authorizing temporary token:
Next, the temporary token needs to be authorized and associated with a Mobage user. After user login to the game, call the below designated API in the Mobage SDK to authorize the token. The SDK talks to the Mobage platform in the background and returns a verifier string to the game.

SDK	OS	API to authorize temporary token
Mobage Native SDK	Android	com.mobage.android.social.common.Auth.authorizeToken
	iOS	[MBGSocialAuth authorizeToken:onSuccess:onError:]
Mobage Unity SDK	Common	MobageAuth::authorizeToken
Mobage ngCore SDK	Common	Social.Common.Auth.authorizeToken

9-12. Request access token credentials and returning session ID:
The game should then send the acquired verifier string to the game server, which will make another signed request to the Mobage Platform. This time, the Mobage platform will return an user-associated access token, a token secret and an oauth2 token used for Bank API calls. For more information about signing requests with these tokens, see Signing Request below. However, the game server must NOT pass these credentials to the game client. The game server should issue a session ID and bind this set of credential to it, and return only the session ID to the game client.

For security reason, NEVER return access token, access token secret or oauth2 token to the Game client.
Instead, generate a session ID string and pass that to the client.

Also, DO NOT send currently logged in user ID from the client. Use People API to identify the currently logged in user on server side. Refer to the tutorial here.

Please make sure you are managing the Token Credential (oauth_token, oauth2_token) per Session ID and not per User ID.
Following is a case study of inappropriate usage.

Condition
- Token Credential is stored per User ID in the database.
- The Token Credential in database is overwritten by the initialization of Android or iOS when proceeding 3-Legged OAuth.
State of Action
- User suspends the game in iOS and the starts the game in Android, and then goes back to iOS.
Consequence
- A miss match of Token Credential will occur and if the user purchases an Item from iOS, the Android game currency will be used instead of iOS game currency.

Notice that the Token Credential is tied per device in Mobage Platform. Therefor you can't share the same Token Credential between devices.
Incase you are managing the Token Credential per session ID then you don't need worry of such issue.

The expiry of Token Credentials

Token Credential expires in 24 hours.
However, if suspicious user activity is detected, platform will expire token credentials any time.
Mobage Platform will return status code 401 if the Token Credential has been expired. In this case please retrieve the Token credential again by running 3-Legged authentication process.

13-16. Making requests with session ID:
Game client can then make requests to the game server using the assigned session ID. If necessary, game server uses the associated token credentials to call Mobage RESTful API. Of course all requests must be signed, see Signing Request below. The Mobage platform then returns the result to the game server. The game server can process the results and pass it back to the game client accordingly.

Signing Request

The Mobage platform needs to know that it is getting requests from a legitimate game server. Therefore, game server must sign all requests with either of the following methods, depending on the API that it is calling.

Client Only Signing (sometimes called 2-legged Authorization or Trusted model)
3-legged Authorization Signing (sometimes called Proxy model)
OAuth2 Authorization

For more information about signing request, see Signing Request.