alfresco/alfresco-identity-service repository overview

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

⁠Kubernetes Deployment

⁠Kubernetes Cluster

These instructions illustrate deployment to a Kubernetes cluster on EKS.

Please check the ACS deployment documentation⁠.

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.

⁠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 standalone Identity Services Chart

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

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

export INGRESS_RELEASENAME=<YOUR_INGRESS_RELEASE_NAME>

1. Set the Identity Service release name as a variable:

export RELEASENAME=ids

1. Deploy the Identity Service.

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

helm install $RELEASENAME alfresco-stable/alfresco-identity-service --devel \
  --namespace $DESIREDNAMESPACE

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

helm status $RELEASENAME

1. 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 alfresco-identity-service with the default example realm applied which results in default values of:

(Note that APS expects the email as the username)

⁠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 $RELEASENAME alfresco-stable/alfresco-identity-service --devel \
  --set alfresco-identity-service.realm.alfresco.client.redirectUris="{$DNSNAME}" \
  --namespace $DESIREDNAMESPACE

including multiple redirectUris:

helm install $RELEASENAME alfresco-stable/alfresco-identity-service --devel \
  --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 $RELEASENAME alfresco-stable/alfresco-identity-service --devel \
  --set alfresco-identity-service.realm.alfresco.client.webOrigins="{$DNSNAME}" \
  --namespace $DESIREDNAMESPACE

For multiple webOrigins:

helm install $RELEASENAME alfresco-stable/alfresco-identity-service --devel \
  --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.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

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

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

keycloak:
  extraEnv: |
    - name: KEYCLOAK_USER
      value: admin
    - name: KEYCLOAK_PASSWORD
      value: admin
    - name: KEYCLOAK_IMPORT
      value: /realm/realm.json

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

1. Deploy the identity chart with the new settings:

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

helm install $RELEASENAME alfresco-stable/alfresco-identity-service --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.

⁠Contributing to Identity Service

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