User Manual - ZTrust V1.0
Last updated
Last updated
A study by SecureAuth revealed that 53% of individuals utilize identical passwords across various accounts. In these kinds of scenarios, if an unauthorized party gains access to one account, they can potentially exploit the same password to access the user's other accounts. Employing Single Sign-On (SSO) alongside Multi-Factor Authentication (MFA) can effectively safeguard user accounts and their associated data in such situations.
ZTrust offers integrated Identity and Access Management across various channels, streamlining the user login process. With a single click, users can navigate seamlessly between different applications, without the need to log in separately to each one.
It provides Role Based Access Control (RBAC), Multi-Factor Authentication (MFA), Advanced Password Management, and Brute Force Detection capabilities.
Additionally, it includes features to track or monitor inactive users, password invalidation, real-time data synchronization, and many more.
Refer to the documentation - User Manual - Key Terminologies
Refer to User Manual - Guide to Navigation for more details
This section provides instructions on installing ZTrust.
Before starting, ensure that Docker is installed on your system and that you have a Docker image of ZTrust.
To initiate ZTrust, execute the following command in your terminal:
docker run -p 8080:8080 -e ZTRUST_ADMIN=admin -e ZTRUST_ADMIN_PASSWORD=admin quay.io/ztrust/ztrust:25.0.0 start-dev
This command launches ZTrust, accessible on local port 8080, and establishes an initial admin user with the username "admin" and password "admin".
Go to the ZTrust Administration Console
Login to ZTrust using the credentials that you created earlier.
In Ztrust, a realm is similar to a tenant. This allows the administrator to establish isolated groups of applications and users. These groups are segregated from each other. The users within one realm can not access the details of users in another realm.
For additional information regarding the creation of Realms and the necessary steps, please refer to : Creation of a Realm
Initially the realm won’t have any users.
For further information and instructions on user creation, please refer to : Creation of a user
You can proceed to log in to the Account Console to confirm that this user has been configured correctly.
For additional details and guidance on accessing the Account Console, you can refer to Login to Account Console.
To secure your initial application, begin by registering it with your ZTrust instance:
Open the ZTrust Admin Console.
Navigate to Demo by clicking on master and selecting Demo.
Proceed to Clients and click on Create.
Complete the form with the specified values:
Client ID: demo
Client Protocol : OpenID Connect
After entering the above details, click Save.
Upon clicking Save, you will be redirected to the following screen.
Ensure that the Standard flow is activated and scroll down.
Set Valid redirect URIs to https://sso.ztrust.in
Enter Web origins as - https://sso.ztrust.in
Click on Save.
On following the above steps, the client would be created successfully.
This section outlines the procedure for configuring ZTrust and implementing the necessary configurations. It contains guidelines for configuring ZTrust to optimize its startup speed.
ZTrust retrieves its configuration from four different origins, which follow the below sequence:
Command-line parameters
Environment variables
Settings specified in the conf/ztrust.conf file or a custom configuration file
Confidential settings outlined in a user-generated Java KeyStore file.
If an option is configured in multiple sources, the value from the source higher in the list takes precedence in determining the value for that option.
The given example illustrates how the value for db-url is configured across four different configuration sources:
Command line parameters
--db-url=cliValue
Environment variables
KC_DB_URL=envVarValue
Configuration file
db-url=confFileValue
Java KeyStore file
kc.db-url=keystoreValue
According to the order of priority, the value utilized during startup is cliValue, as command-line parameters take precedence over other sources.
If --db-url=cliValue hadn't been specified, the value applied would be KC_DB_URL=envVarValue, given that environment variables come next in priority. In the absence of values from the command line or environment variables, db-url=confFileValue from the configuration file would be used. Should none of the prior values be present, kc.db-url=confFileValue would be utilized as it holds the lowest priority among the available configuration sources.
The configuration employs a consistent format for each source, which facilitates the conversion of a key/value pair from one configuration source to another.
It's important to note that these formats are also applicable to spi options.
The format for configuring values differs based on the source:
Command-line parameter format
Command-line values follow the --<key-with-dashes>=<value> pattern, and some have a shorthand -<abbreviation>=<value> option.
Environment variable format
Environment variables are in uppercase and follow the format KC_<key_with_underscores>=<value>.
Configuration file format
Configuration file values follow the <key-with-dashes>=<value> structure.
KeyStore configuration file format
KeyStore configuration file values use the kc.<key-with-dashes> format, with the <value> being a password stored in the KeyStore.
At the end of each configuration guide, look for the Relevant options heading, which defines the applicable configuration formats. For all configuration options, see All configuration.
Choose the configuration source and format that applies to your use case.
Below is an example demonstrating the configuration format for db-url-host across three different configuration sources:
command-line parameter
bin/kc.[sh|bat] start --db-url-host=myztrustdb
environment variable
export KC_DB_URL_HOST=myztrustdb
conf/ztrust.conf
db-url-host=myztrustdb
ZTrust is packed with many command line parameters for configuration. To explore the available configuration formats, simply run the following command:
bin/kc.[sh|bat] start --help
Alternatively, you can refer to All configuration for a comprehensive list of all server options.
In the ztrust.conf file, you can utilize placeholders to retrieve environment-specific values from environment variables using the ${ENV_VAR} syntax, like so:
db-url-host=${MY_DB_HOST}
If the environment variable cannot be resolved, you have the option to specify a fallback value. This is achieved by appending a : (colon) followed by the mydb, such as:
db-url-host=${MY_DB_HOST:mydb}
By default, the server retrieves configuration options from the conf/ztrust.conf file. In a fresh installation, this file contains only commented settings as a reference for configuring the system for production use.
Alternatively, you can specify a specific configuration file location using the [-cf|--config-file] option. Here's how you can do it:
bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start
When this option is set, ZTrust will read configuration from the specified file instead of conf/ztrust.conf.
With the Keystore Configuration Source, you have the ability to directly retrieve properties from a Java KeyStore using the [--config-keystore] and [--config-keystore-password] options.
Optionally, you can specify the KeyStore type using the [--config-keystore-type] option, which defaults to PKCS12.
To store secrets in a KeyStore, you need to use the password-based encryption (PBE) key algorithm, where a key is derived from a KeyStore password.
You can generate such a KeyStore using the following keytool command:
keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v
After executing this command, you will be prompted to enter the password to be stored, representing the value of the kc.db-password property mentioned above.
Once the KeyStore is created, you can start the server using the following parameters:
bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=storepass --config-keystore-type=PKCS12
In general, the configuration options provided by ZTrust should cover most server configuration needs. However, if you encounter a specific behavior or capability that is not available in the ZTrust configuration, you have the option to utilize properties from the underlying Quarkus framework.
It's recommended to avoid directly using properties from Quarkus whenever possible, as they are not officially supported by ZTrust. If you find it necessary to use Quarkus properties, consider opening an enhancement request first. This allows us to potentially improve ZTrust’s configuration to better meet your requirements.
If you're unable to make an enhancement request, you can configure the server using raw Quarkus properties by following these steps:
Create a quarkus.properties file in the conf directory.
Define the required properties in that file.
You can only utilize a subset of the Quarkus extensions defined in the Quarkus documentation.
Properties with a lock icon in the Quarkus documentation signify build-time properties. You need to run the build command to apply these properties.
Refer to the subsequent sections on optimizing ZTrust for details about the build command.
Properties without a lock icon in the Quarkus guide indicate runtime properties for both Quarkus and ZTrust.
To include the quarkus.properties file, use the [-cf|--config-file] command-line parameter.
Similarly, you can store Quarkus properties in a Java KeyStore.
ZTrust relies on Quarkus and MicroProfile for processing configuration values, supporting value expressions such as ${some_key}, which evaluates to the value of some_key.
To disable expression evaluation, the \ character serves as an escape character. It must be used to escape the usage of $ characters when they appear to define an expression or are repeated. For example, if you want the configuration value my$$password, you should use my\$\$password instead.
It's important to note that the \ character requires additional escaping or quoting when used in most Unix shells or when it appears in properties files. For example, in bash single quotes preserve the single backslash --db-password='my\$\$password'.
In bash double quotes, an additional backslash is needed --db-password="my\\$\\$password".
Similarly, in a properties file, backslash characters must also be escaped: kc.db-password=my\\$\\$password.
ZTrust can be launched in either development mode or production mode, with each mode featuring distinct defaults tailored to its respective environment.
Development mode in ZTrust is designed for quick setup and experimentation, ideal for those trying out ZTrust for the first time or developing new themes.
To start ZTrust in development mode, use the command:
bin/kc.[sh|bat] start-dev
In development mode, the following default configurations are set:
HTTP is enabled
Strict hostname resolution is disabled
Cache is set to local (no distributed cache mechanism used for high availability)
Theme-caching and template-caching are disabled
Production mode in ZTrust is intended for deployments in production environments, adhering to a secure by default principle.
To start ZTrust in production mode, use the command:
bin/kc.[sh|bat] start
Without additional configuration, this command will not start ZTrust and instead display an error.
This intentional response is to ensure security, as ZTrust expects certain configurations to be in place for production deployment, such as a configured hostname and HTTPS/TLS setup.
In production mode, the following defaults are set:
HTTP is disabled as HTTPS (transport layer security) is essential.
Hostname configuration is expected.
HTTPS/TLS configuration is expected.
By default, example configuration options for production mode are commented out in the default conf/ztrust.conf file. These options provide guidance on the main configurations to consider when running ZTrust in production.
Instead of creating the initial admin user through the web frontend accessed via a local connection (localhost), you have the option to create this user using environment variables.
Set ZTRUST_ADMIN=<username> to specify the initial admin username and ZTRUST_ADMIN_PASSWORD=<password> to set the initial admin password.
ZTrust will parse these values during the first startup to create an initial user with administrative rights. Once the initial administrator is created, you can use either the Admin Console or the command-line tool kcadm.[sh|bat] to create additional users.
If the initial administrator already exists and the environment variables are still present at startup, an error message indicating the failed creation of the initial administrator will be logged. However, ZTrust will ignore these values and start up correctly.
Before deploying ZTrust in a production environment, it's advisable to optimize it for faster startup and improved memory consumption. This section outlines the steps to apply optimizations to ZTrust for optimal performance and runtime behavior.
By default, when utilizing the start or start-dev command, ZTrust executes a build command internally for convenience purposes.
This build command executes a series of optimizations aimed at improving startup and runtime behavior. The build process typically takes a few seconds.
In containerized environments like Kubernetes or OpenShift, startup time is crucial. To avoid potential delays during startup, it's recommended to run the build explicitly before starting up ZTrust, for instance, as a separate step in a CI/CD pipeline.
2.4.16.1. First step: Run a build explicitly
To execute a build, use the following command:
bin/kc.[sh|bat] build <build-options>
This command displays the build options you provide. ZTrust makes a distinction between build options, which are applicable when running the build command, and configuration options, which are applicable when starting up the server.
During a non-optimized startup of ZTrust, this distinction doesn't have any effect.
However, if you run a build before starting up the server, only a subset of options is available to the build command. This restriction is because the build options are persisted into an optimized ZTrust image. For instance, configuration for credentials like db-password (which is a configuration option) must not be persisted for security reasons.
Build options are indicated in All configuration with a tool icon. To discover the available build options, you can refer to the All configuration page with build options selected, or alternatively, execute the following command:
bin/kc.[sh|bat] build --help
For instance, to set the database to PostgreSQL before startup, you can run a build with the following example command:
bin/kc.[sh|bat] build --db=postgres
2.4.16.2. Second step: Start ZTrust using --optimized
After a successful build, you can initiate ZTrust and deactivate the default startup behavior by executing the following command:
bin/kc.[sh|bat] start --optimized <configuration-options>
The --optimized parameter instructs ZTrust to assume that a pre-built, already optimized ZTrust image is being used. Consequently, ZTrust skips the check for and execution of a build directly at startup, saving time.
You can specify all configuration options at startup, excluding those marked with a tool icon in All configuration.
If a build option is detected at startup with a value identical to the value used during the build, that option is quietly disregarded when using the --optimized parameter.
However, if the option has a different value than the one used during the build, a warning is logged, and the previously built value is utilized. To implement this new value, perform a new build before starting.
Create an optimized build
Here's an example demonstrating the creation of an optimized build followed by starting ZTrust with the --optimized parameter:
Set the build option for the PostgreSQL database vendor using the build command:
bin/kc.[sh|bat] build --db=postgres
Set the runtime configuration options for PostgreSQL in the conf/ztrust.conf file:
db-url-host=ztrust-postgres
db-username=ztrust
db-password=change_me
hostname=myztrust.acme.com
https-certificate-file
Start the server with the optimized parameter:
bin/kc.[sh|bat] start --optimized
The build command allows you to implement many optimizations to startup and runtime behavior. Additionally, by utilizing the ztrust.conf file as a configuration source, certain steps that would typically require command-line parameters, such as initializing the CLI, are avoided during startup. This streamlining results in even faster server startup times.
This section provides an overview of the underlying concepts utilized by ZTrust, particularly focusing on optimizing startup.
ZTrust employs the Quarkus framework and adopts a re-augmentation/mutable-jar approach behind the scenes. This process initiates when a build command is executed.
Here are some optimizations carried out by the build command:
A new closed-world assumption about installed providers is established, eliminating the need to recreate the registry and initialize the factories at every ZTrust startup.
Configuration files are pre-parsed to reduce I/O when starting the server.
Database-specific resources are configured and prepared to operate with a particular database vendor.
By persisting build options into the server image, the server avoids additional steps to interpret configuration options and reconfigure itself.
For further details, refer to the specific Quarkus guide.
Refer to the documentation - User Manual - Admin Manual
For any inquiries or assistance needed, please contact us at contact@ztrust.in.
