Acosix / alfresco-deauth

Alfresco Repository-tier addon to simplify deauthorisation of users in an Alfresco Enterprise system

About

This addon aims to provide functionality to simplify deauthorisation of users so Alfresco Enterprise Edition customers can reduce the effort to comply with their specific subscription terms and keep user counts within the allowed range.

Compatbility

This addon has been built to be compatible with Alfresco Enterprise Edition 5.1+ and Java 8.

Features

Inactive user deauthorisation

Based on the (acosix-audit module)[https://github.com/Acosix/alfresco-audit] this addon provides the means to bulk-deauthorise users that have been inactive for a specific duration of time. Inactivity is determined using the same logic as in the Audit-based web scripts to query active / inactive users of the acosix-audit module.

Deauthorisation via web script

The Repository-tier web script at URL /alfresco/s/acosix/api/deauth/inactiveUsers may be called with a POST request to trigger bulk-deauthorisation.

Parameters:

• lookBackMode - mode/unit for defining the time frame; default value: months, allowed values: days, months, years
• lookBackAmount - number of units for defining the time frame, default value: 1 (mode=years), 3 (mode=months), 90 (mode=days)
• workerThreads - the amount of parallel execution for the inactive user query phase, default value: 4
• batchSize - the size of individual batches, default value: 20
• dryRun - whether the execution should run as a simulation without actually deauthorising users, default: false

Note that the actual bulk-deauthorisation work will be done in single-threaded batches to avoid conflicts and inconsistent state in the Alfresco AuthorisationService, which has been found in practice to not behave properly in a highly concurrent scenario.

By default, the web script will use the exact same configuration as the inactive user query web script of the acosix-audit module. This means that it will also by default use the acosix-audit-activeUsers audit application as the source of data. This can be reconfigured to use any audit application, e.g. the default alfresco-access. All configuration properties share the same prefix of acosix-deauth.web.script.deauthoriseInactiveUser.. The following properties are supported:

• auditApplicationName - the name of the audit application to use (default: acosix-audit-activeUsers)
• userAuditPath - the path to the user name within the audit data to filter queries against; if empty, the user name associated with the audit entry will be used to query
• dateFromAuditPath - the path to a date or ISO 8601 string value within the audit data that denotes the start of a timeframe in which the user was active; must be set together with dateToAuditPath (default: /acosix-audit-activeUsers/timeframeStart)
• dateToAuditPath - the path to a date or ISO 8601 string value within the audit data that denotes the end of a timeframe in which the user was active; must be set together with dateFromAuditPath (default: /acosix-audit-activeUsers/timeframeEnd)
• dateAuditPath - the path to a date or ISO 8601 string value within the audit data that denotes an effective date at which the user was active
• defaultLookBackMode - the default lookBackMode if no parameter is provided in the web script call (default: months)
• defaultLookBackDays - the amount of days to look back if lookBackMode is "days" and no parameter is provided in the web script call (default: 90)
• defaultLookBackMonths - the amount of months to look back if lookBackMode is "months" and no parameter is provided in the web script call (default: 3)
• defaultLookBackYears - the amount of years to look back if lookBackMode is "years" and no parameter is provided in the web script call (default: 1)
• defaultBatchSize - the size of an atomic batch of users to process if no parameter is provided in the web script call (default: 10)
• defaultWorkerThreads - the number of parallel worker threads to use if no parameter is provided in the web script call (default: 4)
• defaultLoggingInterval - the number of processed users after which to log process information (default: 50)

If none of the date-related configuration properties are set to a valid constellation, the date of the audit entries will be used as input to the report of the web scripts.

Reports are provided in JSON or CSV format, with JSON being the default if a specific format is not reqeusted by using the URL parameter ?format=xxx or adding a file extension to the URL.

Deauthorisation via job

The Repository-tier Quartz job acosix-deauth-DeauthoriseInactiveUsersJobTrigger may be used to periodically run the same deauthorisation logic as the above web script to deauthorise inactive users.

By default, the job will use the exact same configuration as the inactive user deauthorisation web script. All configuration properties share the same prefix of acosix-deauth.job.deauthoriseInactiveUser.. The following properties are supported:

• cron - the CRON expression defining the schedule of the job, default: * * * * * ? 2099
• dryRun - whether the execution should run as a simulation without actually deauthorising users, default: true
• auditApplicationName - the name of the audit application to use (default: acosix-audit-activeUsers)
• auditApplicationName - the name of the audit application to use (default: acosix-audit-activeUsers)
• userAuditPath - the path to the user name within the audit data to filter queries against; if empty, the user name associated with the audit entry will be used to query
• dateFromAuditPath - the path to a date or ISO 8601 string value within the audit data that denotes the start of a timeframe in which the user was active; must be set together with dateToAuditPath (default: /acosix-audit-activeUsers/timeframeStart)
• dateToAuditPath - the path to a date or ISO 8601 string value within the audit data that denotes the end of a timeframe in which the user was active; must be set together with dateFromAuditPath (default: /acosix-audit-activeUsers/timeframeEnd)
• dateAuditPath - the path to a date or ISO 8601 string value within the audit data that denotes an effective date at which the user was active
• lookBackMode - the mode to determine the least granular time interval to look back into audit data (default: months)
• lookBackAmount - the amount of the least granular time intervals to look back into audit data (default: 3)
• batchSize - the size of an atomic batch of users to process (default: 10)
• workerThreads - the number of parallel worker threads to use (default: 4)
• loggingInterval - the number of processed users after which to log process information (default: 50)

If none of the date-related configuration properties are set to a valid constellation, the date of the audit entries will be used as input to the report of the web scripts.

Note: The job is disabled as well as set to dryRun-mode by default. This is to avoid accidental deauthorisation of all users should this module be installed without sufficient audit data to actually back the logic. An Alfresco administrator must explicitly enable this job and/or remove the dryRun-mode once they are confident it can work correctly with the data available.

Maven usage

This addon is being built using the Acosix Alfresco Maven framework and produces both AMP and installable JAR artifacts. Depending on the setup of a project that wants to include the addon, different approaches can be used to include it in the build.

Build

This project can be build simply by executing the standard Maven build lifecycles for package, install or deploy depending on the intent for further processing. A Java Development Kit (JDK) version 8 or higher is required for the build.

Note: This project does not provide a Travis CI build status since it relies on Alfresco Enterprise artifacts which cannot be resolved by Travis CI without adding customer-specific information to retrieve them from the private Alfresco artifact server.

Dependency in Alfresco SDK

The simplest option to include the addon in an All-in-One project is by declaring a dependency to the installable JAR artifact. Alternatively, the AMP package may be included which typically requires additional configuration in addition to the dependency.

Using SNAPSHOT builds

In order to use a pre-built SNAPSHOT artifact published to the Open Source Sonatype Repository Hosting site, the artifact repository may need to be added to the POM, global settings.xml or an artifact repository proxy server. The following is the XML snippet for inclusion in a POM file.

<repositories>
    <repository>
        <id>ossrh</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Repository

<dependency>
    <groupId>de.acosix.alfresco.utility</groupId>
    <artifactId>de.acosix.alfresco.utility.common</artifactId>
    <version>1.0.2.0</version>
    <type>jar</type>
</dependency>

<dependency>
    <groupId>de.acosix.alfresco.utility</groupId>
    <artifactId>de.acosix.alfresco.utility.repo</artifactId>
    <version>1.0.2.0</version>
    <type>jar</type>
    <classifier>installable</classifier>
</dependency>

<dependency>
    <groupId>de.acosix.alfresco.audit</groupId>
    <artifactId>de.acosix.alfresco.audit.repo</artifactId>
    <version>1.0.0.0</version>
    <type>jar</type>
    <classifier>installable</classifier>
</dependency>

<dependency>
    <groupId>de.acosix.alfresco.deauth</groupId>
    <artifactId>de.acosix.alfresco.deauth.repo</artifactId>
    <version>1.0.0.0-SNAPSHOT</version>
    <type>jar</type>
    <classifier>installable</classifier>
</dependency>

<!-- OR -->

<!-- AMP packaging -->
<dependency>
    <groupId>de.acosix.alfresco.utility</groupId>
    <artifactId>de.acosix.alfresco.utility.repo</artifactId>
    <version>1.0.2.0</version>
    <type>amp</type>
</dependency>

<dependency>
    <groupId>de.acosix.alfresco.audit</groupId>
    <artifactId>de.acosix.alfresco.audit.repo</artifactId>
    <version>1.0.0.0</version>
    <type>amp</type>
</dependency>

<dependency>
    <groupId>de.acosix.alfresco.deauth</groupId>
    <artifactId>de.acosix.alfresco.deauth.repo</artifactId>
    <version>1.0.0.0-SNAPSHOT</version>
    <type>amp</type>
</dependency>

<plugin>
    <artifactId>maven-war-plugin</artifactId>
    <configuration>
        <overlays>
            <overlay />
            <overlay>
                <groupId>${alfresco.groupId}</groupId>
                <artifactId>${alfresco.repo.artifactId}</artifactId>
                <type>war</type>
                <excludes />
            </overlay>
            <!-- other AMPs -->
            <overlay>
                <groupId>de.acosix.alfresco.utility</groupId>
                <artifactId>de.acosix.alfresco.utility.repo</artifactId>
                <type>amp</type>
            </overlay>
            <overlay>
                <groupId>de.acosix.alfresco.audit</groupId>
                <artifactId>de.acosix.alfresco.audit.repo</artifactId>
                <type>amp</type>
            </overlay>
            <overlay>
                <groupId>de.acosix.alfresco.deauth</groupId>
                <artifactId>de.acosix.alfresco.deauth.repo</artifactId>
                <type>amp</type>
            </overlay>
        </overlays>
    </configuration>
</plugin>

For Alfresco SDK 3 beta users:

<platformModules>
    <moduleDependency>
        <groupId>de.acosix.alfresco.utility</groupId>
        <artifactId>de.acosix.alfresco.utility.repo</artifactId>
        <version>1.0.2.0</version>
        <type>amp</type>
    </moduleDependency>
    <moduleDependency>
        <groupId>de.acosix.alfresco.audit</groupId>
        <artifactId>de.acosix.alfresco.audit.repo</artifactId>
        <version>1.0.0.0</version>
        <type>amp</type>
    <moduleDependency>
        <groupId>de.acosix.alfresco.deauth</groupId>
        <artifactId>de.acosix.alfresco.deauth.repo</artifactId>
        <version>1.0.0.0-SNAPSHOT</version>
        <type>amp</type>
    </moduleDependency>
</platformModules>

Other installation methods

Using Maven to build the Alfresco WAR is the recommended approach to install this module. As an alternative it can be installed manually.

alfresco-mmt.jar / apply_amps

The default Alfresco installer creates folders amps and amps_share where you can place AMP files for modules which Alfresco will install when you use the apply_amps script. Place the AMP for the de.acosix.alfresco.deauth.repo module in the amps directory, the de.acosix.alfresco.deauth.share module in the amps_share directory, and execute the script to install them. You must restart Alfresco for the installation to take effect.

Alternatively you can use the alfresco-mmt.jar to install the modules as described in the documentation.

Manual "installation" using JAR files

Some addons and some other sources on the net suggest that you can install any addon by putting their JARs in a path like <tomcat>/lib, <tomcat>/shared or <tomcat>/shared/lib. This is not correct. Only the most trivial addons / extensions can be installed that way - "trivial" in this case means that these addons have no Java class-level dependencies on any component that Alfresco ships, e.g. addons that only consist of static resources, configuration files or web scripts using pure JavaScript / Freemarker.

The only way to manually install an addon using JARs that is guaranteed not to cause Java classpath issues is by dropping the JAR files directly into the <tomcat>/webapps/alfresco/WEB-INF/lib (Repository-tier) or <tomcat>/webapps/share/WEB-INF/lib (Share-tier) folders.

For this addon the following JARs need to be dropped into <tomcat>/webapps/alfresco/WEB-INF/lib:

• de.acosix.alfresco.utility.common-<version>.jar
• de.acosix.alfresco.utility.repo-<version>-installable.jar
• de.acosix.alfresco.audit.repo-<version>-installable.jar
• de.acosix.alfresco.deauth.repo-<version>-installable.jar

If Alfresco has been setup by using the official installer, another, explicitly recommended way to install the module manually would be by dropping the JAR(s) into the <alfresco>/modules/platform (Repository-tier) or <alfresco>/modules/share (Share-tier) folders.