Manage the ActivID AS Customization Files

The customization package contains all the customization files (that is, the branding and configuration files) for the ActivID AS applications currently installed on the server.

The ActivID application folders (Authentication Portal, Management Console, Self-Service Portal and Mobile Application) in the customization package have the same hierarchy for branding as that on the file system.

The branding files are stored in the <ACTIVID_HOME>/ActivID_AS/applications/branding directory on the file system (referred to as <BRANDING_HOME> from this point).

The package is organized in the following multi-level structure:

metadata.properties file − This metadata file provides information on the customization package such as the version (ActivID AS can only apply a customization package if the version of the package matches the version of the customization scripts currently installed on the server).

The current version of the customization package is 2.0.
AuthenticationServer folder − contains the ActivID Authentication Server configuration files (no branding).
AuthenticationPortal folder − contains the ActivID Authentication Portal customization files.
ManagementConsole folder − contains the ActivID Management Console customization files.
SelfServicePortal folder − contains the ActivID Self-Service Portal customization files.
MobileApplication folder − contains the HID Approve mobile application branding file (no configuration) as a .json file.

The application folders (except AuthenticationServer) contain a branding sub-folder with the following category folders:

In all customization packages:

default folder – default branding files that should NEVER be updated manually.

Note: The default folder and its contents are NOT customizable. They are included in the package to be used as templates for the customized files.

In packages generated on deployments with existing customization:

_common_ folder – customization files common to all domains.

<DOMAIN> folder – domain-specific files (where <DOMAIN> is the domain name).

Note: If you have not previously customized your deployment, these folders do not exist. You will need to create them manually (using the default folder as a template) in order to store your customized files in the package to upload.

Each category folder contains the application-specific customization files in dedicated sub-folders where:

Authentication Portal – ap
Management Console – mc
Self-Service Portal – ssp
Mobile Application – mobile-app

Example of the ActivID AS Customization Package Contents

For example, in an ActivID AS deployment:

With two domains (ENTERPRISE and ONLINEBANK).
Localized with English and French labels.

The contents of the ActivID Self-Service Portal branding folder (SelfServicePortal) would be:

Example of ActivID Self-Service Portal Branding Files for Customization

Folder	Application	Contents	Comment
_common_	ssp	img - <customized images> ac-4tress-ssp_en.properties ac-4tress-ssp_fr.properties	Common to all domains.
default	ssp	img - <default images> ac-4tress-ssp_en.properties	Default images and labels.
ENTERPRISE	ssp	img - <customized images> ac-4tress-ssp_en.properties ac-4tress-ssp_fr.properties	Domain-specific.
ONLINEBANK	ssp	img - <customized images> ac-4tress-ssp_en.properties ac-4tress-ssp_fr.properties	Domain-specific.

Generate a Customization Package

ActivID AS includes a script designed to generate a package of the current customization of your system.

You can also use the script to:

Backup your current configuration and the branding before making any modifications. If necessary, you can restore the backed up configuration.
Replicate your customization on other ActivID AS servers.

To generate the customization package for an ActivID AS server, run the customizeApplications.sh script using the following command as ftadmin:

Copy

<ACTIVID_HOME>/ActivID_AS/bin/customizeApplications.sh –c <Output folder>

Where:

-c is the flag to use for the creation of the customization package.
<Output folder> is the path to the folder where the customization package will be created.

The package is generated as a .zip file called ActivID_AS_Customization_<CreationDate>.zip where <CreationDate> is the package creation date and time in the format YYYY-MM-dd_HH-mm.

Apply a Customization Package

You apply a customization package using the same script as the creation process.

You can also use the script to replicate your customization on another ActivID AS server.

Once the new files are ready, add them to the customization package in the correct location so that the following are present at the root:

<ApplicationFolder>/branding/_common_/<application> for a customization common to all domains.
<ApplicationFolder>/branding/<DOMAIN_NAME>/<application> for a domain-specific customization (for the ActivID Authentication Portal and Self-Service Portal only).
metadata.properties file.

Important:

The domain folder name must correspond to the existing domain name and is case-sensitive.
The file names and file extensions must be kept as-is in the original package.

To apply a customization package on an ActivID AS installation, run the customizeApplications.sh script as ftadmin using the following command:

Copy

<ACTIVID_HOME>/ActivID_AS/bin/customizeApplications.sh <option> <package file path>

Where:

<option> indicates how the customization package is applied:
-uf – to apply the full package
-uc – to apply only the configuration files
-ub – to apply only the branding files

<package file path> is the path to the customization package file to apply.

The script checks the integrity of the package:

Version of the customization package.

Validity of folders hierarchy inside the package.

Validity of file position in the folder hierarchy.

Note: If any of the checks above fail, the script displays an error message.

The script then compares the contents of the customization package with the customization files present on the target system according to the installed applications. It then prompts the user to confirm the resulting intersection.

Review the proposed intersection of the package and confirm the operation.

Before applying the customization from the package, the script backs up the existing customization (all the branding and configuration files for the installed applications).

The backup folder is called <ACTIVID_HOME>/ActivID_AS/backup. This folder is created (with the appropriate user, group and permissions) if it does not already exist.

The backup itself is a customization package generated as described in Generate a Customization Package.

Important: At the first reset or the first application of a customized package, this backup folder contains the default versions of all the customizable configuration files (but not the branding files).

Do NOT delete this backup or you will not be able to restore the default configuration.

The script then applies the branding and configuration files, overwriting the:

Branding files – it first deletes the existing files on the server and then adds those from the package.
Configuration files – it overwrites the existing version on the server.

Any customizable files NOT present in the customization package remain unchanged on the file system (the existing version on the file system is NOT deleted).

If the script returns a success code (0), restart the ActivID AS applications.

If the script fails, it returns a code and error message:

1: Invalid input (invalid command line, package file/output folder path or package format)

2: Invalid package version

3: Internal error

If required, correct the package error as indicated by the error code and run the script again.

Customize the ActivID AS WAR/EAR Files

If you have specific deployment requirements, you can customize an ActivID AS application WAR/EAR file.

After adding your customization, you then generate and deploy the new WAR/EAR. The re-generation process:

Creates the EAR/WAR file based on the content of the <ACTIVID_HOME>/ActivID_RPM/<application>/package folder.
Adds/overwrites the content of the EAR/WAR file with the content of the <ACTIVID_HOME>/ActivID_RPM/<application>/custom folder.

Important: Do not modify the file content and folder structure of the original ActivID AS application EAR/WAR delivery. Customization must be added to the dedicated ‘custom’ folder.

As root, create a folder called custom in the <ACTIVID_HOME>/ActivID_RPM/<application> folder, where <application> corresponds to the ActivID AS application EAR/WAR that you want to customize:
- ac-4tress-srv - the ActivID Authentication Services EAR file (activid-authentication-services-<app-server>.ear).
- ac-4tress-ap - the ActivID Authentication Portal WAR file (activid-authentication-portal-<app-server>.war) that is embedded in the ActivID Authentication Services EAR file.
- ac-4tress-ssp - the ActivID Self-Service Portal WAR file (activid-self-service-portal-<app-server>.war).
- ac-4tress-mc - the ActivID Management Console WAR file (activid-self-service-portal-<app-server>.war).
In the <ACTIVID_HOME>/ActivID_RPM/<application>/custom folder, copy the customized content that you want to add/update in the EAR/WAR file.

The organization of your customized content should exactly match that of the target EAR/WAR file.

For example, if you want to customize the ActivID Authentication Portal’s jboss-ejb3.xml file where the original file location is:

activid-authentication-services-<app-server>.ear/

activid-authentication-portal-<app-server>.war/

WEB-INF/

jboss-ejb3.xml

Then you have to add your customized jboss-ejb3.xml file in the following location:

<ACTIVID_HOME>/ActivID_RPM/ac-4tress-ap/custom/WEB-INF/

As root, regenerate the ActivID AS application WAR/EAR files using the following command:
Copy
```
<ACTIVID_HOME>/ActivID_AS/bin/updateSoftware.sh -g
```

This operation regenerates each EAR/WAR file into the <ACTIVID_HOME>/ActivID_AS/deploy folder.

As the application server administrator, deploy the new ActivID AS application WAR/EAR file.
Restart the server.