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 properties retrieved from a
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.