Jump to content

Developer Documentation

Introduction to Login Methods

Note: This documentation applies to Invision Community 4.3 and higher only. For older versions, see 4.2 and below: Login Handlers. Basic functionality will be backwards compatible.

Introduction

Invision Community allows users to log in using a number of different Login Handlers. For example, in addition to the "Standard" login handler where the user enters their email address or display name and password that they used to register, users can also log in with their Facebook account, or using credentials provided by an external MySQL database.

A Login Handler which has been set up is called a Login Method. Some Login Handlers can be used more than once (creating multiple Methods) and some cannot. For example, you can have multiple external MySQL databases but there is only one Facebook.

Types and Class Structure

All Login Handlers extend the abstract \IPS\Login\Handler class.

Login Handlers can work in two ways:

  • Username/Password Handlers allow the user to enter either a display name or an email address and a password (for example: the Standard handler, external MySQL database, LDAP directory). These will use the \IPS\Login\Handler\UsernamePasswordHandler trait.
  • Button Handlers work by the user clicking a button which redirects them to an external site to authenticate (for example: Facebook, Twitter, etc.). These will use the \IPS\Login\Handler\ButtonHandler trait.

Usually a Login Handler will only use one of these traits, however it can use both and change its behaviour based on how the Method is configured.

There are also base classes for OAuth-based handlers (one for OAuth 1.0 and one for OAuth 2.0) which extend \IPS\Login\Handler to provide some shared code between Login Handlers which use OAuth.  

This is the class structure of all the Login Handlers provided in Invision Community by default:

  • abstract \IPS\Login\Handler
    • abstract \IPS\Login\Handler\OAuth2 uses \IPS\Login\Handler\UsernamePasswordHandler and \IPS\Login\Handler\ButtonHandler
      • \IPS\Login\Handler\OAuth2\Facebook
      • \IPS\Login\Handler\OAuth2\Google
      • \IPS\Login\Handler\OAuth2\LinkedIn
      • \IPS\Login\Handler\OAuth2\Microsoft
      • \IPS\Login\Handler\OAuth2\Invision
      • \IPS\Login\Handler\OAuth2\Wordpress
      • \IPS\Login\Handler\OAuth2\Custom
    • abstract \IPS\Login\Handler\OAuth1
      • \IPS\Login\Handler\OAuth1\Twitter
    • \IPS\Login\Handler\ExternalDatabase
    • \IPS\Login\Handler\LDAP

Understanding the Flow

When a user uses a Login Method they may or may not already have an account in the community's database. If the authentication is successful, one of three things will happen:

  • If the user has logged in with that Login Method before (for example, they are logging in with Facebook and have done that on that community before), the Login Handler will return the \IPS\Member object for the member, and they will be logged straight in.
  • If the user has not logged in with that Login Method before, the Login Handler will attempt to create an account, optionally providing (if it knows them) a display name and an email address. Invision Community will then either:
    • If there is already an account in the database with the same email address as what the Login Handler provided, the user will be prompted to link the accounts by authenticating with another Login Method they have used before (usually this means entering their password).
    • If there is not already an account with the same email address, or the Login Handler did not provide an email address, an account will be created (unless the administrator has configured the Login Method to not allow new accounts to be created) and the user will either be logged straight in, be prompted for more information to create their account, or be required to validate, depending on what information the Login Handler provides and what settings the administrator has chosen.

Getting Started

To get started with a basic skeleton Login Handler:

  1. With Developer Mode enabled, create an application you will use for your Login Handler from the Applications page in the AdminCP.
  2. Create a class for your login handler using the skeleton below. You will need to set an appropriate value for $allowMultiple (see above more information) and return the key for the language string you just created in the getTitle() method.
  3. Create a code hook on the \IPS\Login\Handler class to add the name of the class you just created to the value returned by \IPS\Login\Handler::handlerClasses(). See below for sample code.

Login Handler Skeleton 

<?php
	
namespace IPS\mycustomloginhandler;

/* To prevent PHP errors (extending class does not exist) revealing path */
if ( !defined( '\IPS\SUITE_UNIQUE_KEY' ) )
{
	header( ( isset( $_SERVER['SERVER_PROTOCOL'] ) ? $_SERVER['SERVER_PROTOCOL'] : 'HTTP/1.0' ) . ' 403 Forbidden' );
	exit;
}

class _MyCustomLoginHandler extends \IPS\Login\Handler
{
	/**
	 * @brief	Can we have multiple instances of this handler?
	 */
	public static $allowMultiple = FALSE;
		
	/**
	 * Get title
	 *
	 * @return	string
	 */
	public static function getTitle()
	{
		return 'my_cusom_login_handler'; // Create a langauge string for this
	}
}

Sample Code Hook 

//<?php

/* To prevent PHP errors (extending class does not exist) revealing path */
if ( !defined( '\IPS\SUITE_UNIQUE_KEY' ) )
{
	exit;
}

abstract class mycustomloginhandler_hook_loginHandlerHook extends _HOOK_CLASS_
{
	public static function handlerClasses()
	{
		$return = parent::handlerClasses();
		$return[] = 'IPS\mycustomloginhandler\MyLoginHandler';
		return $return;
	}
}

 

Next Steps

  1. Follow the instructions specific to the type of Login Handler you are creating, creating any settings you need as you do so:
  2. Follow instructions for adding profile syncing
  3. Follow instructions for adding any advanced features you need
Edited by Mark
  Report Document


Invision Community © 2024 IPS, Inc.
×
×
  • Create New...