Skip to content

CLI Authentication

To access and interact with kdb Insights Enterprise, you must authenticate by using the kxi auth login command.

You can authenticate through either user authentication or service account authentication.

  • User Authentication: This approach provides user specific access and requires interaction for authentication. You log in through a browser by accessing the kdb Insights Enterprise user interface.

  • Service Account Authentication: Service accounts are designed for application-specific access and do not require user interaction. This method is well-suited for programmatic, non-interactive tasks, and command-line-based operations. It is commonly used for server-to-server communication.

Authentication exceptions

The following commands are exempt from the authentication described in this section:

  • The install and backup commands interact directly with the Kubernetes cluster. To use these commands, you need Kubernetes access. Ask your system administrator to configure it

  • The user command operates under a separate authentication mechanism. It manages kdb Insights Enterprise users and requires an admin login. For more information, refer to the User Management Authentication section.

Authenticating as a user

To authenticate as a user, execute kxi auth login.

  1. This command automatically opens a web browser.
  2. Complete the login process using your kdb Insights Enterprise user credentials.
  3. After successfully logging in, close the browser tab and return to the command-line.

For example, to authenticate and list packages:

  1. Execute kxi auth login to authenticate:

    kxi auth login

    Authenticating with kdb Insights Enterprise

Successfully authenticated with kdb Insights Enterprise

  2. List packages:

    kxi pm list

    ╭────────────────────────────────────┬─────────┬───────────────────┬──────┬────────┬─────────────────┬──────────────────────────────────────╮
│ name                               │ version │ deployment.status │ data │ access │ owner.name      │ id                                   │
├────────────────────────────────────┼─────────┼───────────────────┼──────┼────────┼─────────────────┼──────────────────────────────────────┤
│ kxi-db                             │ 1.0.0   │ -                 │ yes  │ ARWX   │ user            │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
╰────────────────────────────────────┴─────────┴───────────────────┴──────┴────────┴─────────────────┴──────────────────────────────────────╯

Authentication validity period

After authenticating, the CLI caches a token on your local machine and re-uses it across future commands. By default, this token has a relatively short validity period (5 minutes by default). However, if you are actively using the CLI, the token will be automatically refreshed, ensuring seamless access.

If you leave the CLI idle for an extended period, you will be prompted to login through the browser again. Provided the SSO session cached in the browser hasn't expired, you won't have to re-enter your credentials and it will automatically re-authenticate. This SSO session is 10 hours by default. After this, you will need to re-authenticate.

You can check the token and session settings on your deployment at https://${INSIGHTS_HOSTNAME}/auth/admin/master/console/#/${INSIGHTS_REALM}/realm-settings

Managing users.

Non-local browser flow

When authenticating with user credentials through the CLI without a local browser on the machine, the non-local browser flow provides a seamless and secure method of authentication. Follow these steps to authenticate using the kxi auth login --force-code command:

  1. The command will prompt you with a URL. Open this URL in a remote web browser by either copying and pasting it into your preferred browser or manually navigating to it.
  2. Complete the login process by entering your kdb Insights Enterprise user credentials on the web page.
  3. After successfully logging in, the browser will redirect to a Success page. Copy the provided authorization code from the page.
  4. Return to the CLI prompt and paste the authorization code when prompted.
$ kxi auth login --force-code
Authenticating with kdb Insights Enterprise
To complete the authorization with Insights Enterprise, please open the following URL in your web browser:

https://${INSIGHTS_HOSTNAME}/auth/realms/insights/protocol/openid-connect/auth?redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code&client_id=insights-app

Enter the authorization code you received after visiting the provided URL:

Authenticating as a service account

Before authenticating as a service account, configure the CLI with your service account credentials. This ensures the CLI can seamlessly re-authenticate in the background without causing any disruptions.

The recommended way to do this is to use kxi configure to setup your configuration file with the service account ID and secret.

  1. Configure the CLI:

    kxi configure

    ..
Service account ID []: test-publisher
Service account Secret (input hidden):
Re-enter to confirm (input hidden):
CLI successfully configured, configuration stored in ..

  2. Authenticate using the service account:

    kxi auth login --serviceaccount

    Authenticating with kdb Insights Enterprise

Successfully authenticated with kdb Insights Enterprise
    You can use environment variables to specify service account credentials if necessary

    The following example shows how to do this:

    export KXI_SERVICEACCOUNT_ID=test-publisher
export KXI_SERVICEACCOUNT_SECRET=<SECRET>
kxi auth login --serviceaccount

    Authenticating with kdb Insights Enterprise

Successfully authenticated with kdb Insights Enterprise

  3. List the packages using a cached token for a request:

    kxi pm list

    ╭────────────────────────────────────┬─────────┬───────────────────┬──────┬────────┬─────────────────┬──────────────────────────────────────╮
│ name                               │ version │ deployment.status │ data │ access │ owner.name      │ id                                   │
├────────────────────────────────────┼─────────┼───────────────────┼──────┼────────┼─────────────────┼──────────────────────────────────────┤
│ kxi-db                             │ 1.0.0   │ -                 │ yes  │ ARWX   │ user            │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
╰────────────────────────────────────┴─────────┴───────────────────┴──────┴────────┴─────────────────┴──────────────────────────────────────╯

Managing service accounts.

Unlike user authentication, service accounts cannot be automatically refreshed as they do not have a long-lived session. Hence the service account credentials should be configured, as shown above, to ensure re-authentication can be handled automatically.

Token caching

During the authentication process, the tokens generated are cached and saved by default to the location ~/.insights/credentials. This location can be updated by adding the auth.cache_file variable to the configuration file.

Config profiles

The kxi auth command can make use of profiles to allow you to authenticate with different profiles concurrently.

Use the --profile command to authenticate for a specific profile.

Supporting multiple profiles simplifies the process of querying different environments, providing a convenient way to interact with multiple deployments without needing to re-authenticate.

The example below interacts with two different environments; dev and canary.

In this example, both profiles are configured using kxi configure and used to push packages:

  1. Setup configuration profiles:

    [dev]
hostname = https://dev.kxi.example.com
auth.serviceaccount.id = <ID>
auth.serviceaccount.secret = <SECRET>
..

[canary]
hostname = https://canary.kxi.example.com
auth.serviceaccount.id = <ID>
auth.serviceaccount.secret = <SECRET>
..

  2. Authenticate with each environment:

    kxi --profile dev auth login
kxi --profile canary auth login

  3. View packages on the dev environment:

    kxi --profile dev package remote-list -o table

    ╭────────────────────────────────────┬─────────┬───────────────────┬──────┬────────┬─────────────────┬──────────────────────────────────────╮
│ name                               │ version │ deployment.status │ data │ access │ owner.name      │ id                                   │
├────────────────────────────────────┼─────────┼───────────────────┼──────┼────────┼─────────────────┼──────────────────────────────────────┤
│ kxi-db                             │ 1.0.0   │ -                 │ yes  │ ARWX   │ user            │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
╰────────────────────────────────────┴─────────┴───────────────────┴──────┴────────┴─────────────────┴──────────────────────────────────────╯

  4. Push the insights-demo package using the dev profile:

    kxi --profile dev pm push insights-demo-1.0.0.kxi

    Pushing package insights-demo
Pushed insights-demo (1.0.0)

  5. View packages on the dev environment again:

    kxi --profile dev pm list

    ╭────────────────────────────────────┬─────────┬───────────────────┬──────┬────────┬─────────────────┬──────────────────────────────────────╮
│ name                               │ version │ deployment.status │ data │ access │ owner.name      │ id                                   │
├────────────────────────────────────┼─────────┼───────────────────┼──────┼────────┼─────────────────┼──────────────────────────────────────┤
│ kxi-db                             │ 1.0.0   │ -                 │ yes  │ ARWX   │ user            │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
│ insights-demo                      │ 1.0.0   │ -                 │ yes  │ ARWX   │ user            │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
╰────────────────────────────────────┴─────────┴───────────────────┴──────┴────────┴─────────────────┴──────────────────────────────────────╯

  6. View packages on the canary environment:

    kxi --profile canary pm list

    ╭────────────────────────────────────┬─────────┬───────────────────┬──────┬────────┬─────────────────┬──────────────────────────────────────╮
│ name                               │ version │ deployment.status │ data │ access │ owner.name      │ id                                   │
├────────────────────────────────────┼─────────┼───────────────────┼──────┼────────┼─────────────────┼──────────────────────────────────────┤
│ kxi-db                             │ 1.0.0   │ -                 │ yes  │ ARWX   │ user            │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
╰────────────────────────────────────┴─────────┴───────────────────┴──────┴────────┴─────────────────┴──────────────────────────────────────╯

Printing a token

The CLI automatically caches and uses the auth tokens under the covers of its commands.

If you require the raw token, you can obtain it using kxi auth print-token.

kxi auth print-token

eyJhbGciOiJSU..

If the cached token has expired, the CLI won't return it and will prompt you to re-authenticate.

Deprecated functionality

The authentication approach described by this document supersedes previous implementations. As such previous features have been deprecated.

The kxi auth get-access-token command retrieved and printed service account tokens on-demand. This has been marked as deprecated. If you need a token, please use kxi auth login --serviceaccount and kxi auth print-token instead.

The client.id and client.secret config fields are being deprecated and replaced by auth.serviceaccount.id and auth.serviceaccount.secret.

The --client-id and --client-secret options are deprecated from all CLI commands. Previously commands provided these options to authenticate as part of each command. This is no longer required.

User management authentication

The kxi user command can be used to manage users, assign roles and reset credentials. This command uses a different method of authentication than that provided by the kxi auth login command.

The credentials required are those of the admin user configured when you deployed the system, i.e. the user in the Master realm when you login to https://${INSIGHTS_HOSTNAME}/auth. These should be configured in your configuration file as admin.username and admin.password.

[dev]
hostname = https://dev.kxi.example.com
admin.username = <ADMIN_USERNAME>
admin.password = <ADMIN_PASSWORD>
..

Authentication tokens not cached

This command does not cache tokens and requests one each time it's called. This means it will not appear in ${HOME}/.insights/credentials and will not be returned by the kxi auth print-token command.