Skip to content

Latest commit

 

History

History
152 lines (109 loc) · 8.62 KB

README.md

File metadata and controls

152 lines (109 loc) · 8.62 KB
Raw

LowkeyVault

GitHub license Java version latest-release Docker Hub JavaCI codecov badge-abort-mission-armed-green

Lowkey Vault - App

This is the root of the Java app. Visit the Readme in the repo root for more information about the project in general.

Startup parameters

Log requests

In order to support debugging integration, Lowkey Vault can log request data. To turn on this feature, you must pass --LOWKEY_DEBUG_REQUEST_LOG=true as startup argument:

java -jar lowkey-vault-app-<version>.jar --LOWKEY_DEBUG_REQUEST_LOG=true

Non-default vaults

In case you wish to use more than one vaults, you should consider registering additional vaults using the --LOWKEY_VAULT_NAMES=<name1>,<name2> comma separated format. This will register the https://<name1>.localhost:<server.port> and https://<name2>.localhost:<server.port> vaults in the aforementioned example. You can pass any number of vault prefixes as long as you have enough RAM:

java -jar lowkey-vault-app-<version>.jar --LOWKEY_VAULT_NAMES=name1,name2

A handful of vaults are available by default. These are configured here.

The example above would register the following vaults as it can be seen in the logs as well:

Creating vault for URI: https://127.0.0.1:8443
Creating vault for URI: https://localhost:8443
Creating vault for URI: https://default.lowkey-vault:8443
Creating vault for URI: https://default.lowkey-vault.local:8443
Creating vault for URI: https://name1.localhost:8443
Creating vault for URI: https://name2.localhost:8443

If you wish to turn off the automatic vault registration feature, simply pass --LOWKEY_VAULT_NAMES=-:

java -jar lowkey-vault-app-<version>.jar --LOWKEY_VAULT_NAMES=-

Defining vault aliases for auto-registered vaults

Since v1.13.0

If you are using the automatically registered vaults, you can add aliases to them by using the --LOWKEY_VAULT_ALIASES argument.

  1. This argument is containing the comma (,) separated list of pairs.
  2. Each pair should
    1. start with the host name of an auto-registered vault without the port suffix
    2. then contain an equals sign (=)
    3. then define the host authority of the alias vault in one of the following formats
      1. hostname (e.g. localhost), meaning that we want to register an alias to the :443 port of the host defined in the hostname part
      2. hostname:port (e.g. localhost:8443) meaning, that we want to register an alias to exactly that host and port, which is defined
      3. hostname:<port> (e.g. localhost:<port>) meaning that we want to register an alias to the host defined in the hostname using the port set with --server.port
java -jar lowkey-vault-app-<version>.jar --LOWKEY_VAULT_NAMES="name1" --LOWKEY_VAULT_ALIASES="name1.localhost=alias.localhost,localhost=example:<port>"

This command will result in the following aliases as seen in the logs:

Updating aliases of: https://name1.localhost:8443 , adding: https://alias.localhost, removing: null
Updating aliases of: https://localhost:8443 , adding: https://example:8443, removing: null

Custom port use

In order to avoid using the reserved 8443 port, we need to tell Lowkey Vault to use a different one instead. Set --server.port=<port> as an argument as usual with Spring Boot apps:

java -jar lowkey-vault-app-<version>.jar --server.port=8443

Overriding the challenge resource URI

The official Azure Key Vault clients verify the challenge resource URL returned by the server (see blog). You can either set DisableChallengeResourceVerification=true in your client, or you can configure the resource URL returned by the Lowkey Vault:

java -jar lowkey-vault-app-<version>.jar --LOWKEY_AUTH_RESOURCE="vault.azure.net"

Note

You should be running Lowkey Vault with a resolvable hostname as a subdomain of vault.azure.net (e.g. lowkey.vault.azure.net) and have appropriate SSL certificates registered if you choose to configure the auth resource.

Warning

This property is only intended to be used in case you absolutely cannot disable your challenge resource verification because it raises the complexity of your setup significantly and there are no guarantees that the clients will keep working with this workaround. Therefore, this is NOT recommended to be used. Please consider following the official guidance instead.

Using the Token endpoint with a custom realm

By default, the Token endpoint includes the WWW-Authenticate response header with the Basic realm=assumed-identity value. If you need to change the realm (for example because you are using Managed Identity authentication with the latest Python libraries) you can use the LOWKEY_TOKEN_REALM configuration property to override it as seen in the example below:

java -jar lowkey-vault-app-<version>.jar --LOWKEY_TOKEN_REALM="local"

Using the configuration above, the value of the response header would change to Basic realm=local.

Importing vault content at startup

When you need to automatically import the contents of the vaults form a previously created JSON export, you can use a few parameters to customise the way import is happening.

Property Default Description
LOWKEY_IMPORT_LOCATION <null> The JSON file we want to import. If left on default, or the file cannot be read, the import will not happen.
LOWKEY_IMPORT_TEMPLATE_HOST localhost The host name we want to use for replacing {{host}} placeholders in the JSON export (if there are any).
LOWKEY_IMPORT_TEMPLATE_PORT <server.port> The port number we want to use for replacing {{port}} placeholders in the JSON export (if there are any).

Similarly to how LOWKEY_IMPORT_TEMPLATE_HOST and LOWKEY_IMPORT_TEMPLATE_PORT are replacing placeholders, we can use {{now <seconds>}} placeholders (with positive or negative values as well) which will be replaced with the <UTC_Epoch_seconds_now> + <seconds> formula. This can allow you to use relative timestamps, in case your tests need a key of certain age relative to the time of the test execution.

Example:

java -jar lowkey-vault-app-<version>.jar --LOWKEY_IMPORT_LOCATION=export.json --LOWKEY_IMPORT_TEMPLATE_HOST=127.0.0.1 --LOWKEY_IMPORT_TEMPLATE_PORT=443

External configuration

Since Lowkey Vault is a Spring Boot application, the default mechanism for Spring Boot external configuration can work as well. For example, if there is a ./config/application.properties file relative to the folder where you are running Lowkey Vault, the contents will be picked up automatically. For more information please see the Spring Boot documentation.