Import and Export Configurations

Import and Export Configurations

On this page

There are several ways to manage configurations in the Curity Identity Server. This article outlines different options to import and export configurations. It exemplifies how to use configuration snippets that can be imported and merged with the running configuration of an instance.

Example Configuration

Working example configurations for different versions of the Curity Identity Server are available through the Developer Portal.

Import

Importing a configuration, complete or partial, is very straightforward using the Admin UI. Simply navigate to Changes Upload, then select or drag & drop a file to the Upload Configuration area.

Merge or Replace

When importing a configuration, using the Admin UI, CLI or RESTCONF, it is possible to either fully replace the existing configuration or merging what's being imported with the current configuration.

Merge

Merging a configuration that is uploaded will combine the currently running configuration with the one being imported. This is a very useful option if, for example, a complete client configuration or an authenticator configuration is held in its own separate configuration file.

Replace

Choosing to replace the configuration will fully overwrite the configuration in place with the one held in the file selected for import. The option is straight forward. However, take into account that replacing the full configuration may change the running configuration and have immediate effect on the accessibility of the Admin UI.

This option also allows for parts of the configuration to be deleted. Deleting parts of the configuration is not possible when merging the configuration.

Configuration will be replaced

Using this option to import the configuration will replace the existing configuration and typically only make sense when being replaced with a complete configuration and not a partial configuration.


Export

Both the full configuration of a system or a partial configuration can be exported using various methods.

Admin UICLIIDSVRRESTCONF

Full Configuration

To export the full configuration, navigate to Changes Download. This will download the full configuration as a file with the name curity-config.xml.

Export Config

Partial Configuration

It is possible to download a partial configuration throughout the AdminUI. Below is an example of an Authenticator configuration. Note the Download as XML button that will download only the specific configuration in view (the Authenticator).

For some views in the AdminUI this option is accessible via the 3-dot menu.

The format of the configuration export using the CLI can vary. However, the system in many cases expects XML and therefore this is the recommended format.

Full Configuration

Example commands to export the full configuration as XML to a file with the name backup.xml:

/backup.xml
123
idsh
show configuration | display xml | save ./backup.xml
exit

Partial Configuration

It is also possible to export only a part of the configuration using the CLI. Example commands to export the configuration of an authenticator (MyWebAuthnAuthenticator):

/my_webauthn_authenticator_config.xml
123
idsh
show configuration profiles profile authentication-service authentication-service settings authentication-service authenticators authenticator MyWebAuthnAuthenticator | display xml | save ./my_webauthn_authenticator_config.xml
exit

The idsvr binary can be used to export the full configuration as well as a partial configuration.

Full Configuration

To export the full configuration to a file named backup.xml:

sh
1
idsvr --dump-config >> backup.xml

Partial Configuration

A <CONFIG_PATH> can be used with the --dump-config parameter to export a partial configuration. The following command provides a <CONFIG_PATH> to export only the MyWebAuthnAuthenticator authenticator config:

sh
1
idsvr --dump-config "/profiles/profile{authentication-service auth:authentication-service}/settings/auth:authentication-service/authenticators/authenticator{MyWebAuthnAuthenticator}/webauthn:webauthn" >> my_webauthn_authenticator_config.xml

The below command shows how idsh can be used to determine what the <CONFIG_PATH> for a given part of the configuration is:

sh
1
./idsh <<< "show configuration profiles profile authentication-service authentication-service settings authentication-service authenticators authenticator webauthn | display keypath" | head -n 1

Full Configuration

The full configuration of a running system can be exported using the RESTCONF API with the following GET request. This downloads the config to a file with the name complete-config.xml.

sh
12345
curl --request GET \
--url 'https://localhost:6749/admin/api/restconf/data?content=config' \
--output complete-config.xml \
--header 'Authorization: Bearer _0XBPWQQ_ccd1bc8f-9631-43ce-9a32-0439a5e3a9ab' \
--header 'Content-Type: application/yang-data+xml'

Partial Configuration

A partial configuration can be downloaded through a GET request to the specific configuration path. Review the Introduction to the RESTCONF Admin API recording to learn how to determine the path for a given resource.

sh
12345
curl --request GET \
--url 'https://localhost:6749/admin/api/restconf/data/base:profiles/base:profile=token-service,oauth-service/base:settings/profile-oauth:authorization-server/profile-oauth:client-store/profile-oauth:config-backed/profile-oauth:client=my-client' \
--output client-config.xml \
--header 'Authorization: Bearer _0XBPWQQ_1deb9b87-347b-4323-9bca-e1597174b8c7' \
--header 'Content-Type: application/yang-data+xml'

Commit Hooks

It is possible to leverage Commit Hooks to execute scripts when a configuration is committed using the CLI. This could for example be used to push the configuration to an alternative storage at every commit.

Helm Backup Config

When deploying using the Curity Helm Chart, it is possible to set a configuration flag so that the configuration is written to a Secret when committed.

Load on First Startup

The Curity Identity Server has the capability to load configuration at startup. Configurations placed in $IDSVR_HOME/etc/init will load the first time the server starts. For a more streamlined configuration management, the configuration placed here can be broken up into separate files if needed. When multiple files are used, they will be merged together and not replaced to overwrite each other.

It is possible to trigger the configuration to be read (in addition to first startup) by running idsvr --force-reload when the server is running. This will replace the currently loaded configuration with the configuration that is in $IDSVR_HOME/etc/init.

In addition, idsvr --reload can be used to merge the configuration that is in $IDSVR_HOME/etc/init with the configuration the server is currently using.

Parameterized configuration

When loading configuration through $IDSVR_HOME/etc/init it is possible to make use of parameters in the configuration. This is very useful to maintain the same configuration across different environments where the parameter loads different values. The value that replaces the parameter in the configuration can be picked up either from a properties file, $IDSVR_HOME/etc/init/startup.properties, or from an ENV variable of the system.

A part of the configuration could look like this:

xml
1
<base-url>https://idsvr-dev.example.com</base-url>

Leveraging a parameter, it could be changed to:

xml
1
<base-url>https://idsvr-#{CURITY_ENVIRONMENT}.example.com</base-url>

It is also possible to set a parameter in the configuration coupled with a default value that is used if the parameter has not been set. In the example below, DEV will be the default value if CURITY_ENVIRONMENT is not set.

xml
1
<base-url>https://idsvr-#{CURITY_ENVIRONMENT | DEV}.example.com</base-url>

Exporting config with parameters

As described above in the Export section, idsvr can be used to export the full configuration or a partial configuration. When using the --dump-config flag the configuration (or partial configuration if a CONFIG_PATH is provided) is exported with the actual values that was picked up when the configuration was imported. It is also possible to export the parameters by instead using the --dump-config-with-params flag.

Refer to the Parameterized XML Configuration of the product documentation for further details.


Encryption and Crypto

Parts of the configuration can be encrypted, and by default a known key is used. For each deployed system, you should replace this, by setting a unique CONFIG_ENCRYPTION_KEY as an environment variable. More details in the Encrypted Configuration section of the product documentation. Other unique crypto keys for each deployment of the Curity Identity Server also needs to be configured.

For more on these topics, see the GitOps configuration management tutorial.

Summary

The Curity Identity Server supports several ways of exporting and importing complete or partial configurations. The different alternatives available should be able to cater for many different scenarios.