How to add a custom Login Module in CQ / AEM

Use Case:

1) You want to create a custom login module in CQ / AEM
2) You already have a custom login module in CQ5.4 and integrate it with CQ5.5

Prerequisite: Please check http://dev.day.com/content/kb/home/cq5/CQ5Troubleshooting/cq55prerelease-installandconfigchanges.html

Solution:

CQ 5.6 and less

Any custom login module should be added in CQ5.6 and less as a JAAS module. That mean CQ should have access to module during load time.

Here is set of steps you might have to do to create custom login module

1) Create a OSGI bundle with class that extend Jackrabbit AbstarctLoginModule (Example http://wemcode.wemblog.com/custom-login-module)

2) Create bundle as frangment bundle attached it to com.day.crx.sling.server



<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>
<Import-Package>!com.day.crx.core.token,!org.apache.jackrabbit.*,*</Import-Package>
<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
<Export-Package>....... Package you want to export .... </Export-Package>
<Fragment-Host>com.day.crx.sling.server</Fragment-Host>
<Bundle-Name>${project.name}</Bundle-Name>
<Bundle-Description>${project.description}</Bundle-Description>
<Bundle-Version>${project.version}</Bundle-Version>
<Include-Resource>lib=${basedir}/lib</Include-Resource>
<Bundle-ClassPath>
.,
lib/<Your custom jar file>.jar,
</Bundle-ClassPath>
</instructions>
</configuration>
</plugin>

3) Deploy and start your bundle as start level 15. You can do following things for that

curl -u admin:admin -T <Your custom module bundle>.jar http://<host>:<port>/apps/<Your path>/install/15/<Your login module>.jar

Or


<profiles>
<profile>
<id>install-packages</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.sling</groupId>
<artifactId>maven-sling-plugin</artifactId>
<executions>
<execution>
<id>install-package</id>
<goals>
<goal>install</goal>
</goals>
<configuration>
<slingUrl>${crx.url}/system/console/install</slingUrl>
<user>${crx.user}</user>
<password>${crx.password}</password>
<bundleStartLevel>15</bundleStartLevel>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>

4) Change repository.xml 

Open the file crx-quickstart/repository/repository.xml (on the server's filesystem) and remove the <LoginModule>...</LoginModule> element.
Find the <SecurityManager> element and add the WorkspaceAccessManager as shown below:
<SecurityManager class="com.day.crx.core.CRXSecurityManager">
<WorkspaceAccessManager class="org.apache.jackrabbit.core.security.simple.SimpleWorkspaceAccessManager"/>
<UserManager class="com.day.crx.core.CRXUserManagerImpl">
<param name="usersPath" value="/home/users"/>
<param name="groupsPath" value="/home/groups"/>
<param name="defaultDepth" value="1"/>
</UserManager>
</SecurityManager>

5) Create custom jaas config

Now create the file crx-quickstart/conf/jaas.conf. In this file you would have something like this:

com.day.crx {
<Your login Module class name> sufficient
com.day.crx.core.CRXLoginModule sufficient;
};

6) Change start up script

Update your crx-quickstart/bin/start script with this jvm parameter (Replace /path/to/your/jaas.conf with the real path to the jaas.conf file):
-Djava.security.auth.login.config=/path/to/your/jaas.conf

7) Restart your CQ

Note: if you already have Non osgi version of your custom login module, You can use http://www.wemblog.com/2012/04/how-to-integrate-3rd-party-jar-file-in.html to convert to OSGI bundle. Make sure that you follow step 2.

To debug custom login module, you can follow steps mention in http://www.wemblog.com/2011/09/how-to-set-up-debug-mode-for.html

Note that LDAP login module com.day.crx.security.ldap.LDAPLoginModule in CQ is good example of custom Login Module.

AEM / CQ 6

From CQ6 onward, Login module can now be configured as pluggable login module in OSGI. To implement Login Module in CQ6 onward you can

Option 1:

implement org.apache.sling.jcr.jackrabbit.server.security.LoginModulePlugin Here is example of Pluggable Login Module with Authentication handler http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form/src/main/java/org/apache/sling/auth/form/impl/

More info: https://sling.apache.org/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html

Option 2:

You can also use OAK external Login Module https://github.com/apache/jackrabbit-oak/tree/trunk/oak-auth-external To create custom login module (Which you register and service) as well. Example of that would be LDAP Login Module in AEM6 https://github.com/apache/jackrabbit-oak/tree/trunk/oak-auth-ldap

Here is one more example of how to use this in AEM 6 onward: https://helpx.adobe.com/experience-manager/using/oak-login.html


You do not have to restart your instance after creating custom login module in AEM 6.