Skip to content
Connect2id

Run in Docker

The primary artifact of the Connect2id server is a Java servlet web application (WAR), which can be deployed in a servlet container like Apache Tomcat and packaged in a Docker image.

1. Docker quick start

This section describes use of the Docker image intended for evaluation and testing of the Connect2id server. The image contains a complete deployment, including a backend database, a sample login page, an OpenID relying party, and other components.

A production deployment should be based on a minimal purpose-built image, with the database and the complementary web applications executing in their own separate containers.

1.1 Installing Docker

If Docker isn’t installed on your computer you can find instructions here. The Community Edition (CE) is sufficient to run a Connect2id server.

1.2 Content of the Docker image

The provided demo image includes the required Java runtime and an exploded copy of the ZIP package that is available for download – a Tomcat servlet container with a Connect2id server WAR, an OpenID relying party and several other sample WARs deployed in it. A relational database (H2 in embedded mode) for the Connect2id server to persist its own data is also included.

1.3 Configuring the Connect2id server

The Connect2id server configuration is located in a set of properties files in the /WEB-INF/ directory of its web application archive (WAR).

Individual configuration properties can be overridden by injecting a text file with the desired values into the Docker container at /etc/c2id/override.properties. The injection can be done by means of a volume, bind mount or a custom storage driver. The steps below use the bind mount method.

Alternative configuration methods, for example via environment variable, are also available.

1.4 To run a container

Important: The provided Docker image uses host networking, which has no isolation between host and container and is limited to Linux hosts.

The steps to run the Connect2id server in a Docker container:

  1. Pull the latest image from Docker Hub

    The available versions are listed in the c2id Docker repository.

    docker pull c2id/c2id-server-demo:[version]

  2. (Optional) Save your custom properties in a override.properties file

    For example:

    op.issuer                   = https://my.idp.com
op.authz.endpoint           = https://my.idp.com/login
op.authz.apiAccessToken     = vuxiehaiGhohrahJeik0ui0aib9jai9c
op.reg.apiAccessToken       = Oosoje7choh1dom8ahng4kueQuoo6la0
op.logout.apiAccessToken    = eik1Oosahpaic5dei2ioco4og9rahkee
authzStore.apiAccessToken   = Ahrek9shie3Eidaex9lu4biem7ahpeeb
sessionStore.apiAccessToken = foo7ahM5koo9eiziah7ahwaequaek5ta
monitor.apiAccessToken      = caew6jaeX2phah8oolaoghaec0Heer8l
jose.jwkSet                 = eyAia2V5cyIgOiBbIHsgImt0eSIgOi...

  3. Run a container with the Connect2id server image

    Replace host_port with an available port on your host.

    • To use the default server setting and embedded H2 database:

      docker run -p [host_port]:8080 c2id/c2id-server-demo:[version]

    • To pass your own server settings in override.properties via bind mount:

      docker run -p [host_port]:8080 --mount type=bind,source="/directory/containing/override/file",target=/etc/c2id c2id/c2id-server-demo:[version]

For extra options that may be of use see the Docker run command reference.

2. Sample minimal Docker file

Minimal Docker file where the Connect2id server is the sole web application deployed in Apache Tomcat. The login page and any other complementary web UIs, services and web handlers are to be deployed separately.

Apache Tomcat listens on port 8080 for HTTP and on port 8443 for HTTPS using a self-signed certificate valid for 2 years.

Security note: Docker images must be regularly rebuilt with the most recent stable Java and Tomcat releases, to ensure there are no unpatched security vulnerabilities in the underlying stack. Always use a specific Docker tag. Don’t use general tags like tomcat:10.1-jdk17-temurin, as this does not guarantee the tag will resolve to the most recent stable version!

# Need Java 17 with Tomcat 10.1.x
FROM tomcat:10.1.29-jdk17-temurin-jammy

# Create a Java keystore with a self-signed certificate for HTTPS in it, then
# configure Tomcat for HTTPS with the certificate
RUN <<EOF
KEYSTORE_PASSWORD=$(openssl rand -base64 16)
echo $KEYSTORE_PASSWORD > /usr/local/tomcat/conf/keystore-password.txt
keytool -genkeypair \
    -alias tomcat \
    -keyalg RSA \
    -keysize 2048 \
    -validity 730 \
    -keystore /usr/local/tomcat/conf/keystore.jks \
    -storepass $KEYSTORE_PASSWORD \
    -keypass $KEYSTORE_PASSWORD \
    -dname "CN=localhost"
sed -i '/<!-- A "Connector" using the shared thread pool-->/ i\
<Connector port="8443" \
           protocol="org.apache.coyote.http11.Http11NioProtocol" \
           SSLEnabled="true" \
           maxThreads="150" \
           scheme="https" \
           secure="true" \
           clientAuth="false" \
           sslProtocol="TLS" \
           sslEnabledProtocols="TLSv1.3"> \
    <SSLHostConfig> \
        <Certificate \
            certificateKeystoreFile="/usr/local/tomcat/conf/keystore.jks" \
            certificateKeystorePasswordFile="/usr/local/tomcat/conf/keystore-password.txt" \
            type="RSA" /> \
    </SSLHostConfig> \
</Connector>' \
/usr/local/tomcat/conf/server.xml
EOF

# Add the Connect2id server as the root (/) web application. The application
# is added as a file tree, not as a WAR package, so that configuration files,
# such as WEB-INF/log4j.xml, can be easily modified, and any developed SPI
# plugins, such as an OpenID claims source plugin, can be directly added as
# JARs to the WEB-INF/lib subdirectory.
ADD target/docker-min/ROOT /usr/local/tomcat/webapps/ROOT

# Override the Connect2id server op.issuer to point to the ROOT.war using HTTP.
# For an HTTPS op.issuer using the self-signed Apache Tomcat certificate run
# the Docker image with the following environment variable:
# -e CATALINA_OPTS="$CATALINA_OPTS -Dop.issuer=https://127.0.0.1:8443"
ENV CATALINA_OPTS="$CATALINA_OPTS -Dop.issuer=http://127.0.0.1:8080"

# Direct Connect2id server logging to STDOUT, add more Java system properties
# where needed. Note, Tomcat's own logging still goes to /usr/local/tomcat/logs
ENV CATALINA_OPTS="$CATALINA_OPTS -Dlog4j.loggers.root.appender=console"

# Tomcat binds on port 8080 for HTTP and 8443 for HTTPS
EXPOSE 8080
EXPOSE 8443

# Launch Tomcat
CMD ["bash", "/usr/local/tomcat/bin/catalina.sh", "run"]

An image built with this Dockerfile can be checked out at

https://hub.docker.com/r/c2id/c2id-server-min/tags

3. Database connectivity

Make sure the database parameters in the Connect2id server configuration are set correctly so that the server can connect via TCP/IP to the intended database for persisting its objects.

An occasional mistake with Docker host networking where the database is also deployed on the same host is trying to connect to localhost, which resolves to the container with the Connect2id server itself.

In some cases the Docker container environment may require an additional setup.

4. Logging

The Connect2id server ships with a configuration for writing the log messages to tomcat/logs/c2id-server.log. When running the server in a Docker container it may be more useful to write the logs to the standard output, which can then be monitored with docker logs or other tools.

To write the logs to the standard output, replace the Connect2id server WEB-INF/log4j.xml configuration with this one.

4.1 AWS CloudWatch

Connect2id server deployments in AWS Elastic Container Service (ECS) can have their logs collected in AWS CloudWatch.

  • First, make sure the server is configured to write the logs to the standard output, as explained above.

  • In the AWS CloudWatch console, create a new log group with a suitable name, e.g. c2id-docker (Log groups → Actions → Create log group).

  • In the AWS ECS console, set the definition for your Connect2id server Docker container to use the log driver awslogs, and then its parameters to point to the desired log group, e.g.

    • awslogs-group = c2id-docker (the CloudWatch log group name)
    • awslogs-region = eu-central (the region of the CloudWatch log group)

5. How to modify the Connect2id server WAR

The Connect2id server WAR package is a ZIP file. It can be modified before packaging the Docker image.

5.1 Remove a file

How to remove an included SPI plugin and its configuration file(s) from the WAR file:

zip -d c2id.war WEB-INF/lib/webapps/c2id/WEB-INF/lib/oidc-claims-source-ldap-1.6.1.jar WEB-INF/ldapClaimsSource.properties WEB-INF/ldapClaimsMap.json

With wildcard for the JAR version number:

zip -d c2id.war WEB-INF/lib/oidc-claims-source-ldap-*.jar WEB-INF/ldapClaimsSource.properties WEB-INF/ldapClaimsMap.json

5.2 Add or replace a file

The Unix zip utility adds files relative to the current working directory.

How to add an SPI plugin to the WAR file (note, its path must be recreated before the zip utility is invoked):

mkdir -p WEB-INF/lib
cp my-plugin.jar WEB-INF/lib/
zip c2id.war WEB-INF/lib/my-plugin.jar