OAuth 2.0¶
Some “external” credentials (facebook
, google
, vk
etc)
follow OAuth 2.0 protocol in order of the authorization to proceed. This
authorization can be achieved with a simple flow:
- User has the corresponding social network’s “login page” shown, asking user consent for the authorization.
- After approval, the browser gets redirected back to the special
redirect_uri
location, with the specialcode
argument. - This redirect is caught and the code is extracted as an argument for the actual authorization in the login service.
In practice, each social service has different location of the “login page”, so login service encapsulates it with a convenient call. Open this URL in the application’s in-app browser:
http(s)://<login-service-location>/auth/<credential>?redirect_uri=<redirect_uri>&gamespace=<gamespace>
Argument | Description |
---|---|
credential |
A credential type of the social service (for example, google ) |
redirect_uri |
Application’s main domain page, for example, http://example.com/ . It’s important to have / at the end. |
gamespace |
A gamespace name (alias) to authenticate in. See Authenticate call for more details. |
Please note that redirect_uri
value has to be added into the allowed
“REDIRECT URIs” list in each social service’s settings page of your
application.
- This call will automatically redirect to the corresponding social service authorization form on which the user is asked for login and password.
- After successful authorization, the browser is redirected to the
redirect_uri
page, according to the OAuth 2.0 standard. - This redirect will have a query argument
code
, and the application has to catch the redirect, extract thecode
, closing the browser. - Then
code
andredirect_uri
has to be used during the last-step authentication call to the login service.
Admin Tool¶
You can log in into the admin-tool using these credentials, but the
http(s)://<login-service-location>/auth/oauth2callback
has to be
added as a redirect_uri
(see above).
Authenticate¶
Authenticates the user in the Anthill Platform
← Request¶
POST /auth
Argument | Description |
---|---|
credential |
Credential type |
scopes |
Comma-separates list of access scopes to request |
gamespace |
A gamespace name (alias) to authenticate in |
Optional arguments:
Argument | Description | Default value |
---|---|---|
should_have |
Comma-separated list of scopes the user should definitely acquire, or 403 Forbidden will be returned. Useful in cases when player is OK with not having some of scopes. |
* , everything requested should be retrurned. |
info |
A JSON object of the additional info would be attached to account (for example, device ID) | {} |
attach_to |
Access token of the account to proceed the attach procedure. See Attach Credential for more information. | |
unique |
Should the access token be unique (meaning no two tokens of the same name could exists). Setting to false would require a special access scope auth_non_unique . |
true |
as |
A name for the token. Only one token of the same name could exist at the same time (if unique is true ) |
def |
full |
Return more information about the token returned (if form of a JSON object instead of just token) | false |
→ Response¶
In case of success, an access token is returned:
"token string"
Warning: token string format could be changed at any moment, so the client application should not rely on this response, and should threat it like a simple string.
If the argument full
is set to true
, a JSON object is returned
instead:
{
"token": "<token string>",
"account": "<account ID>",
"credential": "<credential>",
"scopes": [<array of allowed scopes>]
}
Response | Description |
---|---|
200 OK |
Everything went OK, service location follows. |
404 Bad Arguments |
Some arguments are missing or wrong. |
403 Forbidden |
Failed to acquire a token, either username/password is wrong, or access is denied. |
409 Conflict |
A merge conflict is happened, a Conflict Resolve is required |
Attach Credential¶
If you login with a credential for the first time, a fresh new account
is created. However, sometimes it is not the case. For example, a player
have already authenticated into credential anonymous:XX-XX-XX
, so
the account A
is created.
anonymous:XX-XX-XX -> A
But if player also wants to login using facebook
, he will end up
with a different account.
anonymous:XX-XX-XX -> A
facebook:12345678 -> B
To avoid this, credential can be attached to a same account instead of creating new one.
anonymous:XX-XX-XX -> A
facebook:12345678 -> A
Simplest way to do so is to pass attach_to
argument while doing
Authenticate call:
- Authenticate, using first credential (say
anonymous:XX-XX-XX
), accountA
will be used (or created); - Authenticate, using second credential (say
facebook:12345678
). While doing that, pass the access token from a previous authentication, asattach_to
argument; - The system will try to attach credential
facebook:12345678
to accountA
as long as credential is not used elsewhere;
Account Conflict¶
In case credential facebook:12345678
has already attached to a
different account, or already has multiple accounts attached, a conflict
will occur:
{
"result_id": "<Conflict Reason>",
// other useful information about the conlict
}
In response to conflict, server may return resolve_token
to Resolve
Conflict. Possible conflict reasons:
merge_required
Credential, you are trying to attach is already attached to a different account. Possible account solutions along with their profiles (if exist) are described in field
accounts
.{ "result_id": "merge_required", "resolve_token": "<a resolve token>", "accounts": { "local": { "account": <account N>, "credential": <credentian N>, "profile": { a possible profile JSON object } }, "remote": { "account": <account N>, "credential": <credentian N>, "profile": { a possible profile JSON object } } } }
Profile fields may be used to describe to the Player information about the accounts (level reached, currency have, avatar etc). On of the solutions should be used as
resolve_with
when dealing with Resolve Conflict.multiple_accounts_attached
Credential, you are trying to attach is already attached to a multiple accounts. One of them is required to be detached first. Please note that this may happen during normal authentication.
{ "result_id": "multiple_accounts_attached", "resolve_token": "<a resolve token>", "accounts": [ { "account": <account number>, "profile": { a possible profile JSON object } }, { "account": <account number>, "profile": { a possible profile JSON object } }, ... ] }
On of the account numbers should be used as
resolve_with
when dealing with Resolve Conflict.
Resolve Conflict¶
I case of conflict, a Resolve Conflict method may be used to solve the conflict situation.
← Request¶
POST /resolve
Argument | Description |
---|---|
access_token |
A Resolve Token, retrieved when the conflict occurred. |
resolve_method |
A way how to resolve this conflict. Should be exactly the Conflict Reason server gave.
For example, merge_required or multiple_accounts_attached . |
scopes |
Access scopes to be acquired like in Authenticate procedure. |
resolve_with |
A way to resolve this conflict. Varies for different Conflict Reasons |
Optional arguments:
Argument | Description |
---|---|
attach_to |
Access Token to the account player originally was going to attach to. Only applicable if conflict happened during Attach Credential procedure. |
full |
Return more information about the token returned (if form of a JSON object instead of just token) |
→ Response¶
In case of success, an access token is returned:
"token string"
Warning: token string format could be changed at any moment, so the client application should not rely on this response, and should threat it like a simple string.
If the argument full
is set to true
, a JSON object is returned
instead:
{
"token": "<token string>",
"account": "<account ID>",
"credential": "<credential>",
"scopes": [<array of allowed scopes>]
}
Validate Access Token¶
Checks if the given access token is valid
→ Response¶
This request has no response body.
Response | Description |
---|---|
200 OK |
Access token is valid. |
404 Bad Arguments |
Some arguments are missing or wrong. |
403 Forbidden |
Token is not valid. |
Extend Access Token¶
Allows to to give additional Access Scopes to the existing access token (account of which did not have such scopes originally), using other, more powerful account.
- Say there’s account
A
with scopesS1
andS2
allowed. - There’s account
B
with scopeS10
thatA
has no access to. A
authenticates, requesting scopeS1
.B
authenticates, requesting scopeS10
.- Access token of
B
extends access tokenA
using scope he hadS10
. - A working access token for
A
with scopesS1
andS10
is now available.
This flow is primarily used for trusted game servers to do strict actions server side. For example,
- User Authenticates asking for
profile
scope. This scope allows only to read user profile, but not to write; - The Game Server Authenticates itself using
dev
credential withprofile_write
scope; - User give the access token to the server is a secure way;
- The Game Server extends this token to the more powerful one, so server can write the profile in behalf of the user;
- At the same time, user still have perfectly working access token, without such possibility;
← Request¶
POST /extend
Argument | Description |
---|---|
access_token |
Access token to extend (the one to be improved) |
extend |
Access token to extend with (the one that have required scopes) |
scopes |
Scopes to improve access_token with. Default * – to use all scopes the scope extend have. Otherwise, a comma-separate list of Access Scopes. |
→ Response¶
A JSON object with a new token and it’s expiration date.
{
"token": "<improved access token>",
"scopes": [<scopes of improved token>],
"account": "<account of the original access_token>",
"expires_in": <time, in seconds, for the new token to expire>
}
Please note that the original access token is still valid. Also, tokens have to be in a same gamespace.