Authentication Hub

Introduction

The SocialOS Authentication Hub module is an optional application that can be added to your SocialOS installation.

Configuration:

You will need the following to be configured before you can use the authentication hub:

Your client_id
Your SocialOS instance name
Your authentication hub base_url

Additionally, if you are intending to use foreign authentication providers, you will need API keys and client secrets for each

Error handling:

If there is an error in the linking or login process, and a redirect_uri has been supplied by the requesting service, the user will be redirected to that location with a “error” and a “error_message” parameter as GET variables set. The destination page should interpret these parameters and take appropriate action.

A table of Authentication Hub errors can be found at the end of this document.

Example:

http://<redirect_uri>?state=None&error_description=username+and+password+do+not+match&error=invalid_grant

If there is no redirect_uri supplied, then the response is a json encoded payload of the same information as below:
{
state: null,
error_description: "username and password do not match",
error: "invalid_grant"
}

User Sign Up

To sign up, Users will be required to provide:

Full Name
Email Address
Password
check the box to accept the terms and conditions (flag set on SocialOS account)
check the box to keep me updated via email (flag set on SocialOS account)

On successful sign up, SocialOS will respond with the unique MemberID, a unique email verification link (which the client is responsible for emailing to the new Member for confirmation). The new Member will click on the link to verify their email address. Once the email is verified, SocialOS will set a flag denoting same in the user’s account.

Action:

Below are examples of the required API calls to allow the client web site to CREATE accounts in SocialOS (with the relevant metadata and tags etc). SocialOS will assign a unique ID to each member (MemberID).

EXAMPLE PHP CODE

$register_data = {
    'emailupdate' => 'false',
    'password' => 'test123',
    'name' => 'Han Tester',
    'email' => '[email protected]'
}

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://$base_url/register/$instance");
curl_setopt($ch, CURLOPT_POST, true)
curl_setopt($ch, CURLOPT_POSTFIELDS, $register_data)
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true)

$res = curl_exec($ch)

EXAMPLE RESPONSE FORMAT

{"address": "stester.1456726433@dev", "validation_code": "NMm37Ma8unZyLPKVEuQVIB", "id": "56d3e1a1e81a00532d3001ef", "name": "stester.1456726433"}

NOTES:
email validation link is to be built from the validation code above:

http://<base_url>/validate_email/<instance>?client_id=<client_id>&code=<code as supplied>&redirect_uri=<some url>

User Login

Action:

Below are examples of the required API calls to allow the client web site to LOGIN accounts, and receive a token from SocialOS which is used to authenticate API calls to SocialOS for that user (e.g. when making a comment).

$login_data = {
    'password' => $password,
    'email' =>  $email,
    'client_id' => $client_id,
    'redirect_uri' => $some_url # optional
}


$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://$base_url/authenticate/$instance>");
curl_setopt($ch, CURLOPT_POST, true)
curl_setopt($ch, CURLOPT_POSTFIELDS, $login_data)
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true)

$res = curl_exec($ch)

EXAMPLE RESPONSE FORMAT

{"code": "dijn9sRZxOEI6xRUwgbxU9"}

Note that if redirect_uri is set, a 301 redirect will be performed instead of a json response being returned, with the code attached as a GET parameter to the end of the redirect url.

Codes can be exchanged for SocialOS keys as follows:

$login_data = {
    'client_id' => $client_id,
    'code' => $code
}

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://base_url/token/$instance");
curl_setopt($ch, CURLOPT_POST, true)
curl_setopt($ch, CURLOPT_POSTFIELDS, $login_data)
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true)

$res = curl_exec($ch)

EXAMPLE token response format:

{"access_token": "+055264382540:wJLTUxbiuuwW", "token_type": "key"}

User Logout

Persistant session logut is currently implemented by client javascript making a CORS request to http://<base_url>/logout.

It is possible to check the user’s current login status by making a javascript CORS request to http://<base_url>/check/?client_id=<client_id> . If the user is currently logged in a code will be returned in the following format (a non-loggedin user will return an empty code)
{code: "ADby9Kx0dhTTSGSJaK9azT"}

The code may be exchanged for a SocialOS token as above.

LINKING A SOCIAL ACCOUNT:

Requirements enforced by the login hub:

User must be logged in
‘Link’ parameter must be set (for a link request, required not to be set for login)
Foreign account must not be linked to another user
User must not already have a foreign account from the source requested

If any of these are not true, the Authentication Hub will respond with an error.

Redirect the user to:

https://<base_url>/authorize/dev/twitter?client_id=<client_id>&redirect_uri=<redirect_uri>&link=1

This in turn redirect the user to the foreign service provider, authenticate them, and return them to the redirect_uri with a code parameter attached:

Example:

https://<redirect_uri>?code=ryAlS6HYN8xXPUBZVFZopM

This code can be exchanged for a SocialOS token by using the previously documented ‘token’ endpoint.

Logging In With A Social Account

Requirements:

User must not currently be logged in
‘Link’ parameter must be NOT be set
Foreign account must previously have been linked to the user

Redirect the user to:

https://<base_url>/authorize/<instance>/twitter?client_id=<client_id>&redirect_uri=<redirect_uri>

This in turn redirect the user to the foreign service provider, authenticate them, and return them to the redirect_uri with a code parameter attached:

Example:

http://<redirect_uri>?code=ryAlS6HYN8xXPUBZVFZopM

This code can be exchanged for a SocialOS token by using the previously documented ‘token’ endpoint.

Reference:

Example user record with linked accounts: (obtained by calling SocialOS API user endpoint).

Linked account information is in the ‘identities’ section.

{u'_cls': u'User',
 u'address': u'andrewhorn.1457409952@dev',
 u'analytics': {u'_cls': u'Analytics',
                u'count': 0,
                u'influence': 0.0,
                u'minus': 0.0,
                u'outreach': 0.0,
                u'plus': 0.0,
                u'score': 0.0,
                u'sentiment': 0.0,
                u'spam': 0.0},
 u'app': None,
 u'app_private': False,
 u'bio': {u'_cls': u'Bio',
          u'age': None,
          u'avatar': None,
          u'description': u'',
          u'gender': None,
          u'language': None,
          u'name': u'Andrew Horn',
          u'photo': None,
          u'timezone': None,
          u'tz': 0,
          u'url': None},
 u'counts': {},
 u'created': 1457409952,
 u'data': {},
 u'domain': u'dev',
 u'email': u'[email protected]',
 u'flags': [],
 u'folders': [],
 u'geo': {u'_cls': u'Geo',
          u'cc': None,
          u'city': None,
          u'country': None,
          u'latitude': None,
          u'location': None,
          u'longitude': None,
          u'state': None},
 u'global_id': u'56de4fa0e81a00532bde9425@@dev',
 u'id': u'56de4fa0e81a00532bde9425',
 u'identities': [{u'_cls': u'User',
                  u'address': u'[email protected]',
                  u'analytics': {u'_cls': u'Analytics',
                                 u'count': 0,
                                 u'influence': 0.0,
                                 u'minus': 0.0,
                                 u'outreach': 0.0,
                                 u'plus': 0.0,
                                 u'score': 0.0,
                                 u'sentiment': 0.0,
                                 u'spam': 0.0},
                  u'app': None,
                  u'app_private': False,
                  u'bio': {u'_cls': u'Bio',
                           u'age': None,
                           u'avatar': u'http://pbs.twimg.com/profile_images/506301305262854144/z9FJFQxR_normal.jpeg',
                           u'description': u'Scifi geek | Cat lover | Gamer | Coffee drinker | Web developer | Father | Biped | All-round @Artee',
                           u'displayName': u'Artee',
                           u'gender': u'u',
                           u'language': None,
                           u'name': u"Andrew'; --",
                           u'photo': None,
                           u'timezone': None,
                           u'tz': 0,
                           u'url': None},
                  u'counts': {},
                  u'created': 1457410244,
                  u'data': {},
                  u'direct_link': True,
                  u'domain': u'twitter.com',
                  u'email': None,
                  u'flags': [],
                  u'folders': [],
                  u'geo': {u'_cls': u'Geo',
                           u'cc': None,
                           u'city': None,
                           u'country': None,
                           u'latitude': None,
                           u'location': None,
                           u'longitude': None,
                           u'state': None},
                  u'global_id': u'6825762@@twitter.com',
                  u'id': u'56de50c4e81a0053272a7047',
                  u'limits': {},
                  u'modified': 1457413997,
                  u'name': u'6825762',
                  u'networks': [],
                  u'permissions': {},
                  u'pools': [],
                  u'private': None,
                  u'refs': {},
                  u'role': None,
                  u'status': u'active',
                  u'tags': [],
                  u'type': u'user',
                  u'updated': 1457413997}],
 u'limits': {},
 u'modified': None,
 u'name': u'andrewhorn.1457409952',
 u'networks': [],
 u'permissions': {},
 u'pools': [],
 u'private': None,
 u'refs': {},
 u'role': None,
 u'status': u'active',
 u'tags': [],
 u'type': u'user',
 u'updated': 1457409952}

Authentication Hub Errors

In addition to the normal OAuth 2.0 errors, the following errors may also be returned from the authentication hub. In each case, both the Error and the Error Description are returned:

Error	Error Description	Trigger notes
server_error	Invalid client_id	Client_id supplied in the request does not exist in the selected SocialOS instance
invalid_request	Must be logged in to add account	Request with link parameter set while user not logged in
server_error	Could not find user	SocialOS database inconsistency
invalid_request	User already has account	Link attempt made (link parameter set) while user already has a linked account for the defined source
invalid_request	account already linked to another user	Link attempt made while the authenticated foreign account has been linked to another user
invalid_request	account does not belong to existing user	Login attempt made and the authenticated foreign account is not linked to an existing user
invalid_grant	Username and password do not match	Username/password login attempt failure