Docker Container Customization

To start an instance of the Curity Identity Server, you can use the official Curity Docker image. This image can be utilized in several different ways, including running locally with docker-compose or on Kubernetes with a Helm chart. There are also several ways to customize the Curity Identity Server, and some of those customizations can be made when running in a Docker container. This article will point out some of the more common customizations needed and how to implement them.

The Curity Identity Server Docker image is available in Azure Container Registry.

The image can be used as-is by running this command:

docker run -e PASSWORD=<ADMIN_USER_PASSWORD> -p 6749:6749 curity.azurecr.io/curity/idsvr:latest

This article will cover different scenarios where the Curity Identity Server Docker image is used as a base image and is amended with additional components or configurations as needed.

The Dockerfile

When creating a Docker image using another image as a base, a minimal approach would be to create a Dockerfile that looks like this:

# specify the base image with your desired version curity.azurecr.io/curity/idsvr:<version>
FROM curity.azurecr.io/curity/idsvr:latest

Save it in a file named Dockerfile and run the following command to build an image with the name custom/idsvr and the tag 1.0.

docker build --tag custom/idsvr:1.0 .

The above Dockerfile and build command will simply build a new Docker image that is identical to the standard Curity Docker image but with a different name and tag. The next steps will outline how to add to that Dockerfile to customize the Docker image further.

First Run

The standard Curity Identity Server Docker image adds a script, /opt/idsvr/etc/first-run, that only runs the first time the server starts. By default, this script checks if the admin user password is set via the $PASSWORD variable. If so, it will trigger an unattended install. The unattended install can be skipped by invoking the $SKIP_INSTALL variable.

if [ -n "$PASSWORD" -a -z "$SKIP_INSTALL" ]; then
    unattendedinstall
fi

This script can also be modified to execute different actions as part of the first run. For example, it could initiate a service to push logs to another system or cue other actions to control how the installer runs.

Create the script and then use the Docker COPY command to copy the file to the correct location for the Docker image being built.

# specify the base image with your desired version curity/idsvr:<version>
FROM curity.azurecr.io/curity/idsvr:latest

COPY config/first-run /opt/idsvr/etc/first-run

Init Config

The Curity Identity Server employs an init folder that can be used to load configurations at startup. The configuration loaded via the init folder would contain the complete configurations for Data Sources, Authentication, Token Services with their Authenticators, and Actions and Clients. The target folder is /opt/idsvr/etc/init. The example below uses the COPY command to copy a full Curity Identity Server configuration file exported from the admin UI of a different system via the menu under Changes -> Download.

# specify the base image with your desired version curity/idsvr:<version>
FROM curity.azurecr.io/curity/idsvr:latest

COPY config/first-run /opt/idsvr/etc/first-run
COPY config/curity-config.xml /opt/idsvr/etc/init/

Loading a configuration at startup would allow the container to start with a fully-functioning configuration. If the container is a runtime node (no Admin), it would immediately be operational without connecting to an admin node to retrieve its configuration.

Adding Database Drivers

The Curity Identity Server ships with several out-of-the-box drivers. However, you may need to deploy additional drivers depending on the database used. An example is the Oracle database driver. It is listed in the drop-down of drivers when creating a JDBC Data Source in the admin web UI. Yet, the driver itself is not available and needs to be deployed to /opt/idsvr/lib/plugins/data.accesss.jdbc/.

Similar to copying the config file using the Docker COPY command, the jar(s) can also be copied to the image as part of the image build process. The updated Dockerfile will add a row to copy the ojdbc8.jar file to the correct location for JDBC drivers.

# specify the base image with your desired version curity/idsvr:<version>
FROM curity.azurecr.io/curity/idsvr:latest

COPY config/first-run /opt/idsvr/etc/first-run
COPY config/curity-config.xml /opt/idsvr/etc/init/
COPY db-drivers/ojdbc8.jar /opt/idsvr/lib/plugins/data.access.jdbc/

Plugins

There are several types of plugins you can use to extend the capabilities of the Curity Identity Server. Common plugins are:

• Authenticators
• Authentication Actions
• Data Access Providers (DAP)
• Token Publishers

Many open-source plugins are available in the Curity GitHub Repository. Visit the Plugin section of the product documentation for more details on plugin development.

Plugins are arguably the most common extension for the Curity Identity Server. Thus, they are a common requirement for customizing a Docker image.

Plugins are deployed in /opt/idsvr/usr/share/plugins/ and should be separated through sub-folders. E.g. deploy a custom Authenticator to /opt/idsvr/usr/share/plugins/custom-authenticator.

In the example below, on line 6, the entire contents of the custom-plugins/custom-authenticator are copied to /opt/idsvr/usr/share/plugins/custom-authenticator. This is important, as plugins often have dependencies, and several files may need to be copied.

# specify the base image with your desired version curity/idsvr:<version>
FROM curity.azurecr.io/curity/idsvr:latest

COPY config/first-run /opt/idsvr/etc/first-run
COPY config/curity-config.xml /opt/idsvr/etc/init/
COPY db-drivers/ojdbc8.jar /opt/idsvr/lib/plugins/data.access.jdbc/
COPY custom-plugins/custom-authenticator /opt/idsvr/usr/share/plugins/custom-authenticator

Templates

Templates can be used to customize the look and feel of all user-facing screens of the Curity Identity Server. Check the Front-End Development section of the product documentation for very detailed information on the Velocity templating system used for customization.

Templates are stored in /opt/idsvr/usr/share/templates. For example, the directions for changing the style of the HTML Form Authenticator would reside in /opt/idsvr/usr/share/templates/overrides/authenticator/html-form/. Additional sub-folders can control the look of UIs for account creation, password reset, forgotten username, and other visualizations. The below example assumes all HTML Form Authenticator customizations reside in the customize-curity/templates/overrides/authenticator/html-form/ folder, which is copied to the overrides folder within the Docker image.

# specify the base image with your desired version curity/idsvr:<version>
FROM curity.azurecr.io/curity/idsvr:latest

COPY config/first-run /opt/idsvr/etc/first-run
COPY config/curity-config.xml /opt/idsvr/etc/init/
COPY db-drivers/ojdbc8.jar /opt/idsvr/lib/plugins/data.access.jdbc/
COPY custom-plugins/custom-authenticator /opt/idsvr/usr/share/plugins/custom-authenticator
COPY customize-curity/templates/overrides/authenticator/html-form/ /opt/idsvr/usr/share/templates/overrides/authenticator/html-form/

Localization

Like customizing the look and feel using Templates, you can also localize the user-facing messages that the Curity Identity Server exposes. These messages can be modified to fit the customer's needs and localized for specific languages.

Message files are located in /opt/idsvr/usr/share/messages and are separated in sub-folders that define the locale they are for, such as en, or sv. More details on the naming convention can be found in the Localizing Resources section in the product documentation.

# specify the base image with your desired version curity/idsvr:<version>
FROM curity.azurecr.io/curity/idsvr:latest

COPY config/first-run /opt/idsvr/etc/first-run
COPY config/curity-config.xml /opt/idsvr/etc/init/
COPY db-drivers/ojdbc8.jar /opt/idsvr/lib/plugins/data.access.jdbc/
COPY custom-plugins/custom-authenticator /opt/idsvr/usr/share/plugins/custom-authenticator
COPY customize-curity/templates/overrides/authenticator/html-form/ /opt/idsvr/usr/share/templates/overrides/authenticator/html-form/
COPY customize-curity/messages/overrides /opt/idsvr/usr/share/messages/overrides

Removing Languages

When building the custom Docker image, it's also possible to remove unnecessary languages. Accomplish this with a simple RUN command in the Dockerfile to remove the language directory from /opt/idsvr/usr/share/messages/core/. The below example removes Swedish (sv).

# specify the base image with your desired version curity/idsvr:<version>
FROM curity.azurecr.io/curity/idsvr:latest

COPY config/first-run /opt/idsvr/etc/first-run
COPY config/curity-config.xml /opt/idsvr/etc/init/
COPY db-drivers/ojdbc8.jar /opt/idsvr/lib/plugins/data.access.jdbc/
COPY custom-plugins/custom-authenticator /opt/idsvr/usr/share/plugins/custom-authenticator
COPY customize-curity/templates/overrides/authenticator/html-form/ /opt/idsvr/usr/share/templates/overrides/authenticator/html-form/
COPY customize-curity/messages/overrides /opt/idsvr/usr/share/messages/overrides

RUN rm -r /opt/idsvr/usr/share/messages/core/sv

Using the Custom Image

Docker Compose

The Docker Compose article describes how to run the Curity Identity Server as part of a docker-compose cluster. Part of docker-compose.yml looks like this:

version: '3.2'
services:
  admin:
    image: curity.azurecr.io/curity/idsvr
    ports:
      - 6749:6749

Row 4 above defines the image for the admin node, curity.azurecr.io/curity/idsvr. This is the standard Curity Identity Server Docker image. To use a custom image, simply change the image name and tag. The example used throughout this article is custom/idsvr:1.0, making the new docker-compose.yml look like this:

version: '3.2'
services:
  admin:
    image: custom/idsvr:1.0
    ports:
      - 6749:6749

Helm

Details on running the Curity Identity Server on a Kubernetes Cluster using Helm are outlined in the Install using Helm article. Part of those guidelines include installing the Helm chart with the following command:

helm install idsvr-tutorial curity/idsvr \
    --set image.tag=latest \
    --set curity.config.password=Pa$$w0rd! \
    --set curity.config.uiEnabled=true

To use a custom image, the command would have to be changed. Using the example from this article, the snippet below replaces custom/idsvr with 1.0.

helm install idsvr-tutorial custom/idsvr \
    --set image.tag=1.0 \
    --set curity.config.password=Pa$$w0rd! \
    --set curity.config.uiEnabled=true

Conclusion

The standard Curity Identity Server Docker image is reasonably complete, but sometimes must be customized. This article has outlined several of the most common customizations needed with examples. For additional information, follow the references throughout this article to the product documentation, which explains specific configurations in much more detail.