Installation Guide

System requirements and prerequisites

Use this information to review your system before you install Alfred Edge.

Alfred Edge is a Spring Boot application. It can run as a stand-alone application or can be deployed in any Servlet 3.0+ compatible container.

In order to let Alfred Edge and Alfresco work seemless together, a few additional modules are available for Alfresco Content Services and Alfresco Share.

These modules (aka amps) are :

• a JWT-authentication amp for Alfresco Respository
• a JWT-authentication amp for Alfresco Share to make these systems take advantage of the central Alfred Edge authentication.

Alfred Edge itself depends on the JSESSIONID cookie to keep browser-based connections authenticated. It requires sticky sessions to be configured in your load balancer.

A second set of additional modules contains:

• a Zipkin amp for Alfresco Respository
• a Zipkin amp for Alfresco Share

These modules allow a centralized logging of messages with Zipkin, initiated by Alfred Edge.

It is possible to install these different amps as one amp for Alfresco and one for Share. The above mentioned amps are assembled in order to guarantee the installation has the correct version of the different amps, needed by Alfred Edge.

• alfresco-edge-repo.amp: module with all Edge amps for the alfresco deployment
• alfresco-edge-share.amp: module with all Edge amps for the share deployment

System Requirements

The following are estimated system requirements for Alfred Edge 1.1. Actual requirements will vary based on your system configuration and workload.

For the application server:

• a minimum of 512Mb should be assigned to the Tomcat process (JAVA_OPTS parameter Xmx=512G). For a production system 2G RAM for the Tomcat process is recommended.
• a 64-bit processor with at least 4 cores is recommended.

Supported Platforms

These list of components have been tested with Alfred Edge and are officially supported.

For the Alfred Edge application, the following platforms have been tested:

Operating Systems

Application Servers

Alfred Edge is developed and tested with an embedded Tomcat 8.5.23

Alfred Edge can also be deployed to any Servlet 3.0+ compatible container, but this is not routinely tested.

Java

Java 8+ is required to run Alfred Edge.

Alfresco

Alfred Edge works with all Alfresco 5.x+ versions, both Enterprise and Community.

Internal testing is performed on the following versions:

Installation

There are multiple ways to run Alfred Edge in production.

Alfred Edge is a Spring Boot application and can be deployed in various ways:

1. The primary method to run Alfred Edge is with the docker image hub.xenit.eu/edge:1.1. This packages the application and it’s dependencies in an immutable image.
2. Alfred Edge is available as a standalone executable .war file. This .war file embeds a Tomcat application server, which allows you to run Alfred Edge without the installation and configuration of an application server.
3. The traditional method is to deploy Alfred Edge in Apache Tomcat (or any Servlet 3.0+ compatible container) as a .war.
4. It can also be deployed in the cloud with most popular PaaS providers.

Docker

You can contact XeniT Support at support@xenit.eu for account credentials on our private Docker Hub.

Standalone

The artifact that allows Alfred Edge to run as a standalone application is edge-x.x.x.war. A Tomcat 8.5 application server is embedded in the .jar file and does not require installation or configuration.

Alfred Edge can be run in the foreground with java -jar edge-x.x.x.war.

There is no out of the box support to run this as a background program or as a service, but there are various guides available online.

Application Server

Running Alfred Edge in an application server like Apache Tomcat is the traditional method.

1. Stop Tomcat.
2. Copy edge-x.x.x.war in \$TOMCAT/webapps and rename to ROOT.war.
3. Start Tomcat.

To configure edge through external configuration, place the edge.yml configuration file in ${CATALINA_HOME}/lib/config. You can also add the -Dspring.config.location=/path/to/config/edge.yml to the CATALINA_OPTS env variable.

Installing Alfresco Modules

The sections below describe how to install some additional modules in Alfresco and Share to facilitate the functionality Alfred Edge provides. These modules are grouped in individual amps but also into one single amp, containing the appropriate versions of the different modules for the Edge version that is released:

• alfresco-edge-repo.amp: module to add to the alfresco deployment
• alfresco-edge-share.amp: module to add to the share deployment

The major and minor version of the single amps will be identical to the major and minor version of the corresponding Alfred Edge version.

It is possible to install only some of the individual amps, if the functionality of the other amps is not wanted, but the recommended way is to install the provided single Edge amp.

Installing Alfresco JWT-modules

Alfred Edge provides central request authentication and securely propagates this information by embedding it in a JWT (Json Web Token). This JWT is signed with a secret passphrase or a private key. The signed JWT is sent with every request Alfred Edge routes to any of the backend services.

The backend services - like Alfresco or Share - can verify the signature and decode the information (containing among others the authenticated username) embedded in the JWT.

Alfresco JWT-authentication

This module adds a new external authentication subsystem to Alfresco, named external-jwt.

To integrate central authentication with Alfred Edge and Alfresco, the alfresco-edge-repo.amp (or only alfresco-jwt-auth-repo.amp) artifact needs to be installed and the authentication chain in Alfresco needs to be configured.

Installation

Install alfresco-edge-repo.amp (or only alfresco-jwt-auth-repo.amp). More information on the Alfresco Module Packages and how to install them, can be found in the Alfresco Documentation.

Configuration

In alfresco-global.properties you can configure the new JWT authentication subsystem.

Configure the Alfresco authentication chain (authentication.chain) to make use of the external-jwt authentication subsystem.

For example, you can configure the authentication chain with two members: JWT authentication and the default Alfresco Internal authentication. This means that Alfresco will first check if the request header contains a (valid!) JWT header and uses that to authenticate. If the JWT is missing from the headers or the signature is invalid, the system falls back onto the default Alfresco Internal authentication.

authentication.chain=external-jwt:external,alfrescoNtlm1:alfrescoNtlm

See the Alfresco documentation on the Authentication Subsystem Chain for more information on this topic.

Alfred Edge can use either a shared secret or public/private keys to sign the JWT.

The Alfresco JWT module ships without a default shared password. This can be set by setting the property authentication.jwt.token.secret in alfresco-global.properties or as a system property on the command that starts the application.

authentication.jwt.token.secret=my-shared-secret

It is recommended to validate the installation and configuration of the JWT module first by following the steps in the next section, after changing the shared secret to “secret”.

Validation

Once Alfresco is started, the JWT Alfresco Module installation and configuration can be validated by making a request to Alfresco with curl with a valid JWT in the Authorization header.

If the shared secret is still the sample “secret”, this is a valid JWT token, representing the admin user:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiJ9.
PGnRccPTXeaxA8nzfytWewWRkizJa_ihI_3H6ec-Zbw

(split in two lines to make the whole token visible)

With this token, we can make a request to Alfresco with curl:

$ curl --head 
    --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
            eyJzdWIiOiJhZG1pbiJ9.PGnRccPTXeaxA8nzfytWewWRkizJa_ihI_3H6ec-Zbw" 
     http://localhost/alfresco/webdav/

(split in multiple lines to make the complete command visible)

If everything was installed and configured correctly, an HTTP/1.1 200 OK should be returned and the JWT authentication works!

> HTTP/1.1 200 OK
> Server: Apache-Coyote/1.1
> Set-Cookie: JSESSIONID=D1782281AEE974435776BA7D0848C81C; Path=/alfresco; HttpOnly
> Content-Length: 0
> Date: Mon, 05 Feb 2018 10:59:10 GMT

If something is not correct (authentication.chain is not configured correctly, the JWT is invalid, …) curl will print HTTP/1.1 401 Unauthorized.

> HTTP/1.1 401 Unauthorized
> Server: Apache-Coyote/1.1
> Set-Cookie: JSESSIONID=A7F4B0E005F0FFE1CB5C2D01F0FF1F11; Path=/alfresco; HttpOnly
> WWW-Authenticate: BASIC realm="Alfresco DAV Server"
> Transfer-Encoding: chunked
> Date: Mon, 05 Feb 2018 10:58:10 GMT

If the sample shared secret is already changed in the previous configuration step, the JWT is no longer valid. The JWT can be copied & pasted into the Encoded textfield in the JWT Debugger at https://jwt.io/#debugger-io. This will decode the JWT and allows you to edit the payload and the secret.

Share JWT-authentication

To enable JWT authentication in Alfresco Share, there is a module named alfresco-edge-share.amp (or only alfresco-jwt-auth-share.amp) that needs to be installed and configured in share.war.

Unlike the Alfresco repository itself, Share does not have a global .properties file, but it can read that file if it is on the classpath. This module reads the needed parameters from the system properties and if not found from the global properties file on the class path So after installing the .amp in share.war, the needed values must be added as VM argument to the Tomcat startup parameters. For example:

JAVA_OPTS="$JAVA_OPTS -Dauthentication.jwt.header.name=Authorization 
     -Dauthentication.jwt.header.schema=Bearer 
     -Dauthentication.jwt.secret=<shared-secret> 
     -Dauthentication.jwt.keystore.path
         ="file:<path-to-keystore>" 
     -Dauthentication.jwt.keystore.password=<keystore-password>
     -Dauthentication.jwt.keystore.alias=<keystore-alias>

(in the snippet the line is split into multiple lines to make it completely visible)

Configuration Reference

The configuration reference is for both the modules alfresco-jwt-auth-repo.amp and alfresco-jwt-auth-share.amp.

external-jwt.authentication

Enable/disable the JWT authentication module.

authentication.jwt.header.name

The http request header that carries the JWT. The default is the Authorization header.

authentication.jwt.header.schema

The authentication schema used. The defaults is Bearer, as defined RFC 6750. The Bearer scheme is originally defined in RFC 6750 for the OAuth 2.0 authorization framework, but this is also appropriate for JWT-based authentication.

authentication.jwt.keystore.path

The path to the keystore on the filesystem.

authentication.jwt.keystore.password

The password or passphrase for the keystore.

authentication.jwt.keystore.alias

The name or alias of the public key in the keystore.

Installing Alfresco Zipkin Modules

In order to have distributed tracing with Zipkin available from the Alfresco Repository and Alfresco Share, the -zipkin modules need to be installed to instrument these applications.

The two amps alfresco-edge-repo.amp (or only alfresco-zipkin-repo.amp) for the Alfresco Repo and alfresco-edge-share.amp (or only alfresco-zipkin-share.amp) must be installed in the standard way.

To allow them to send the tracing to a Zipkin server, the url of the Zipkin-collector needs to be specified as zipkin.collector. This can be configured in alfresco-global.properties or as a JVM property.

For example:

JAVA_OPTS="$JAVA_OPTS -Dzipkin.collector="http://<zipkin-host>:<zipkin-port>/api/v2/spans"

The default port for the Zipkin service is TCP port 9411.

When the Alfresco Repo or Share module receives a request with a trace id, e.g. from Alfred Edge, trace information will be sent to the specified Zipkin collector.

The sampled traces can be inspected via the Zipkin UI, by default running on your Zipkin service, together with the collector.

If one wants the Alfresco Repo or Share to send these tracing, without the incoming requests having tracing, properties can be set to specify a rate of traced requests:

JAVA_OPTS="$JAVA_OPTS -Dzipkin.collector="http://<zipkin-host>:<zipkin-port>/api/v2/spans" 
        -Dzipkin.service.repo.sampler.rate=0.01
        -Dzipkin.service.share.sampler.rate=0.10

(in the snippet the line is split into multiple lines to make it completely visible)

In the above example, 1% of the repo requests and 10% of the share requests are spontaneously traced.