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:

1. If &action=wordpress_social_authenticate is found in the current url, then WSL will display a loading screen,
2. That loading screen will refresh it self adding &redirect_to_provider=ture to the url, which will trigger the next step,
3. Next, WSL will instantiate Hybridauth main class, build the required provider config then initiate the auth protocol /hybridauth/?hauth.start=PROVIDER_ID,
4. Hybridauth will redirect the user to the selected provider site to ask for his consent (authorisation to access his profile),
5. If the user gives his authorisation for your application, the provider will redirect the user back to Hybridauth entry point /hybridauth/?hauth.done=PROVIDER_ID,
6. Hybridauth will redirect the user to the given callback url.
7. 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_authenticated to the current url which will trigger the second part of the auth process,
8. 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,
9. Finally, WSL will authenticate the user within WordPress (give him a sweet cookie) and redirect him back to Redirect URL

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.

• wsl_process_login()

  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: $_REQUEST['action'] eq wordpress_social_* and depending on the value of action it will either call wsl_process_login_begin() or wsl_process_login_end().

• wsl_process_login_start

  Runs just at the the start of wsl_process_login().

---

• wsl_process_login_begin()

  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_Auth and 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 Redirect URL.

• wsl_process_login_begin_start

  Runs just at the the start of wsl_process_login_begin().

• wsl_render_redirect_to_provider_loading_screen()

  Display a loading screen while hybridauth is redirecting the user to the selected provider. This function is pluggable, see Pluggable Functions.

• wsl_hook_process_login_alter_provider

  Reset the selected provider ID.

• wsl_process_login_build_provider_config()

  Build the required hybridauth configuration for the given provider (keys, scopes, callback url, etc.) .

• wsl_hook_alter_provider_scope

  Reset (overwrite) the requested scopes (permissions). For usage, refer to Code Snippets.

• wsl_hook_alter_provider_config

  Reset (overwrite) the selected provider config. For usage, refer to Code Snippets.

• wsl_hook_process_login_before_hybridauth_authenticate

  This action run just before delegating the authentication via social networks to the Hybridauth library.

• Hybrid_Auth::authenticate()

  Start the authentication process via hybridauth libray.
  If not already connected hybridauth::authenticate() will redirect the user to the selected $provider API, 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 $adapter.

• wsl_hook_process_login_after_hybridauth_authenticate

  This action run just after delegating the authentication via social networks to the Hybridauth library.

• wsl_render_return_from_provider_loading_screen()

  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.

---

• wsl_process_login_end()

  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.

• wsl_process_login_end_start

  Runs just at the the start of wsl_process_login_end().

• wsl_hook_process_login_alter_redirect_to

  Reset the Redirect URL.

  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 URL set in WSL Widget tab instead. When Force redirection is set to Yes, users will be always redirected to Redirect URL.

---

• wsl_process_login_get_user_data()

  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).

• wsl_process_login_get_user_data_start

  Runs just at the beginning of wsl_process_login_get_user_data().

• Bouncer::Filters

  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.

• wsl_hook_process_login_alter_user_id

  ...

• wsl_process_login_complete_registration()

  This function will display Profile Completion form and it will keep calling it self until the user enter a valid username and email.

---

• wsl_process_login_create_wp_user()

  This function will attempt to create a new WordPress user. This function will only kick in for new users.

• wsl_process_login_create_wp_user_start

  Runs just at the beginning of wsl_process_login_create_wp_user().

• wsl_hook_process_login_alter_wp_insert_user_data

  Reset the array of user data. See: http://codex.wordpress.org/Function_Reference/wp_insert_user#Parameters.

• wsl_hook_process_login_before_wp_insert_user

  This action runs just before creating a new wordpress user.

• wsl_hook_process_login_delegate_wp_insert_user

  This action runs just before creating a new wordpress user, it delegate user insert to a custom function. If this filter returns a valid $user_id, WSL will not use wp_insert_user().

• wp_insert_user()

  WordPress builtin function.

  Create a new WordPress user: Insert a user into the database.

• wsl_hook_process_login_after_wp_insert_user

  This action runs just after a wordpress user has been created

  Note: At this point, the user has been added to wordpress database, but NOT CONNECTED.

---

• wsl_process_login_update_wsl_user_data()

  Store WSL user data:
  1. Store Hybridauth user profile
  2. Import user contacts
  3. Launch BuddyPress Profile mapping

• wsl_process_login_update_wsl_user_data_start

  Runs just at the beginning of wsl_process_login_update_wsl_user_data().

• wsl_store_hybridauth_user_profile()

  Store the user social profile in table wslusersprofiles. WSL only sotre the user profile if it has changed since last login.

• wsl_buddypress_xprofile_mapping()

  When enabled, this function will map the user social profile to buddypress xprofile table. Profile mapping will only work with new users.

• wsl_store_hybridauth_user_contacts()

  When enabled, this function will import user contacts into wsluserscontacts. WSL only import the contacts list once per user per provider.

---

• wsl_process_login_authenticate_wp_user()

  This function will attempt to log the user withing WordPress.

• wsl_process_login_authenticate_wp_user_start

  Runs just at the beginning of wsl_process_login_authenticate_wp_user().

• update_user_meta()

  WordPress builtin function.

  update some fields in usermeta for the current user wsl_current_provider and wsl_current_user_image

• Bouncer::User Moderation

  When enabled, WSL will check for the current user role. If equal to pending then Bouncer will do the following :
  1) Halt the authentication process,
  2) Skip setting the authentication cookies for the user,
  3) Reset the Redirect URL to the appropriate Theme My Login page.

• wsl_hook_process_login_before_wp_set_auth_cookie

  This action runs just before logging the user within WordPress (before setting the auth cookie).
  Note: If User Moderation is enabled and the current user is NOT validated yet, then this action WILL NOT kick in. (see the previous step)

• wp_set_auth_cookie()

  WordPress builtin function.

  Sets the authentication cookies based User ID.
  Note: If User Moderation is 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_login: The wp_login action 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_set_auth_cookie() call.

• wsl_hook_process_login_before_wp_safe_redirect

  This action runs just before redirecting the user back to Redirect URL.
  Note: If User Moderation is enabled and the current user is NOT validated yet, then this action WILL NOT kick in.

• wp_safe_redirect()

  WordPress builtin function.

  Redirect the user to Redirect URL or to the appropriate Theme My Login pending page.

---