Federated Identity User Authentication

You may, if you wish, have your application's users login to your app using a third party user authentication, such as Twitter or Facebook.

We support third party authentication using OpenID2, OAuth1 and OAuth2, for identity provides including Facebook, Twitter, Google, LinkedIn and Yahoo.

This page describe Federated Authentication through the Rdb2.js module. If you are using the older Rdb.js module, see its own docs.

Federated Identity at RdbHost

Adding Third Party Login to your RdbHost-hosted web application involves five easy steps.

  1. Enable Federated Login on your profile page.
  2. Obtain client key and client secret for each identity service.
  3. Add login buttons to the web application for each service, with click-handlers.
  4. Call the Rdbhost.confirm_fedauth_login() function from your web application, as early as possible after loading the app.

Now we'll go through those one at a time:

1. Enable Federated Login on the profile page.

Like it sounds, just click the button. Disabling and re-enabling from the profile has the effect of resetting the auth.fedauth_providers table to original condition.

2. Obtain client key and client secret from the service.

These are obtained from each service's web site. They are sometimes refered to as 'consumer key' or 'consumer secret', or 'client id'. The service will provide one each per registered application.

3. Add login buttons to your web application.

Provide a click handler on each button, that calls Rdbhost.fedauth_login().

<button id="twitter-login">Twitter Login
$('#twitter-login').click(function(e) {
    Rdbhost.fedauth_login('Twitter', window.origin);
    // this function never returns.
})
4. Add the library function call Rdbhost.confirm_fedauth_login() to your app.

Include the rdbhost library in your app header, and call the function as soon as possible after loading. When the browser returns to your app at the end of the login sequence, this function will run and find the identifier and key passed to your app by RdbHost. It will call a callback and pass it those values. Have your login callback store those values in the app somewhere, perhaps in sessionStorage.

var liProm = Rdbhost.confirm_fedauth_login();

liProm.then(function(userData) {
    if (userData.status === 'loggedin') {
        app.user = userData.identifer;
        app.key = userData.key;
    }
    else {
        throw new Error('login status: '+userData.status);
    }

The identifier is the identifying string provided by the third party identity service, prepended by the service name. The key is a random string that serves to prove to the server that the app has that user logged in. When querying the fedauth_accounts table, you generally want to match on both identifier and key.

Fedauth Providers in the Database

The Fedauth Providers are tracked in a table called 'lookup.fedoauth_providers', and the form of the table is similar to below. Services in the table without keys and secrets will be considered disabled. If you are adding support for a third party identity service not covered here, you can add records to this table, and make the Rdbhost.fedauth_login() first parameter value match the 'provider' value.

You may never need to edit this directly, as the Rdb2.js library populates it for you, for each Service you enable in your app, upon first test.

provider version client_key client_secret redirect mode .. more columns deleted ..
Google2[client key][client secret]/auth/oauth2/cbgoogle...
Facebook2[client key][client secret]/auth/oauth2/cbfacebook...
LinkedIn2[client key][client secret]/auth/oauth2/cblinkedin...
Twitter1[client key][client secret]/auth/oauth1/cbtwitter....

User Accounts in the Database

When a user logs in for the first time, an entry is created in the auth.fedauth_accounts table, with fields for the identifier and for a random key, as well as a unique index value and whatever profile information was available from the identity provider. This random key is unique to this account in your database, and is provided to your app at the end of the login process.

Also, a view named auth.user_accounts is created for you, and the identifier column in this view is the samse issuer || identifier form as the key passed to your JavaScript login function. Your queries, generally, will reference this view rather than the source auth.fedauth_accounts table.

All of these tables and views are created for in Step 1, and can be viewed and (if necessary) edited in RdbAdmin.

A query using user id might resemble:

-- get messages for current user
SELECT message_body, from_usr, date_sent
 FROM messages m JOIN auth.user_accounts u ON m.to_usr = u.idx
WHERE u.key = %(key)s AND u.identifier = %(identifier)s
LIMIT 100;

Examples