Single Sign-On Implementation \ Setup

You will first discover how to setup your database in order to store the data required by the Single Sign-On service. Then you will have to slightly update your existing system in order to enable the exchange of user data between your websites.

If the setup of your website is different, you should still be able to follow this guide, some sections may however not be relevant for you.

1. Add the required tables to your database.

You first of all have to add two new tables to your database. For MySQL you can use tables like in our examples below. You may have to tweak the structure slightly if you represent your internal user identifiers differently.

OneAll User

This table links the user_token generated by OneAll to the user's identifier in your own database. Both keys are unique as each user in your own database should only be linked to a single user record in your OneAll cloud storage and vice-versa.

-- Table Structure
CREATE TABLE `oneall_user` (
  `user_id` INT(10) UNSIGNED NOT NULL ,
  `user_token` CHAR(36) NOT NULL 		 
) ENGINE = InnoDB;

-- Table Indexes
ALTER TABLE `oneall_user`
  ADD PRIMARY KEY (`user_id`),
  ADD UNIQUE KEY `user_link` (`user_id`,`user_token`),
  ADD UNIQUE KEY `user_token` (`user_token`);

The user_id is the id that uniquely identifies user entries in your users table. Generally speaking the identifier corresponds to the primary key of that table.

The user_token uniquely identifies user records kept in your OneAll cloud storage. User records are added either automatically - whenever a new user connects using his social network acccount - or you can add new users the fly by using our API.

OneAll Identity

Identities represent collections of user information and there is a one-to-many relationship between users and identitites. A single user might for example have an identity representing the user information that you have explicitly pushed to the cloud storage and another identity that was automatically added when that user linked his social network account.

-- Table Structure
CREATE TABLE `oneall_identity` (
  `user_id` INT(10) UNSIGNED NOT NULL ,
  `identity_token` CHAR(36) NOT NULL          
) ENGINE = InnoDB;

-- Table Indexes
ALTER TABLE `oneall_identity`
  ADD UNIQUE KEY `identity_link` (`user_id`,`identity_token`),
  ADD UNIQUE KEY `identity_token` (`identity_token`);

The user_id is the id that uniquely identifies user entries in your users table.

The identity_token uniquely identifies a collection of user information kept in the OneAll cloud storage.

2. Implement the functions to work with the users table.

To access the oneall_user table you will need a couple of basic function like in the examples below. Please note that these are only examples that need to be implemented depending upon your own system and database.

user_token user_id

This function returns your proprietary user_id for a user_token received by OneAll. The goal is to check if the received token matches a user record in your own database.

     function get_user_id_for_user_token (user_token){
       SELECT `user_id` FROM `oneall_user` WHERE `user_token` = <user_token>
       return <user_id>
     }

user_id user_token

This function returns the user_token for a proprietary user_id. The goal is to check if the given user has already been linked to a record in your OneAll cloud storage.

		function get_user_token_for_user_id (user_id){
			SELECT `user_token` FROM `oneall_user` WHERE `user_id` = <user_id>
			return <user_token>
		}

user_token user_id

This function links a OneAll user_token to a proprietary user_id. The goal is to keep the oneall_user table in sync.

        function link_user_token_to_user_id (user_token, user_id){
            INSERT INTO `oneall_user` SET `user_token` = <user_token>, `user_id` = <user_id>
        }

3. Implement the functions to work with the identitites table.

To access the oneall_identity table you will need a similar subset of functions. Please keep in mind that the functions slightly differ from the previous example as there is a one-to-many relationship between users and identitites.

identity_token user_id

Returns the proprietary user_id for an identity_token received by OneAll. The goal is to check if the received token matches a user record in your own database.

        function get_user_id_for_user_token (identity_token){
           SELECT `user_id` FROM `oneall_identity` WHERE `identity_token` = <identity_token>
           return <user_id>
        }

identity_token user_id

This function links the OneAll identity_token to a proprietary user_id. The goal is to keep the oneall_identity table in sync.

        function link_identity_token_to_user_id (identity_token, user_id){
           INSERT INTO `oneall_identity` SET `identity_token` = <identity_token>, `user_id` = <user_id>
        }
    

4. Create a basic callback script.

If the user browsing your website is not logged in, the Single Sign-On service will check if that user has an an open SSO session. If there is an open session, the user will be redirected to the callback script.

During that redirection the OneAll API includes a connection_token as POST data. That token can then be used to retrieve the user's profile data and to register and/or login the user. Now create a file with the code below on your server:

		<?php

		// Check if we have received a connection_token
		if ( ! empty ($_POST['connection_token']))
		{
		  echo "Connection token received: ".$_POST['connection_token'];
		}
		else
		{
		  echo "No connection token received";
		}

Once you have created the file, you should be able to open it in your browser and you should see the message No connection token received. Please keep the complete URL that points to this file handy as it will be used during the next steps of the guide. In the setup guide the link to this file is called callback_uri.

Your database should now be ready and you should have setup a basic version of the callback script.

Next Step - Backend Integration

User Contributed Notes