Saturday, 5 March 2016

Behind the scenes of Alfresco Share Login page...

Alfresco Share Login page is the first screen you get to see when you access the Alfresco Share URL. As soon as you provide valid credentials, you are logged into the Alfresco Share, having access to the alfresco repository. Entering wrong credentials on login page displays an error message and doesn't allow you to login.

While working on the projects, you may have come across the scenarios wherein you need to modify the login page look and feel as per the client requirements. You may sometimes want to perform some logic on completion of successful login and so on...

Here is alfresco documentation link about how you can override the default login page in Alfresco Share. It's an excellent resource and provides step by step instructions to get the job done easily. If you are interested to understand how this happened so easily then you may be interested to find out how it works out-of-the-box. As a developer my viewpoint is always that, In order to do any customization,  it is essential to understand how it is working out-of-the-box. This will help you have a good understanding about how to easily customize it.

Let's have a quick look and get to know about behind the scenes working of Alfresco Share login page.

How Alfresco Share Login page gets displayed?

Alfresco Share is a web application. Once successfully deployed on Tomcat server, As soon as you hit http://localhost:8080/Share, it looks for the entries defined under <welcome-file-list> in  web.xml.It is the core file for any web application.

It defines index.jsp as the welcome file as shown in the code snippet here in the right side. Hence, this is the first page which should get rendered.

Note: The code snippets I have taken from my local alfresco installation. C:\Alfresco is the alfresco installed directory.

If we take a look at the code inside index.jsp, it simply does a redirection to the URL "page/".


Now, in order to process the request, the appropriate servlet needs to be invoked. Servlet mapping for above URL can be found in web.xml file as shown
in the code snippet here.

The corresponding servlet is org.springframework.web.servlet.DispatcherServlet and it's entry is defined in web.xml.

During the request processing, when there is no page included in the request, such as we saw above like page/, Spring MVC request dispatcher by default tries to render the default configured landing page for the site.

Default site configuration is specified in surf.xml as highlighted in the code snippet below. surf.xml is a key file which contains the default configurations for the surf application.


You should be able to find the above mentioned site configuration file at the location \tomcat\webapps\share\WEB-INF\classes\alfresco\site-data\configurations inside your alfresco installed directory.

Now, here starts the interesting stuff. If you go through the above configuration file code, it specifies the <root-page>site-index</root-page>.That is basically the surf page-definition name. Inside the location \tomcat\webapps\share\WEB-INF\classes\alfresco\site-data\pages, You should be able to locate site-index.xml file.
As highlighted in the code-snippet above, it specifies the authentication as user. This is the point where Share application identifies that in order to access the default landing page, user must be authenticated. Hence, now it tries to redirect the user to the login page. Now, let's understand how it does this.

The default configuration for login page is specified in the surf.xml as shown in the code snippet. Here, basically the login page-type mapping is specified for surf page instance id
Now, there are corresponding surf components for this page instance id such as related page definition, template instance, template type and related presentation tier web script. Following is the details about it.

Login page related Surf Components
  1. The corresponding page definition slingshot-login.xml for login page type mentioned above can be located at tomcat\webapps\share\WEB-INF\classes\alfresco\site-data\pages.It  basically specifies the corresponding template-instance as simple-guest and also it specifies the corresponding presentation web script at share tier.
  2. Template instance simple-guest.xml is located at \tomcat\webapps\share\WEB-INF\classes\alfresco\site-data\template-instances. It refers to the template-type org/alfresco/simple-guest
  3. Template type simple-guest.ftl is located at \tomcat\webapps\share\WEB-INF\classes\alfresco\templates\org\alfresco
Presentation-Tier web script

Nicely looking login page of out-of-the-box Alfresco Share is displayed using the presentation tier web script residing at the location tomcat\webapps\share\WEB-INF\classes\alfresco\site-webscripts\org\alfresco\components\guest inside of your Alfresco installed directory. Following are the web script documents for this web script.
  • Web script description document - login.get.desc.xml
  • Server side JavaScript controller - login.get.js
  • Response template - login.get.html.ftl
  • CSS dependency - login.css 
  • Client side JavaScript - login.js
The last two files above can be located at tomcat\webapps\share\components\guest in Alfresco installed directory.

The controller of this web script primarily sets up the essential details for the login form such as form submit action URL, url to redirect to on successful login and also for failure on login.

Response template login.get.html.ftl specifies the complete Login form that gets rendered on the screen.

This is how the login page gets displayed on the screen. Now what next? 

What happens when you submit the Login button?

When login page is submitted, POST request gets triggered to the url /page/dologin. If you take a look at login.get.html.ftl,you should be able to easily find it. This basically references a SpringSurf controller whose id would be dologin.There will be a corresponding bean which would be having the implementation to handle the login request,which we will see in the next section.
Inside share-security-config.xml located at tomcat\webapps\share\WEB-INF\classes\alfresco, a rule is setup as a part of CSRF filter config to not require any token for the request.

Login Form Submission URL Mapping

As we discussed above, Inside slingshot-application-context.xml located at tomcat\webapps\share\WEB-INF\classes\alfresco, url mapping has been specified for /dologin url pattern which maps to a bean id loginController in order to get the authentication done.

Login Class

loginController bean id is mapped to the back-end class which extends
In SlingshotLoginController class, once user authentication is successful then corresponding group memberships for the authenticated user are retrieved. Actual authentication is performed inside the handleRequestInternal() method of 
class,which is a parent class of

Okay, that is good enough, we got to know that which method performs the actual authentication, 
But how the actual login happens? How Share connects to Alfresco repository and authenticates the 
given user?

How user is authenticated actually?

The controller defined above uses the user factory. Default user factory is specified in surf.xml.


It uses the user factory bean id specified in surf.xml as shown in the code snippet.

The corresponding bean definition for above mentioned id is and is specified in 

To connect to alfresco repository and authenticate the user, it uses the alfresco endpoint 
which is bind to use the alfresco-ticket authenticator. The relevant class for this authenticator is 
which basically invokes api/login web script and authenticates the user. 

The above mentioned endpoint configurations can be found in the file spring-webscript-config.xml 
that can be located at org\springframework\extensions\webscripts inside 
spring-webscripts-*.jar in tomcat\webapps\share\WEB-INF\lib.
This is how it does the authentication against the alfresco repository. 
We went too much technical...isn't it?

Now, if the authentication is successful then based on the success url we specified in our presentation
tier web scripts controller implementation, it navigates to the default landing page.
If user credentials are invalid then using the failure URL, user will be redirected back to the login 
page itself.

That's it...! We have just deep dived into the technical details about understanding the out-of-the-box
login page internals. Hope you find this information useful for your reference.


  1. Aadit Majmudar18 May 2016 at 04:27

    Hi Ramesh,

    Excellent..! In and out of alfresco share login page.

  2. Such a well written article. Keep writing.

    1. Hi
      Thanks for the explanation.I have small requirement regarding share login page.
      If user enters wrong password continuosly 3 times,then account should be lock. for that I modified class,I am throwing two exceptions,one for wrong password and another for locking user.Now I need to change display message based on exceptions.can you please explain me the which files do i need to change.