Legacy Sign-in Widget

This widget has been deprecated.

When creating new sign-in widgets, use the Social Sign-in Widget.

Janrain’s new Social Sign-in Widget was released in September of 2011 and provides many new features and performance improvements. To learn about the new Sign-in Widget, visit the Social Sign-in Widget page.

It is Janrain’s policy to maintain and support legacy UI widgets for 12 months following the release of new replacement widgets. When the 12 month support period expires, Janrain will no longer add features or provide maintenance updates for the legacy widget, such as support for new versions of web browsers. Support for the legacy Social Sign-in Widget will end on December 1st, 2012.

FAQ ¶

Q: Does this mean that my old Sign-in Widget will stop working on December 1st, 2012?

A: No. Your widget will continue to work, and support all the browser versions that were previously supported, however it may not work with the latest browser version.

Q: Is it hard to switch to the New Sign-in Widget?

A: No, it is very straight forward and we have instructions for you to get started on the Social Sign-in Migration Guide page.

This is the fastest and most popular way to implement Janrain Engage. It enables users to use their existing accounts from over twenty different Identity Providers such as AOL, Facebook, Google, Hotmail, LinkedIn, Salesforce, Yahoo!, and others to sign-in or sign-up on your site.

Custom Provider Lists ¶

You can configure the provider list using the Janrain dashboard to show the providers that your users are most likely to use. It presents the user with a scrollable palette of buttons, one for each configured provider.

One Click Sign-in ¶

On return visits, the user’s preferred provider displays prominently. Depending on the providers capabilities, the user may be able to sign-in with a single click.

Janrain Engage uses JavaScript to add a user friendly Social Sign-in box to your website. We supply you with customized JavaScript ready to drop into your existing web site.

Display Modes (Widget Style) – Embedded or Modal ¶

You can embed the widget interface directly into a page or add a link to display a modal dialog.

Best Practices ¶

For both sign-in and sign-up we recommend placing the sign-in widget above the traditional sign-in or registration form. This encourages users to try the sign-in widget first. They discover that it completes some or all of the form for them before proceeding to supply any additional information you may require.

Basic Implementation ¶

This tutorial walks you through the process of coding by hand to better understand how Janrain Engage works. In practice this code is included in our plugins, copied from our examples, or generated by your Janrain Dashboard.

Begin ¶

To get started, you need the following items, which you can setup with the Janrain Dashboard.

Janrain Account — Basic (free), Plus, Pro, Enterprise.
Whitelisted Domain — Also configured for your account.
Identity Providers — Select and configure your preferred identity providers.

And:

A Token URL handler, configured and placed on your server; see Authentication.

Coding Steps ¶

The main steps, which are detailed below, are:

Include the Widget Library on your page.
Initialize the Widget API with your credentials.
Embed or Link to show or invoke the widget.

Include the Widget API ¶

The widget API is a javascript library. It is hosted on our CDN (Content Delivery Network) at Janrain’s rpxnow.com domain.

You use an html script tag to load the API like any other javascript library. It’s usually best to put the script tag as the last tag inside your HTML body element.

For browser security and performance, different methods are available for http and https. For simplicity, we show each call individually; and then for practicality, we provide code that dynamically detects and switches between modes for both.

HTTP

<script type="text/javascript" src="http://static.rpxnow.com/"></script>

HTTPS

<script type="text/javascript" src="https://rpxnow.com/"></script>

Initialize the Library ¶

Initialize the library by passing in your appId (Application Identifier). You can your appId on the Janrain Engage Dashboard. For learning purposes, on your local host you can just cut and paste it directly into the JavaScript. Production code should load it dynamically. See a live example at http://engage-sample.janraindemo.com/

RPXNOW.init({appId: "YOUR APP ID", xdReceiver: window.location+'rpx_xdcomm.html'});

Embed the Widget ¶

The fastest way to display the sign-in widget is to embed it using an html iframe. You can generate this code using your Janrain Dashboard.

	<iframe	src="http://example.rpxnow.com/openid/embed?token_url=http://example.com/rpx-token-url.php" 
			scrolling="no" frameBorder="no" allowTransparency="true" style="width:400px;height:240px" />

If you have provisioned a custom CName for your brand’s domain it may look something like this instead:

	<iframe	src="http://signin.yourbrand.com/openid/embed?token_url=http://yourbrand.com/rpx-token-url.php" 
			scrolling="no" frameBorder="no" allowTransparency="true" style="width:400px;height:240px" />

Advanced Configuration ¶

Flags control widget behavior. Flags may be set on the Widget API or flags may be appended to the URL in the embedded widget iframe src property.

Embedded Flag Example – Hide Message ¶

To hide the default: “Select one of these third-party accounts” message at the top of the embedded widget, append a flags to the url (before the token_url property).

?flags=hide_sign_in_with

Modal Flag Example – Always show provider list ¶

To always show the provider list, use this code:

RPXNOW.flags = "show_provider_list"

Or to disable the welcome return experience and force reauthorization, use this code:

RPXNOW.flags = "force_reauth";

You can set more than one flag by using a comma separated list.

Default Provider ¶

The widget normally displays your full list of Identity Providers, similar to the list displayed in the image below.

Figure 1: Legacy Social Login Widget

To override this behavior, you can set a default provider with code similar to this:

RPXNOW.default_provider = "google";

Depending on which Identity Providers you have configured in your dashboard, valid values for default provider may include: aol, facebook, google, live_id, myspace, openid, yahoo, flickr, livejournal, myopenid, verisign, wordpress, blogger, hyves, netlog, twitter, linkedin, paypal, salesforce, orkut, or vznet. Use code similar to this:

RPXNOW.default_provider = "google";