Introduction to the CLI

Overview

The Command Line Interface (CLI) shipped with Curity Identity Server is a powerful tool for operational tasks and in particular for configuring the product. When working with the CLI configuration changes are saved in a transaction. In this way an administrator can prepare configuration changes without interfering with other users or manipulating the running state of the system. All changes will be local and personal. The CLI validates the changes before it accepts a commit to the running system. As a result it ensures that the configuration is consistent and does not contain any conflicting settings or similar. Since the CLI is of transactional nature it also supports rollbacks. In case of a misconfiguration the system can be put back into a known working state by reverting a commit. In detail, not only the last commit but a whole series of commits can be reverted. As a result, a certain feature can be configured, tested, and adapted and easily reverted if it does not suit the use-case without having to maintain a snapshot.

Commands

In this article we will introduce three commands:

• show - shows the status of the system or configuration parameters
• set - change CLI settings or a configuration parameter
• details - display the details

For more commands please refer to the Configuration Guide. The guide is part of the documentation on the Curity Developer Portal.

Examples

Show

Show the current configuration that was set for the data-source called test.

admin@curity-node% show facilities data-sources data-source test
jdbc {
    connection-string  "jdbc:sqlserver://;servername=server_name";
    connection-timeout 20000;
    driver             org.hsqldb.jdbc.JDBCDriver;
}

By default, the CLI does not show the default values for a parameter. Therefore it is not possible to determine from the output above in which way the configuration differs from the default value.

Set

The CLI settings can be changed using the set command. To view default values update the show settings and set defaults to true.

admin@curity-node> set show defaults true

If there is a default value defined for a parameter, it will be added as a comment after the actual value.

admin@curity-node% show facilities data-source data-souce test
jdbc {
    connection-string  "jdbc:sqlserver://;servername=server_name";
    connection-timeout 20000; #30000
    driver             org.hsqldb.jdbc.JDBCDriver;
}

Details

The output of the show command from the example above is actually missing some parameters. That is because the show command lists only the parameters that were configured intentionally. To get all the parameters of a configuration including the parameters with default values pipe the output into details.

admin@curity-node% show facilities data-sources data-source test | details
jdbc {
    attribute-query                "SELECT linked_accounts.* FROM linked_accounts JOIN accounts ON accounts.account_id = linked_accounts.account_id WHERE accounts.username = :subject";
    connection-string              "jdbc:sqlserver://;servername=server_name";
    connection-timeout             20000;
    credential-query               "SELECT account_id AS accountId, username AS userName, password FROM accounts WHERE username = :subjectId AND active = 1";
    custom-query-verifies-password false;
    driver                         org.hsqldb.jdbc.JDBCDriver;
    idle-timeout                   600000;
    max-lifetime                   1800000;
    max-pool-size                  20;
    min-idle-pool-size             10;
    password                       "";
    use-for-audit                  false;
    username                       "";
}

Scripts

The Admin UI supports most of the settings and is a good starting point. However, it is not suitable for automated processes whereas the CLI can be integrated into deployment scripts making the process fast and results reproducible.

Simple commands can help a development team to get up and running very fast if the CLI is used in the right context. The following lines are extracted from an actual script. It first updates the base-url of the system, then enables WebFinger for Issuer Discovery of a given service role before it changes the protocol to http on the same.

idsh --noninteractive << EOF
    configure
    set environments environment base-url ${BASE_URL}
    ...
    commit
    exit no-confirm
    exit
EOF
...
idsh --noninteractive << EOF
    configure
    set environments environment services service-role ${name} webfinger
    set environments environment services service-role ${name} protocol http
    commit
    exit no-confirm
    exit
EOF

Check out the script published for OAuth Tools. It runs the commands above to configure a local instance of Curity Identity Server to work with OAuth Tools which is a very convenient tool for testing. With the help of the script local changes can quickly be tested in the cloud without any manual configuration on the Curity Identity Server.