Close

Configure Identity Service

There are two things that can be configured in the Identity Service:

Configure a custom realm

The Identity Service is installed or deployed with a default realm applied called Alfresco. The realm can be customized manually or by using a JSON file.

Important: The default realm provided is not production ready and should be used as a reference only.

Customize a realm manually

Customizing a realm manually uses the administrator console of the Identity Service to configure realm settings.

  1. Sign into the master realm administrator console using the credentials created on your first sign in.
  2. Add a new realm or edit the Alfresco realm.
  3. Create a new OIDC client or edit the existing one.
  4. Configure any groups or users.

Customize a realm using a JSON file

Customizing a realm using a JSON file configures a realm outside of the Identity Service and imports it into the configuration using the administrator console or during deployment if installing to Kubernetes cluster using Helm charts.

To import the configuration in the administrator console:

  1. Edit or use the default realm file provided in the Identity Service GitHub project as a reference to create a custom realm file.
  2. Sign into the master realm administrator console using the credentials created on your first sign in.
  3. Navigate to the Create Realm page and use the Browse… option to import your custom realm file.

To set the realm file during deployment:

  1. Create a Kubernetes secret in the cluster called realm-secret:

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

    Important: The name of the realm file must not be set as alfresco-realm.json

  2. Deploy the Helm chart with the additional argument to use the custom realm file (remember to replace any <placeholders>):

     cat > realm-values.yaml << EOL
     keycloakx:
       extraEnv: |
         - name: KEYCLOAK_ADMIN
           value: <placeholder>
         - name: KEYCLOAK_ADMIN_PASSWORD
           value: <placeholder>
         - name: KEYCLOAK_IMPORT
           value: /data/import/realm.json
         - name: JAVA_OPTS_APPEND
           value: >-
             -Djgroups.dns.query={{ include "keycloak.fullname" . }}-headless
     EOL 
    
     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 \
         --values realm-values.yaml \
         --namespace $DESIREDNAMESPACE
    

Run Identity Service with Process Services

You can run the Identity Service with Process Services. You must configure both applications for the logout functionality in Process Services to function correctly.

Note: If you do not configure the Identity Service and Process Services correctly, you will receive an error when you try and logout using Process Services.

To run the Identity Service with Process Services:

  1. Deploy your Identity Service installation by adding the following command-line parameter:

     --spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true
    
  2. Ensure you’ve set keycloak.token-store=cookie in the activiti-identity-service.properties file in Process Services.

    See keycloak.token-store in the Process Services properties table for more details.

  3. Restart Process Services.

The Process Services logout functionality will now work with the Identity Service.

Configure a custom theme

Deploying the Identity Service will deploy an Alfresco login theme.

A custom theme can be applied to the following components of the Identity Service:

  • Login screens
  • Administrator console
  • Email
  • Account management

The Alfresco theme includes a custom login theme only.

Developing a theme

Themes are created using a combination of CSS, HTML Freemarker templates, theme properties and images.

Use the Alfresco theme or the default Keycloak theme as a base to extend and create custom themes from.

Importing a theme for a Kubernetes deployment

There are a number of options for importing a theme into a Kubernetes deployment, for example:

  • Create a new Docker image that contains a custom theme.
  • Use an emptyDir that is shared with the Identity Service container and configure an init container that runs the new theme image and copies it into the theme directory.

    The following is an example of configuring this in the values.yaml:

      keycloak:
          extraInitContainers: |
              - name: custom-theme
                image: <theme-image-location-and-tag>
                imagePullPolicy: IfNotPresent
                command:
                  - sh
                args:
                  - -c
                  - |
                    echo "copying new theme..."
                    cp -R /<theme-image-name>/* /theme
                volumeMounts:
                  - name: theme
                  mountPath: /theme
        
          extraVolumeMounts: |
              - name: theme
                mountPath: /opt/keycloak/themes/<theme-folder-name>
        
          extraVolumes: |
              - name: theme
                emptyDir: {}
    

However a new theme is imported, the new theme will need to be applied by signing into the administrator console and selecting the new themes for each component in the Themes tab under Realm Settings.

Importing a theme for a standalone installation

  1. Navigate to the themes directory of the installation.
  2. Create a new directory for the custom theme.
  3. Copy the custom files into directories for each custom theme component for example /themes/login/
  4. Restart the Identity Service service.
  5. In the administrator console select the new themes for each component in the Themes tab under Realm Settings.

Edit this page

Suggest an edit on GitHub
This website uses cookies in order to offer you the most relevant information. Please accept cookies for optimal performance. This documentation is subject to the Documentation Notice.