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

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"

2. 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

3. 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.

4. 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.