Import and Export Configurations

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.

Import

idsh
configure
load merge ./my-config.xml
commit
exit
exit

idsvr --load-config backup.xml

curl -k --request PUT \ 
  --url 'https://localhost:6749/admin/api/restconf/data' \
  --header 'Authorization: Bearer _0XBPWQQ_48025ef1-b9b1-4b90-a590-6db51c330671' \
  --header 'Content-Type: application/yang-data+xml' \
  --data @example-config.xml

curl --request POST \
  --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' \
  --header 'Authorization: Bearer _0XBPWQQ_1deb9b87-347b-4323-9bca-e1597174b8c7' \
  --header 'Content-Type: application/yang-data+xml' \
  --data @client-config.xml

<client xmlns="https://curity.se/ns/conf/profile/oauth">
  <id>my-client</id>
  <secret>$5$4lzvhAxAUwHG4osE$2vrfdfssj3ZIT3kXrfksdfsfxvv/FhK94i5gmJBLdr8bH5</secret>
  <redirect-uris>https://localhost/callback</redirect-uris>
  <scope>email</scope>
  <user-authentication>
    <allowed-authenticators>Yubikey</allowed-authenticators>
  </user-authentication>
  <capabilities>
    <code/>
  </capabilities>
</client>

curl --request PUT \
  --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' \
  --header 'Authorization: Bearer _0XBPWQQ_1deb9b87-347b-4323-9bca-e1597174b8c7' \
  --header 'Content-Type: application/yang-data+xml' \
  --data '<client
      xmlns="https://curity.se/ns/conf/profile/oauth"
      xmlns:as="https://curity.se/ns/conf/profile/oauth"
      xmlns:base="https://curity.se/ns/conf/base">
      <id>my-client</id>
      <secret>$5$4lzvhAxAUwHG4osE$2vmgyfA8j3ZIT3kXrfkk8xvv/FhK94i5gmJBLdr8bH5</secret>
      <redirect-uris>https://localhost/callback</redirect-uris>
      <redirect-uris>https://localhost/callback-new</redirect-uris>
      <scope>email</scope>
      <user-authentication>
        <allowed-authenticators>Yubikey</allowed-authenticators>
      </user-authentication>
      <capabilities>
        <code></code>
      </capabilities>
    </client>'

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.

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.

Partial Configuration

It is possible to download a partial configuration throughout the Admin UI. 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 Admin UI this option is accessible via the 3-dot menu.

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/startup.properties, or from an ENV variable of the system.

A part of the configuration could look like this:

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

Leveraging a parameter, it could be changed to:

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

<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 Configuration as Code 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.