Mapping Identities

For purposes of this discussion, the site that provides the web front-end to the user will be known as the Host Network (since it hosts the user's profile). The site that provides the social application will be known as the Provider Network (since it provides the application to the other network). The Social Container in the Provider Network performs the identity mapping required to deploy the application to multiple networks. When the application is deployed to the Host Network, the callback URL does not go directly to the application. Instead, the callback URL points to a special URL in the Social Container that manages identity, authentication, and other configuration for external sites that call into the Ringside network.

When a Provider Network user access the application, they access it in the usual way. They log in to the Web Container, and the Social Container performs the request to the application over the HTTP protocol to the callback URL. The application then uses APIs to talk to the API Container, passing in the user ID as part of the request. Whether the Provider Network is Facebook or a Ringside network, this basic flow is always the same.

When a Host Network is introduced, the Social Container of the Provider Network is used to map the identities of users coming from that outside network to the identity of a user known by the Provider Network. When the application makes calls to APIs, the API Container of the Host Network is used. The application doesn't change anything about the way these APIs are called. There are changes required to the application, though.

When storing and retrieving information from the application's database, a simple API must be called to convert the Host Network's user ID (which is the one passed to the application in the POST or GET data) into the Provider Network's user ID. By doing this simple mapping, the application can support users across multiple networks and give them the option to maintain unified application data across those networks.

This mapping procedure must be used both when writing data that was supplied by the user on the Host Network and when reading data that will be supplied to the Host Network. This translation is done using the same users_map() function, but with slightly different parameters. When writing the data, the one-parameter users_map(uid) function will transform the user ID from the Host Network to the Provider Network (this is the network making the call, since the application is deployed there). When reading, the Provider Network user ID must be transformed back to the Host Network user ID. By doing this, the URLs, forms, and subsequent API calls will all operate on the proper ID. To do this transformation, the two-parameter users_map(uid, network) function must be used. This form of the function will transform the Provider Network user ID for use on the specified network.

User Identity Mapping

When a user uses an application that supports identity mapping, they first must choose an identity to associate with their application data. To do this, the Ringside platform introduces an identity mapping page that will allow the user to map their identity from a different social network to their current identity for purposes of application data storage. The user's experience is described in this section. For the example, we will use the user jane@goringside.net. Jane starts out having never used the application before. When she first access the application after logging into the Ringside web interface, she is presented with the mapping options. Because she has never used the application before, she will select "create new profile".

She will then see the application page as usual. After entering some data, it will be stored by the application with a Ringside ID that will be available to map to another network.

Now, Jane logs into a different Ringside instance (rsremote) and accesses the same application. She is again presented with the user mapping page, because she has never access the application from this Jane at this network. However, since she has used the application before, she selects "Ringside" to perform the mapping. Note that the list of networks is different from the last time she saw this page, since she is accessing the application from a different network.

 After selecting a network, Jane must log in to that network to confirm her identity. Note that she is logging into the "rslocal" Ringside network (not "rsremote", where she started).

After authenticating to confirm that she does, indeed, own the identity she is mapping to, Jane is immediately transferred to the application's canvas page. Here we can see that the data entered in the other network is seamlessly available to her on this second network. Notice how on this network, Jane has a different profile (with a different profile image), but Jane's running data is shared across her multiple identities.

Configuring Identity Mapping

To configure identity mapping for your Ringside platform, first you must have the following:

1. A Ringside platform that directly hosts the application (i.e. the callback_url is configured to the application's URL) and
2. A third-party network (Ringside or Facebook) that hosts the application via the social callback URL:

   http://{host}[:{port}]/social/trust.php/{network}/{canvas_url}

   (Note: this URL will not have the "/social" part in an installer download.)

The following configuration settings MUST be the same across ALL participating networks:

• The canvas URL (the end of the URL when the user accesses the application via the web interface)
• The API key
• The secret key

This may require changes to the database after registering the application with Ringside.

Configuring the Provider Network 

While you're in there, the rs_trust_authorities table must also be configured with each network (including the Provider Network). Here is a description of each field in the table:

trust_key: For Facebook, the literal string "facebook". For a Ringside server, the value of the Social API Key (available in LocalSettings.php)
trust_name: The name of the remote trusted network. This will appear during mapping of identities, so it should be descriptive. By default, the local Ringside server will just be called "Ringside".
trust_auth_url: The URL pointing to the REST server (typically http://host:port/api/restserver.php or http://host:port/restserver.php; http://api.facebook.com/restserver.php for Facebook)
trust_login_url: The URL used to login to the network (typically http://host:port/login.php; http://www.facebook.com/login.php for Facebook)
trust_canvas_url: The URL prefix used to construct the canvas URL for the application by appending the configured canvas_url (typically http://host:port/web/canvas.php or http://host:port/canvas.php; http://apps.facebook.com for Facebook)
trust_web_url: The URL prefix used to access a web page on the network (typically http://host:port/web or http://host:port; http://www.facebook.com for Facebook)
trust_social_url: The URL prefix used to access the social layer (typically http://host:port/social or http://host:port; not applicable for Facebook)
trust_auth_class: (not used) The class used to implement trust for the external network

Configuring the Application (Ringside Developer Application)

In order to keep your application's key pair (API key and secret) secure, Ringside enables registration of API keys and secrets generated by third-party networks. To access the additional key registration fields, select the "Manage Keys" tab of the developer application, as illustrated below.

On this tab, you will see places to enter additional key pairs for each network configured on your Ringside instance. In the default configuration, the Ringside instance is configured with Facebook as the only third-party network.

Because all third-party networks have to generate keys for your application, you will need to go to that network's developer application to retrieve your keys. On Facebook, it looks like this:

Just copy the API key and secret (one at a time) into the Ringside developer application, as shown below, and click "Save Keys":

Now, the third-party network should be able to show your application using a key pair assigned specifically to that network. The identity of the network is encoded into the callback URL.

Configuring the Application (Application Configuration)

Because applications run on their own server beyond the control of the Ringside platform, it is necessary to configure the application's client based on the network that is invoking the application (the Host or Provider network). In order to accomplish this, use a simple block of code to make the URLs in the application match the URLs configured in the database for that network. There must be a special URL configured to perform identity mapping that uses an infinite session key for the Provider network. For example:

To create an infinite session, you can add the script here to your application: Infinite Session Code

See the code here: Application Configuration Code for Mapping