Skip to content
Connect2id

External configuration

Out of the box the Connect2id server c2id.war package has its configuration in Java property and XML files inside the /WEB-INF folder. Keeping the configuration internally, within the WAR, is not recommended however:

  • Configuration edits require the c2id.war file to be repackaged.

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

The Connect2id server therefore provides means for external configuration:

A good configuration strategy is to keep all default settings in the c2id.war package and apply all overriding and sensitive parameters (keys, master tokens, database credentials) at Connect2id server startup.

1. Java system properties

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

One method 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

Java system properties can also be passed via an environment variable, as explained in the next section.

2. Environment variable

As mentioned in the previous section, Java system properties for the Connect2id server configuration can also be passed via an environment variable.

The Apache Tomcat web server reads the CATALINA_OPTS environment variable to set the Java system properties when it starts up.

To set it from the shell use the following pattern:

export CATALINA_OPTS="-DpropName1=value -DpropName2=value -DpropName3=..."

For example:

export CATALINA_OPTS="-Dop.issuer=https://op.example.net -D..."

Alternatively, CATALINA_OPTS can be set by editing tomcat/bin/setenv.sh, for example:

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. Whitespace must be avoided or escaped, for instance make sure there is no whitespace around the = and in lists:

export CATALINA_OPTS="$CATALINA_OPTS -Dop.authz.requestJWSAlgs=HS256,RS256,PS256,ES256"

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

These properties will override any properties set via -D and via the environment variable.

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 object’s URL:

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

Supported S3 URL formats:

  • Virtual host format (since v12.16):

    https://[bucket].s3.[region].amazonaws.com/[key]

  • Virtual host old format:

    https://[bucket].s3-[region].amazonaws.com/[key]

  • Path format:

    https://s3.[region].amazonaws.com/[bucket]/[key]

Example, using the path format:

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

Example, using the path format 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

These properties will override any properties set via -D and via the environment variable.

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

These properties will override any properties set via -D and via the environment variable.

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.