To simplify the complexity of the authentication process, we broke it down to a simple timeline of events, even tho things are hardly linear. If you are in hurry and you don't want to read a novel, just scroll deep down and you will find the hooks you need.
The Authentication Process Developer API
As shown in the picture below, when a visitor click on one of providers icons, WSL will take the user in a short journey to the selected social network to ask for his permission to access his profile. If he does, and if everything goes as expected, WSL will create a new account for the user if he doesn't have one already, authenticate him within WordPress, then redirect him back to where he come from (/wordpress/2014/10/hello-world/ in the example below).
Note: Initiating the right authentication or authorisation protocol (whether OpenID, OAuth1 or OAuth2) is delegated to Hybridauth library, so all that boring stuff is dealt with.
Yep, that's 9 redirections in a row :P
To sum things up, here is the major steps that WSL will do during the authentication process:
&action=wordpress_social_authenticateis found in the current url, then WSL will display a loading screen,
- That loading screen will refresh it self adding
&redirect_to_provider=tureto the url, which will trigger the next step,
- Next, WSL will instantiate Hybridauth main class, build the required provider config then initiate the auth protocol
- Hybridauth will redirect the user to the selected provider site to ask for his consent (authorisation to access his profile),
- If the user gives his authorisation for your application, the provider will redirect the user back to Hybridauth entry point
- Hybridauth will redirect the user to the given callback url.
- In that callback url, WSL will display a second loading screen This loading screen will generate and submit a form with a hidden input
&action= wordpress_social_authenticatedto the current url which will trigger the second part of the auth process,
- WSL will grab the user profile from the provider, attempt to identify him and create a new WordPress user if he doesn't exist. In this step, and when enabled, WSL will also import the user contacts and map his profile data to Buddypress xporfiles tables,
- Finally, WSL will authenticate the user within WordPress (give him a sweet cookie) and redirect him back to
All of these actions are defined in /includes/services/wsl.authentication.php and the functions execution order is the following:
do_action('init') . wsl_process_login() . . wsl_process_login_begin() . . . wsl_render_redirect_to_provider_loading_screen() . . . Hybrid_Auth::authenticate() . . . wsl_render_return_from_provider_loading_screen() . . . . wsl_process_login_end() . . . wsl_process_login_get_user_data() . . . . wsl_process_login_request_user_social_profile() . . . . . Hybrid_Auth::getUserProfile() . . . . wsl_process_login_complete_registration() . . . . . . wsl_process_login_create_wp_user() . . . . . . wsl_process_login_update_wsl_user_data() . . . . wsl_store_hybridauth_user_profile() . . . . wsl_buddypress_xprofile_mapping() . . . . wsl_store_hybridauth_user_contacts() . . . . . . wsl_process_login_authenticate_wp_user()
Legend : action — filter — See on GitHub — Logic is simple: Left are the main functions. Right for triggered events.
Entry point to the authentication process.
This function runs after WordPress has finished loading but before any headers are sent.
This function will analyse the current URL parameters and start the login process whenever an WSL action is found:
wordpress_social_*and depending on the value of action it will either call
Start the first part of authentication.
1. Display a loading screen while hybridauth is redirecting the user to the selected provider.
2. Build the hybridauth config for the selected provider (keys, scope, etc).
3. Instantiate the class
Hybrid_Authand redirect the user to provider to ask for authorisation for this website.
4. Display a loading screen after user come back from provider as we redirect the user back to Widget
Display a loading screen while hybridauth is redirecting the user to the selected provider. This function is pluggable, see Pluggable Functions.
Build the required hybridauth configuration for the given provider (keys, scopes, callback url, etc.) .
Reset (overwrite) the requested scopes (permissions). For usage, refer to Code Snippets.
Reset (overwrite) the selected provider config. For usage, refer to Code Snippets.
Start the authentication process via hybridauth libray.
If not already connected
hybridauth::authenticate()will redirect the user to the selected
$providerAPI, where he will be asked for his consent (most providers ask for consent only once). If the user gives his authorisation to your application, the provider will redirect the user back to this same point, and this time
hybridauth::authenticate()will just return the provider
Display a loading screen after a user come back from provider and while WSL is procession his profile, contacts, etc. This function is pluggable, see Pluggable Functions.
Start the second part of the authentication process.
This function will call all the functions below either directly or indirectly, in order to perform the following tasks:
1. Get the user social profile from provider.
2. Create new WordPress user if he didn't exist in database.
3. Store the current user social profile, contacts and BuddyPress mapping.
4. Authenticate the user within WordPress.
By default and after a user authenticate, he will be automatically redirected to the page where he come from. If WSL wasn't able to identify where the user come from (or if they used wp-login.php), then WSL will redirect the user to the
Redirect URLset in WSL Widget tab instead. When Force redirection is set to Yes, users will be always redirected to
Attempt to identify the connected user by provider id, provider uid. If found, this function will return the user data.
1. Grab the user profile from hybridauth.
2. Run Bouncer::Filters if enabled (domains, emails, profiles urls).
3. Check if user exist in database by looking for the couple (Provider name, Provider user ID) or verified email.
4. Deletegate detection of user id to custom functions / hooks.
5. If Bouncer::Profile Completion is enabled and user didn't exist, we require the user to complete the registration (user name & email).
Run Bouncer Filters (domains, emails, profiles urls), if enabled.
When enabled, WSL will check the current user in allowed lists. If was not found, then Bouncer will halt the authentication process and display the appropriate error message.
This function will display Profile Completion form and it will keep calling it self until the user enter a valid username and email.
This function will attempt to create a new WordPress user. This function will only kick in for new users.
Reset the array of user data. See: http://codex.wordpress.org/Function_Reference/wp_insert_user#Parameters.
wp_insert_user()WordPress builtin function.
Create a new WordPress user: Insert a user into the database.
Store WSL user data:
1. Store Hybridauth user profile
2. Import user contacts
3. Launch BuddyPress Profile mapping
Store the user social profile in table
wslusersprofiles. WSL only sotre the user profile if it has changed since last login.
When enabled, this function will map the user social profile to buddypress xprofile table. Profile mapping will only work with new users.
When enabled, this function will import user contacts into
wsluserscontacts. WSL only import the contacts list once per user per provider.
This function will attempt to log the user withing WordPress.
update_user_meta()WordPress builtin function.
update some fields in usermeta for the current user
When enabled, WSL will check for the current user role. If equal to
pendingthen Bouncer will do the following :
1) Halt the authentication process,
2) Skip setting the authentication cookies for the user,
3) Reset the
Redirect URLto the appropriate Theme My Login page.
wp_set_auth_cookie()WordPress builtin function.
Sets the authentication cookies based User ID.
User Moderationis enabled and the current user is NOT validated yet, then this function WILL NOT kick in.
do_action( 'wp_login', $user_login )WordPress builtin action hook.
To keep things standard with the WordPress way of doing things, WSL will trigger the builtin action hook
wp_loginaction hook is triggered when a user logs in by the
wp_signon()function. It is the very last action taken in the function, immediately following the
wp_safe_redirect()WordPress builtin function.
Redirect the user to
Redirect URLor to the appropriate Theme My Login pending page.