Social Login
Social Login module enables people to log in into your ExpressionEngine site using their account in social network that support OAuth authentication. Currently Twitter, Facebook, LinkedIn and Yahoo! logins are supported.
General concept
To let people log into your site using their accounts on Facebook/Twitter/etc. you should place {exp:social_login:form} form on your pages. You can style it with javascript (so that it will not looks as a form) or even hardcode login links (see examples section).
When the user clicks login button (submits the form), he is brought to the site of corresponding service provider (social network) where he is asked to authorise your site. After he authorises it by clicking appropriate button/links, he is brought back to your site (any page that you specify as return).
If the member with given social network ID is already registered in your site, he is logged in into his account. Otherwise new account is created for him.
From the technical point of view, whenever a new person is trying to log in, a record is created in members database table. However the user does not get any notification about created account, he's just logged in. A custom profile field containing username/ID in social network is used to identify returning visitor.
Settings
Because Social Login is MSM-compatible module, the settings are saved separately for each site.
The general settings are:
- Member group to assign. The membership group that will be used fro people who try to log in using this module (and not registered with your site yet). It is recommended that you create separate group for them.
- Set to Pending if email cannot be obtained. If email address cannot be obtained from social network, you can force the account to be Pending (but person can still log in in order to provide email using add_userdata form). When email is added thoguh add_userdata form and you've set Self-activation via email in EE membership preferences, email with activations instructions is sent to user.
- Graphical set (icons type/size) to use. The set of icons to be used by frontend form tag. By default available are different square icons and horizonal bars. You can also use your own icons set by placing images into your themes/third_party/social_login/<your_icons_set_name> folder. The images should be in PNG format and named like <provider_name>.png (ex. twitter.png)
All other settings are provider-specific. As a general rule, you will need to provide application/customer ID, secret key and custom profile field to store the username used by service provider/social network.
The custom field is mandatory and will be used to identify whether person trying to login using external service is already registered at your site. You should use seperate field for each service provider.
Make sure you upload themes and images folder along with actual module files when performing installation
To use Facebook logins, you need to register your site at http://developers.facebook.com/setup/. After you finish the registration, you'll be provided Application ID and Secret key. Input those values into appropriate fields. Select a custom profile field to store Facebook username.
To let people login using Twitter, you need to register your site at https://dev.twitter.com/apps/new. Use your website name as Application Name. The Application Type is Browser and Default Access type you need is Read-only. You can use your site homepage as Callback URL - it will be set dynamically, so you don't have to worry about it. After you finish the registration, you'll need to provide module settings with given Consumer key (not API key) and Consumer secret. Select a custom profile field to store Twitter username.
Twitter is not sharing user's email address, so email is not stored for people who log in using Twitter
Make sure you specify something as callback URI in Twitter app settings. Though it will be overridden, this field should not be empty.
To let people login using LinkedIn, you need to register your website using https://www.linkedin.com/secure/developer. If you only want to let people log in - it is enough to fill only the required fields. Make sure you mark only r_basicprofile scope and leave all Redirect URLs empty. After you finish the registration, you'll need to provide module settings with given API key and Secret key. Select a custom profile field to store LinkedIn ID.
NOTE: we are using LinkedIn ID and not URL to identify user, because one can set the profile to be hidden - but still use it to log in.
Windows / Live ID
To let people login using their Windows account (formerly Live ID), you need to register your website using https://manage.dev.live.com/Applications/Create. If you only want to let people log in - it is enough to fill only the required fields. After you finish the registration, you'll need to provide module settings with given API key and Secret ket. Select a custom profile field to store Windows ID.
Yahoo!
To use logins using Yahoo! ID, you need to register your site at https://developer.apps.yahoo.com/projects/. Register as Standard Project, select "This app requires access to private user data" and then select "Read Public" under "Social Directory (Profiles)". After you finish the registration, you'll be provided Consumer Key and Consumer Secret. Input those values into appropriate fields. Select a custom profile field to store Yahoo! ID (note that it is stored in "short" form, i.e. username only).
To enable logins using Google account, you need to register your site at https://console.developers.google.com/project. Make sure you enable Google+ API for the project. After you finish the registration, you'll be given OAuth Consumer Key and OAuth Consumer Secret. Input those values into appropriate fields. Select a custom profile field to store Gmail address, which will be used as returning visitor identifier.
To use Instagram logins, you need to register your site at http://instagram.com/developer/clients/register/. After you finish the registration, you'll be provided Client ID and Client Secret. Input those values into appropriate fields. Select a custom profile field to store Instagram username.
In your template code for login form, add this parameter:
callback_uri="/template-url" where /template-url is your OAuth redirect_uri.
Instagram is not sharing user's email address
VK.com
To let people login using their VKontakte (VK.com) account, you need to register your website at http://vkontakte.ru/editapp?act=create&site=1. After you finish the registration, you'll need to provide module settings with given Aplication ID and Secret key. Select a custom profile field to store vKontakte ID.
VKontakte is also not sharing user's email address, so it is not stored initially
Usage
The only tag to be used in your template is {exp:social_login:form}. Place it wherever you want login form to appear.
Parameters:
- return — a page to return after login (either successful or failed). Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the page used to display login form. - no_email_return — a page to return after login if user email is not set or cannot be obtained
- id — form ID. Defaults to 'social_login_form'
- class — form CSS class. Defaults to 'social_login_form'
- name — form name. Defaults to 'social_login_form'
- popup="yes" — open the authentication dialog in popup window
- secure_action="yes" — force https usage
Form fields:
- provider — name of external login service provider to use. Can be hardcoded or auto-populated using {providers} tag pair
- auto_login — "Keep me logged in" checkbox. The value should be "1". (This will work only if your session type is "cookies only")
- anon — 'Do not show me in "who's online" list' checkbox. The value should be "1".
Inside of {providers} tag pair following variables are availabe:
- {provider_name} — provider name. This is 'technical' variable, should be used as value for 'provider' input field.
- {provider_title} — the 'full' name/title of service provider/social network
- {provider_icon} — URL for image/button for corresponding provider (from the icons set defined in settings)
You can optionally apply backspace="xx" parameter to {providers} tag pair to remove xx last characters from output result.
If you use Cookie Consent module, you need to add "allow_cookies" field to your form.
<input type='checkbox' name='cookie_consent' value='y'/> <span class="alert">Allow Cookies</span>Adding userdata (email, password)
In case when email address has not been provided by social network, you may want to ask user for it. You may also want to let people set their own password (if you want to let them login with username/password, or edit username etc.)
For this purpose, you can use form generated with {exp:social_login:add_userdata} tag pair.
Here's and example to give you idea:
{exp:social_login:add_userdata return="SAME_PAGE" id="userdata_form"}
{email_block}
<p>Please let us know your email address:<br />
<input type="text" name="email" />
</p>
{/email_block}
{password_block}
<p>For additional security, you may create password to protect your account:<br />
<input type="password" name="password" />
</p>
<p>Confirm password:<br />
<input type="password" name="password_confirm" />
</p>
{/password_block}
<input type="submit" value="Save" />
{/exp:social_login:add_userdata}
The form is displayed only when user is logged in and either email or password fields are empty. The contents of {email_block} is displayed only when email is empty. The contents of {password_block} is displayed only when password is empty.
Examples
Basic example with radio buttons
{if logged_in}
{screen_name}--{username}--<a href="{path=LOGOUT}">Log out</a>
{/if}
{exp:social_login:form return="comments/social-login"}
{providers}
<input name="provider" type="radio" value="{provider_name}" id="{provider_name}_button">
<label for="{provider_name}_button"><img src="{provider_icon}" title="Log in using {provider_title}" /></label>
<br />
{/providers}
<input type="submit" value="proceed" />
{/exp:social_login:form}
Example with auto-submitting dropdown select
{if logged_in}
{screen_name}--{username}--<a href="{path=LOGOUT}">Log out</a>
{/if}
{exp:social_login:form return="comments/social-login"}
Login using:
<select name="provider" onchange="document.getElementById('social_login_form').submit()">
<option value="">--select a service--</option>
{providers}
<option value="{provider_name}">{provider_title}</option>
{/providers}
</select>
{/exp:social_login:form}
Hardcoded login links
Replace 67 with the value of ACT input in the form (you can also find its value on module settings page in CP). RET variable is optional and can point to relative URL to redirect after login (full URLs will not work here)
<a href="http://www.mydomain.com/?ACT=67&provider=facebook&RET=/index.php/comments/social-login"><img src="http://www.mydomain.com/themes/third_party/social_login/bar/facebook.png" title="Log in using Facebook" /></a>
JavaScript-styled form
{exp:jquery:script_tag}
<script type="text/javascript">
$(document).ready(function(){
$('.extlogin').click(function(){
$('#social_login_form input[name=provider]').val($(this).attr('rel'));
$('#social_login_form').submit();
});
});
</script>
{exp:social_login:form return="SAME_PAGE"}
<input type="hidden" name="provider" value="" />
{providers}
<a href="javascript:void(0)" class="extlogin" rel="{provider_name}" title="{provider_title}"><img src="{provider_icon}" alt="{provider_title}" /></a>
{/providers}
{/exp:social_login:form}