alfresco/alfresco-identity-service

Repository for the Alfresco Identity Service

Alfresco Identity Service

⚠ WARNING: Alfresco Identity Service is reaching End of Life. Please refrain from using Alfresco Identity Service at this time and switch to raw Keycloak instead. This branch now contains a set of tests and examples for raw Keycloak, whereas all Alfresco Identity Service development has been moved to release/2.0.x.

Keycloak is a 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 Keycloak you can choose either a sample Kubernetes distribution or a sample standalone distribution. Both methods are described in the following sections. For upgrading, it is recommended to follow the official Keycloak upgrading guide.

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 Keycloak. It covers simple standalone startup with the Alfresco example realm, Alfresco Theme 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

1. Java 11 JDK

Installing and booting

1. Move to distribution and execute the following command: make.

2. Wait for the build process to complete, then locate the .distribution/alfresco-keycloak-${KEYCLOAK_VERSION} directory and cd into it.

3. Run the standalone boot script.

Linux/Unix

$ cd bin
$ ./kc.sh start --import-realm --http-relative-path="/auth" --hostname=<HOSTNAME> --https-certificate-file=<PATH_TO_CERT_FILE> --https-certificate-key-file=<PATH_TO_CERT_KEY_FILE>

Windows bat

> cd bin
> kc.bat start --import-realm --http-relative-path=/auth --hostname=<HOSTNAME> --https-certificate-file=<PATH_TO_CERT_FILE> --https-certificate-key-file=<PATH_TO_CERT_KEY_FILE>

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	[email protected]
Alfresco Client Redirect URIs	*

Creating the Master Realm Admin Account

After the server boots, open http://<IP_ADDRESS>: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://<IP_ADDRESS>:8080/auth/admin/alfresco/console/

Modifying the valid redirect URIs

Note: for security reasons, the redirect URIs should be as specific as possible. See Keycloak official documentation.

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

Kubernetes Deployment

Kubernetes Cluster

These instructions illustrate deployment to a Kubernetes cluster on EKS.

Please check the ACS deployment documentation.

If you are deploying Keycloak 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.

K8s Cluster Namespace

Create the namespace if it does not already exist, to avoid conflicts in the cluster:

export DESIREDNAMESPACE=example
kubectl create namespace $DESIREDNAMESPACE

This environment variable will be used in the deployment steps.

Deploying the sample Keycloak Chart

1. Prepare the EKS cluster by deploying an ingress. See the instruction here.

2. cd to the root of this repository.

3. Get the release name from the ingress deployment (step 1) and set it as a variable:

export INGRESS_RELEASENAME=<YOUR_INGRESS_RELEASE_NAME>

4. Set the Keycloak release name as a variable:

export RELEASENAME=kc

5. Deploy Keycloak.

helm install $RELEASENAME helm/alfresco-keycloak --devel \
  --namespace $DESIREDNAMESPACE

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

helm status $RELEASENAME

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

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

The above steps will deploy Keycloak 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	[email protected]
Alfresco Client Redirect URIs	http://localhost*

(Note that APS expects the email as the username)

Changing Alfresco Client redirectUris

Note: for security reasons, the redirect URIs should be as specific as possible. See Keycloak official documentation.

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

helm install $RELEASENAME helm/alfresco-keycloak --devel \
  --set realm.alfresco.client.redirectUris="{$DNSNAME}" \
  --namespace $DESIREDNAMESPACE

including multiple redirectUris:

helm install $RELEASENAME helm/alfresco-keycloak --devel \
  --set 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 realm.alfresco.client.webOrigins property:

helm install $RELEASENAME helm/alfresco-keycloak --devel \
  --set realm.alfresco.client.webOrigins="{$DNSNAME}" \
  --namespace $DESIREDNAMESPACE

For multiple webOrigins:

helm install $RELEASENAME helm/alfresco-keycloak --devel \
  --set 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 Keycloak chart with this additional setting:

  --set keycloakx.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-X chart Readme

Configuring Keycloak for production

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

1. You will need a realm file. A sample realm file is provided.

2. 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

3. Create a yaml file with following settings. The file name can be anything, for example: custom-values.yaml

keycloakx:
  extraEnv: |
    - name: KEYCLOAK_ADMIN
      value: admin
    - name: KEYCLOAK_ADMIN_PASSWORD
      value: admin
    - name: KEYCLOAK_IMPORT
      value: /data/import/alfresco-realm.json
    - name: JAVA_OPTS_APPEND
      value: >-
        -Djgroups.dns.query={{ include "keycloak.fullname" . }}-headless

NOTE: The above settings use the default admin/admin for keycloak username and password, you can replace those with your own values.

4. Deploy the Keycloak chart with the new settings:

helm install $RELEASENAME helm/alfresco-keycloak --devel \
  -f custom-values.yaml \
  --namespace $DESIREDNAMESPACE

For further details see Setting a Custom Realm.

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

Manually

1. Add a realm named "Alfresco"

2. Create an OIDC client named "alfresco" within the Alfresco realm

3. Create a group named "admin"

4. Add a new user with a username of "testuser", email of "[email protected]" and first and last name of "test"

Using the Sample Realm File

1. Go to the Add Realm page and click the "Select File" button next to the Import label.

2. Choose the sample realm file and click the "Create" button.

Releasing

The release process is explained here.

Contributing

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

alfresco-identity-service's Issues

Does alfresco keycloak supports kerberos authentication?

Does alfresco keycloak supports kerberos authentication? Otherwise how this idnetity service works with office integration with Alfresco?

Is there any OIDC integration doc?

Hi, thank you for great service.

Now, I'm trying integrating OIDC (such as Auth0) to Alfresco sign in.

I successfully launched keycloak and alfresco services by using docker-compose.
And finished setting OIDC settings on keycloak admin console.

But the login screen still show user/password styels.
How can I change the default login screen to OIDC (such as Auth0 or other login) screens... ?

move to new keycloak chart

Activiti is in the process of moving to the keycloak 4.1.0.Final. It would be good if this keycloak chart dep could therefore be moved to 3.1.0. Is there a plan to do this anyway?

There is not any 'standalone.bat' or 'standalone.ps1' in released source code

As mentioned in README.md file there must be a 'standalone.bat' and 'standalone.ps1' files in releases, but these files doesn't exist in zip or tar.gz files.

make ingress optional

For AlfrescoArchive/activiti-cloud-charts#45 (comment)

AUTH-257 - support having APS2 use common base realm

Have submitted #80 as APS needs multiple clients and roles for each.

There is a more radical alternative path available here, which would be to replace the use of the realm in the secret with:

"alfresco-realm.json": {{ .Values.realm | toJson | b64enc | quote }}

That would move all of the realm configuration into the values file. @mteodori realised that keycloak actually defaults a lot if you don't specify it so we could get away with removing a lot of the realm config that is currently present. There then wouldn't be any common base config but seeing what config was being supplied by the activiti and APS charts would be simpler.

But I'm assuming that we do want there to be common base config supplied at the AIS level.

make clientId configurable from values file

for AlfrescoArchive/activiti-cloud-charts#45 (comment)

web origins in overridden realm

Activiti is currently using https://github.com/Activiti/activiti-cloud-charts/tree/master/activiti-keycloak to wrap the stable/keycloak chart and inject the activiti realm. We'd like to use alfresco-identity-service instead.

We could put a value called ALFRESCO_CLIENT_REDIRECT_URIS in our acitivit-realm.json file and use the replace mechanism in the alfresco-identity-service chart. It's not ideal that then the realm file is no longer valid json until it gets loaded by helm (i.e. the file in github isn't valid in itself) but I think we could live with that for now. But we'd need to set origins as well as redirect uris to match what we're currently doing with sed.

Option to use persistence without alfresco infrastructure

How would Activiti apps use persistence? Is the idea that the volume needs to make the volume available, that Activiti needs to use alfresco infrastructure or that Activiti should just use h2?

distribution folder(unzipped) is removed on build.sh

Seems distribution folder (unzipped) is removed under build.sh script

This will cause problems latter on, when we do a scan

(...)
 Files to scan - File or Directory does not exists: /home/bamboo/bamboo-agent-home/xml-data/build-dir/PS-AISP-JOB1/distribution/alfresco-identity-service-1.2
(...)

Steps:

• do not remove the folder under build.sh script
• cleanup this folder in CI