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.

There are additional modules available for Alfresco Content Services and Alfresco Share. These modules add a JWT-authentication mode to Alfresco, so these systems can 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.

System Requirements

The following are estimated system requirements for Alfred Edge 1.0. 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.0. 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 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 (= 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 jwt-auth-repo.amp artifact needs to be installed and the authentication chain in Alfresco needs to be configured.

Installation

Use the standard procedure to install 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.

By default the Alfresco JWT module ships with a default shared password: secret. This can be changed by setting the property authentication.jwt.token.secret in `alfresco-global.properties.

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, before changing the default 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 default “secret”, this is a valid JWT token, representing the admin user:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiJ9.PGnRccPTXeaxA8nzfytWewWRkizJa_ihI_3H6ec-Z
bw

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/

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 default 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 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. This module reads a configuration file from the filesystem from the property jwt.auth.properties.location. This property can be provided as a VM argument as -Djwt.auth.properties.location=file:///opt/alfresco/config/jwt-auth.properties.

So there are two steps involved, after installing the .amp in share.war:

Step 1: Create a property file jwt-auth.properties with the contents:

authentication.jwt.header.name=Authorization
authentication.jwt.header.schema=Bearer
authentication.jwt.secret=my-shared-secret

Step 2: Add a VM argument to the Tomcat startup parameters with key jwt.auth.properties.location and value the path to the properties file. For example:

JAVA_OPTS="$JAVA_OPTS -Djwt.auth.properties.location=file:///opt/alfresco/config/jwt-auth.properties"

Note: in the future, Alfred Edge will look for this properties file, relative to the application root, but that is not yet implemented.

Configuration Reference

The configuration reference is for both the modules jwt-auth-repo.amp and 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.pasword

The password or passphrase for the keystore.

authentication.jwt.keystore.alias

The name or alias of the public key in the keystore