External configuration

The Connect2id server configuration is contained in property and XML files in the /WEB-INF folder of its c2id.war package. This method of configuration however may not always be practical:

• Configuration edits require the WAR to be repackaged.

• The configuration includes sensitive parameters, like keys, master API tokens and database credentials. Depending on how the WAR is distributed and deployed in production, it may be simpler and more secure to not have any secrets stored in it.

To address that the Connect2id server can also be configured externally:

• From Java system properties

• From environment variables

• From properties retrieved from a

  • Local file
  • AWS S3 object
  • AWS DynamoDB item

You can utilise that keep the base settings in the c2id.war and apply all sensitive parameters (keys, master tokens, database credentials) at Connect2id server startup.

1. Java system properties

A configuration property found in the /WEB-INF/*.properties or /WEB-INF/*.xml files can be overridden with a Java system property.

One way to set a Java system property is to pass its name and value with the optional -D command line argument at JVM startup:

-Dop.issuer=https://op.example.net

To do that edit the tomcat/bin/setenv.sh. That script is intended to pass additional parameters to Java at Apache Tomcat startup:

# Override the op.issuer set in c2id.war
export CATALINA_OPTS="$CATALINA_OPTS -Dop.issuer=https://op.example.net"

Caveat: Characters that have a special meaning in the shell, such as & and ;, must be escaped.

2. Environment variables

A shell environment variable can be used to set a Java system property in the tomcat/bin/setenv.sh script. This may be useful if you run the Connect2id server in a Docker container or Kubernetes pod.

# Override the op.issuer set in c2id.war
export CATALINA_OPTS="$CATALINA_OPTS -Dop.issuer=$OP_ISSUER"

Caveat: Characters that have a special meaning in the shell, such as & and ;, must be escaped. Also note that dots are not allowed in environment variable names. You may replace them with an underscore character.

3. Local properties file

The Connect2id server can load Java system properties from a file in the local filesystem. Set a Java system property named systemPropertiesURL to point to the file’s URL:

systemPropertiesURL = file:///[path]

Example:

systemPropertiesURL = file:////etc/c2id/server-credentials.properties

4. AWS S3 object

The Connect2id can load Java system properties from an AWS S3 object. Set a Java system property named systemPropertiesURL to point to the objects’s URL:

systemPropertiesURL = https://[s3-object-location]

Example:

systemPropertiesURL = https://s3-us-west-2.amazonaws.com/loh0uuji/ieg1koik

Example with an optional version ID for the S3 object:

systemPropertiesURL = https://s3-us-west-2.amazonaws.com/loh0uuji/ieg1koik?version=e008d326-6ddc-4ef5-a57b-a08b14c16606

The AWS credentials for accessing the S3 bucket must be configured in way that the default AWS credentials provider chain can look them up, ideally via IAM instance profile roles. See the credentials guide.

5. AWS DynamoDB item

The Connect2id server can load Java system properties from a DynamoDB item attribute. Set a Java system property named systemPropertiesURL to point to the items’s URL:

systemPropertiesURL = dynamodb://[region]/[table]?
  hash_key_name=[key-name]
 &hash_key_value=[key-value]
 &range_key_name=[key-name]
 &range_key_value=[key-value]
 &attribute=[attribute-name]

The query parameters range_key_name and range_key_value are required only when a range key is used for the table.

Alternative format specifying a DynamoDB endpoint instead of region, works also with local DynamoDB instances:

systemPropertiesURL = http+dynamodb://[host-and-port]/[table]?
  hash_key_name=[key-name]
 &hash_key_value=[key-value]
 &range_key_name=[key-name]
 &range_key_value=[key-value]
 &attribute=[attribute-name]

Example where the Java system properties are found in the props string attribute of a DynamoDB item:

dynamodb://us-west-2/config?hash_key_name=tid&hash_key_value=123&attribute=props

The AWS credentials for accessing the DynamoDB table must be configured in way that the default AWS credentials provider chain can look them up, ideally via IAM instance profile roles. See the credentials guide.