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.
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).
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
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 |
|
Common to all domains. |
default |
ssp |
|
Default images and labels. |
ENTERPRISE |
ssp |
|
Domain-specific. |
ONLINEBANK |
ssp |
|
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:
<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.
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:
<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.
- 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.
- If the script returns a success code (0), restart the ActivID AS applications.
- If required, correct the package error as indicated by the error code and run the script again.
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.
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:
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 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
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.
-
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.
-
As root, regenerate the ActivID AS application WAR/EAR files using the following command:
Copy<ACTIVID_HOME>/ActivID_AS/bin/updateSoftware.sh -g
-
As the application server administrator, deploy the new ActivID AS application WAR/EAR file.
-
Restart the server.
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/
This operation regenerates each EAR/WAR file into the <ACTIVID_HOME>/ActivID_AS/deploy folder.