Docker Container Customization
On this page
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.
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
docker build --tag custom/idsvr:1.0 .
There is a
. (dot) at the end of the command. This tells Docker to build the Dockerfile that is in the current directory.
From now on, run the same command when changing the Dockerfile and rebuilding the image.
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.
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
if [ -n "$PASSWORD" -a -z "$SKIP_INSTALL" ]; thenunattendedinstallfi
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:latestCOPY config/first-run /opt/idsvr/etc/first-run
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:latestCOPY config/first-run /opt/idsvr/etc/first-runCOPY 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.
Avoid Static Config
The Docker Image should not be built with a static configuration. Instead, a parameterized configuration should be used. With this approach, the same Docker Image can be used in different environments (dev/test/prod) where the environment-specific configurations are loaded from environment variables.
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
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:latestCOPY config/first-run /opt/idsvr/etc/first-runCOPY config/curity-config.xml /opt/idsvr/etc/init/COPY db-drivers/ojdbc8.jar /opt/idsvr/lib/plugins/data.access.jdbc/
Copying Several Jar Files
It is also possible to copy several jar files at the time by specifying
COPY db-drivers/*.jar /opt/idsvr/lib/plugins/data.access.jdbc/.
There are several types of plugins you can use to extend the capabilities of the Curity Identity Server. Common plugins are:
- Authentication Actions
- Data Access Providers (DAP)
- Token Publishers
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
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:latestCOPY config/first-run /opt/idsvr/etc/first-runCOPY 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 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:latestCOPY config/first-run /opt/idsvr/etc/first-runCOPY 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-authenticatorCOPY customize-curity/templates/overrides/authenticator/html-form/ /opt/idsvr/usr/share/templates/overrides/authenticator/html-form/
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
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:latestCOPY config/first-run /opt/idsvr/etc/first-runCOPY 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-authenticatorCOPY 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
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 (
# specify the base image with your desired version curity/idsvr:<version>FROM curity.azurecr.io/curity/idsvr:latestCOPY config/first-run /opt/idsvr/etc/first-runCOPY 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-authenticatorCOPY 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/overridesRUN rm -r /opt/idsvr/usr/share/messages/core/sv
Using the Custom Image
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/idsvrports:- 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:
Curity Identity Server Docker Images
Refer to the Curity Identity Server Docker Images page for supported images and tags.
version: '3.2'services:admin:image: custom/idsvr:1.0ports:- 6749:6749
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
helm install idsvr-tutorial custom/idsvr \--set image.tag=1.0 \--set curity.config.password=Pa$$w0rd! \--set curity.config.uiEnabled=true
The image (with tag) must be available wherever the Helm chart is installed. Depending on the installation location, the custom-built image might have to be made available in a publicly accessible repository.
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.
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.Start Free Trial