Admin login providers
Introduction
As of 10.10.0, Preside comes with a system for providing alternative login providers for the admin system. The system expects you to:
- configure what providers are available to the application
- provide a login prompt UI for your provider that will be displayed in the login screen
- process the login with your own handler logic
- complete the login with helper methods provided by Preside
Configuration
The configured admin login providers are a simple array defined in your application or extension's Config.cfc
file. The default is:
settings.adminLoginProviders = [ "preside" ]; // 'preside' is the core admin login provider
You can override or extend this setting to render multiple login options in the login screen. For example:
public void function configure() {
// ...
ArrayAppend( settings.adminLoginProviders, "myCompanyActiveDirectory" );
// or
settings.adminLoginProviders = [ "myCompanyActiveDirectory", "preside" ];
// or
settings.adminLoginProviders = [ "myCompanyActiveDirectory" ];
// ...
}
Defining your login provider
The only requirement for a login provider is that it must have a viewlet to render a login prompt in the login form. The location of this viewlet must be admin.loginprovider.{providerid}.prompt
. i.e. you can either implement a simple view at /views/admin/loginProvider/myprovider/prompt.cfm
or a handler with prompt()
method at /handlers/admin/loginProvider/MyProvider.cfc
.
The viewlet will receive two args in its args
struct:
postLoginUrl
: the ideal URL to redirect to once login is completeposition
: the position of the rendered prompt in the admin login screen. You may wish to present the prompt differently when it is the primary provider (e.g. position=1)
A simple example:
<!-- /views/admin/loginprovider/oneClickLocalLogin/prompt.cfm -->
<cfoutput>
<p class="text-center">
<a class="btn btn-info" href="#event.buildAdminLink( "loginProvider.oneClickLocalLogin.dologin" )#">
<i class="fa fa-key fa-fw"></i>
#translateResource( "cms:one.click.local.login.btn" )#
</a>
</p>
</cfoutput>
Processing and completing login
The processing of actual login logic is up to you. However, once you have identified the user, you can log them into Preside with the event.doAdminSsoLogin()
method.
Let's complete our oneClickLocalLogin
provider example by providing the dologin
action that the login button links to:
// /handlers/admin/loginprovider/OneClickLocalLogin.cfc
component {
public void function dologin( event, rc, prc ) {
// here we are hardcoding the user
// so we can do 1 click login
// for local dev. In practice, this
// information will have been supplied
// by your login provider (e.g. Google)
var hardCodedLoginId = "sysadmin";
var hardCodedUserData = {
email_address = "[email protected]"
, known_as = "The Sys Admin"
};
// we call event.doAdminSsoLogin()
// to log the user in without a password
// and to complete the rest of the login
// logic for us
event.doAdminSsoLogin(
loginId = hardCodedLoginId
, userData = hardCodedUserData
, rememberLogin = true
, rememberExpiryInDays = 90
);
}
}