Alfresco Identity Service

The Alfresco Identity Service will become the central component responsible for identity-related capabilities needed by other Alfresco software, such as managing users, groups, roles, profiles, and authentication. Currently it deals just with authentication. This project contains the open-source core of this service.

For installing and upgrading the Identity Service you can choose either a Kubernetes distribution or a standalone distribution. Both methods are described in the following sections.

Check the Kubernetes deployment prerequisites and standalone prerequisites before you start.

Any variation from these technologies and versions may affect the end result. If you do experience any issues please let us know through our Gitter channel.

Standalone Distribution

Overview

This guide helps you get started with the Identity Service. It covers simple standalone startup and use of the default database. Advanced deployment options are not covered. For a deeper description of Keycloak features or configuration options, consult the official Keycloak readme .

Prerequisites

Java 8 or 11 JDK

Installing and booting

Download the Identity Service zip alfresco-identity-service-1.3.0.zip from the Support Portal at http://support.alfresco.com
Place the file in a directory you choose and use the unzip utility to extract it.

Linux/Unix

$ unzip alfresco-identity-service-1.3.0.zip

Windows

> unzip alfresco-identity-service-1.3.0.zip

Cd to the bin directory of the server distribution and run the standalone boot script.

Linux/Unix

$ cd alfresco-identity-service-1.3.0/bin
$ ./standalone.sh -b <IP_ADDRESS>

Windows bat

> ...\alfresco-identity-service-1.3.0\bin\standalone.bat -b <IP_ADDRESS>

Windows powershell

> ...\alfresco-identity-service-1.3.0\bin\standalone.ps1 -b <IP_ADDRESS>

NOTE: To bind to all public interfaces use 0.0.0.0 as the value of IP_ADDRESS otherwise specify the address of the specific interface you want to use.

This is deployed with the default example realm applied which results in default values of:

Property	Value
Admin User Username	`admin`
Admin User Password	`admin`
Admin User Email	`admin@app.activiti.com`
Alfresco Client Redirect URIs	`*`

Creating the Master Realm Admin Account

After the server boots, open http://localhost:8080/auth in your web browser. The welcome page will indicate that the server is running.

Enter a username and password to create an initial admin user.

This account will be permitted to log in to the master realm’s administration console, from which you will create realms and users and register applications to be secured by Keycloak.

The Alfresco realm already has the admin account created and you can reach the realm console with the following url:

http://localhost:8080/auth/admin/alfresco/console/

Modifying the valid redirect URIs

After logging in to the Alfresco realm follow the left side menu and choose clients.
Choose the Afresco client from the client list.
In the client settings window you will have to fill in your appropiate redirect URI's for the Content and Process applications.

Kubernetes Deployment

Kubernetes Cluster

These instructions illustrate deployment to a Kubernetes cluster on AWS.

Please check the Anaxes Shipyard documentation on running a cluster.

If you are deploying the Identity Service into a cluster with other Alfresco components such as Content Services and Process Services, a VPC and cluster with 5 nodes is recommended. Each node should be a m4.xlarge EC2 instance.

Helm Tiller

Initialize the Helm Tiller:

helm init

K8s Cluster Namespace

As mentioned as part of the Anaxes Shipyard guidelines, you should deploy into a separate namespace in the cluster to avoid conflicts (create the namespace only if it does not already exist):

export DESIREDNAMESPACE=example
kubectl create namespace $DESIREDNAMESPACE

This environment variable will be used in the deployment steps.

Deploying the Identity Services Chart

In order to deploy this chart you have to deploy the Alfresco Infrastructure chart which will deploy the Identity Service too.

Using the following command only the Identity Service and the nginx-ingress will be deployed:

helm repo add alfresco-stable https://kubernetes-charts.alfresco.com/stable
helm repo add codecentric https://codecentric.github.io/helm-charts

helm install alfresco-stable/alfresco-infrastructure \
  --set alfresco-infrastructure.activemq.enabled=false \
  --set alfresco-infrastructure.nginx-ingress.enabled=true \
  --set alfresco-infrastructure.alfresco-identity-service.enabled=true \
  --namespace $DESIREDNAMESPACE

Get the release name from the previous command and set it as a variable:

export RELEASENAME=knobby-wolf

Wait for the release to get deployed (When checking status your pods should be READY 1/1):

helm status $RELEASENAME

Get local or ELB IP and set it as a variable for future use:

export ELBADDRESS=$(kubectl get services $RELEASENAME-nginx-ingress-controller --namespace=$DESIREDNAMESPACE -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

The deployment

This is deployed with the default example realm applied which results in default values of:

Property	Value
Admin User Username	`admin`
Admin User Password	`admin`
Admin User Email	`admin@app.activiti.com`
Alfresco Client Redirect URIs	`http://localhost*`

(Note that APS expects the email as the user name)

Changing Alfresco Client redirectUris

You can override the default redirectUri of http://localhost* for your environment with the alfresco-identity-service.client.alfresco.redirectUris property:

helm install alfresco-stable/alfresco-infrastructure \
  --set alfresco-infrastructure.activemq.enabled=false \
  --set alfresco-infrastructure.nginx-ingress.enabled=true \
  --set alfresco-infrastructure.alfresco-identity-service.enabled=true \
  --set alfresco-identity-service.realm.alfresco.client.redirectUris="{$DNSNAME}" \
  --namespace $DESIREDNAMESPACE

including multiple redirectUris:

helm install alfresco-stable/alfresco-infrastructure \
  --set alfresco-infrastructure.activemq.enabled=false \
  --set alfresco-infrastructure.nginx-ingress.enabled=true \
  --set alfresco-infrastructure.alfresco-identity-service.enabled=true \
  --set alfresco-identity-service.realm.alfresco.client.redirectUris="{$DNSNAME,$DNSNAME1,$DNSNAME2}" \
  --namespace $DESIREDNAMESPACE

Note in case of multiple redirectUris the values must be comma-separated with no whitespaces surrounding the corresponding commas.

If you want to deploy your own realm with further customizations, see Customizing the Realm below.

Changing Alfresco Client webOrigins

Similarly to redirectUris, webOrigins can be changed by overriding the alfresco-identity-service.client.alfresco.webOrigins property:

helm install alfresco-stable/alfresco-infrastructure \
  --set alfresco-infrastructure.activemq.enabled=false \
  --set alfresco-infrastructure.nginx-ingress.enabled=true \
  --set alfresco-infrastructure.alfresco-identity-service.enabled=true \
  --set alfresco-identity-service.realm.alfresco.client.webOrigins="{$DNSNAME}" \
  --namespace $DESIREDNAMESPACE

For multiple webOrigins:

helm install alfresco-stable/alfresco-infrastructure \
  --set alfresco-infrastructure.activemq.enabled=false \
  --set alfresco-infrastructure.nginx-ingress.enabled=true \
  --set alfresco-infrastructure.alfresco-identity-service.enabled=true \
  --set alfresco-identity-service.realm.alfresco.client.webOrigins="{$DNSNAME,$DNSNAME1,$DNSNAME2}" \
  --namespace $DESIREDNAMESPACE

Multiple Replicas, High Availability and Clustering

For added resilience, we rely on support in the Keycloak chart for specifying multiple replicas. To enable this you will need to deploy the identity chart with this additional setting:

  --set alfresco-identity-service.keycloak.keycloak.replicas=3

In addition, for high availability, Keycloak supports clustering. For more information on how to configure high availability and clustering, you can consult this additional documentation.

Keycloak Stable chart Readme

Keycloak Standalone Clustered configuration

Keycloak Clustering

NOTE: Be aware that Keycloak recommends that sticky sessions are used so keep that in mind if you choose to use a different ingress type than nginx.

Customizing the Realm

Customizing the Realm During Deployment

You will need a realm file. A sample realm file is provided.
Create a secret using your realm json file

!!NOTE The secret name must be realm-secret, and the realm file name must not be alfresco-realm.json.

kubectl create secret generic realm-secret \
  --from-file=./realm.json \
  --namespace=$DESIREDNAMESPACE

Deploy the identity chart with the new settings:

helm repo add alfresco-stable https://kubernetes-charts.alfresco.com/stable
helm repo add codecentric https://codecentric.github.io/helm-charts

helm install alfresco-stable/alfresco-infrastructure \
  --set alfresco-infrastructure.activemq.enabled=false \
  --set alfresco-infrastructure.nginx-ingress.enabled=true \
  --set alfresco-infrastructure.alfresco-identity-service.enabled=true \
  --set alfresco-identity-service.keycloak.keycloak.extraArgs="-Dkeycloak.import=/realm/realm.json" \
  --namespace $DESIREDNAMESPACE

Once Keycloak is up and running, login to the Management Console to configure the required realm.

Manually

Add a realm named "Alfresco"
Create an OIDC client named "alfresco" within the Alfresco realm
Create a group named "admin"
Add a new user with a username of "testuser", email of "test@test.com" and first and last name of "test"

Using the Sample Realm File

Go to the Add Realm page and click the "Select File" button next to the Import label.
Choose the sample realm file and click the "Create" button.

Contributing to Identity Service

We encourage and welcome contributions to this project. For further details please check the contributing file.

almerico/alfresco-identity-service