% secrets-config-proxy(1) User Manuals secrets-config-proxy(1)

NAME

secrets-config-proxy – Configure EdgeX API gateway service

SYNOPSIS

secrets-config proxy SUBCOMMAND [OPTIONS]

DESCRIPTION

Configures the EdgeX API gateway service.

This command is used to configure the TLS certificate for external connections, create authentication tokens for inbound proxy access, and other related utility functions.

Proxy configuration commands (listed below) require access to the secret store master key in order to generate temporary secret store access credentials.

OPTIONS

--confdir /path/to/directory/with/configuration.toml (optional)

Points to directory containing a configuration.toml file.

SUBCOMMANDS

tls

Configure inbound TLS certificate. This command will provision the TLS secrets into the secret store and re-deploy them to Kong. Requires additional arguments:
- --incert /path/to/certchain (required)
Path to TLS leaf certificate (PEM-encoded x.509) (the file extension is arbitrary). If intermediate certificates are required to chain to a certificate authority, these should also be included. The root certificate authority should not be included.
- --inkey /path/to/private_key (required)
Path to TLS private key (PEM-encoded).
- --snis comma_separated_list_for_server_names (optional)
A comma separated extra server DNS names in addition to the built-in server name indications. The built-in names are "localhost,kong". These names will be associated with the user-provided certificate for Kong's TLS to use. Based on the specification RFC4366: "Currently, the only server names supported are DNS hostnames", so the IP address-based input is not allowed.
adduser

Create an API gateway user using specified token type. Requires additional arguments:
- --token-type jwt (required)
Create user using either the JWT authentication plugin. This value must match the configured authentication plugin (KongAuth.Name in security-proxy-setup's configuration.toml).
- --user username (required)
Username of the user to add.
- --group group (optional)
Group to which the user belongs, defaults to "admin". This should be the group associated with the route ACL (KongAuth.WhiteList in security-proxy-setup's configuration.toml). (Note that secrets-config shares the same configuration as security-proxy-setup as they both configure the EdgeX API gateway.)

The following options are used when token-type == "jwt":
- --algorithm RS256 | ES256 (required for JWT method)
Algorithm used for signing the JWT. (See RFC 7518 for a list of signing algorithms.)
- --public_key /path/to/public_key (required for JWT tokens)
Public key (in PEM format) used to validate the JWT. (Not an x.509 certificate.) This key is assumed to have been pre-created using some external mechanism such as a TPM, HSM, openssl, or other method.
- --id key (optional)
Optional user-specified "key" used for linkage with an incoming JWT via Kong's config.key_claim_name setting (defaults to "iss" field). See Kong documentation for JWT plugin for an example of how this parameter is used.

Upon completion, for token-type == "jwt", the command outputs the autogenerated key for the id command above. This value must be used during later construction of the JWT.
deluser

Delete a API gateway user. Requires additional arguments:
- --user username (required)
Username of the user to delete.
jwt

Utility function to create a JWT proxy authentication token from a supplied secret. This command does not require secret store access, but the values supplied must match those presented to the adduser command earlier. Requires additional arguments:
- --algorithm RS256 | ES256 (required)
Algorithm used for signing the JWT. (See RFC 7518 for a list of signing algorithms.)
- --id key (required)
The "key" field from the "adduser" command. (This will be either the --id argument passed in, or the automatically generated identifier.) (This is not actually a cryptographic key, but a unique identifier such as would be used in a database.)
- --private_key /path/to/private.key (required)
Private key used to sign the JWT (PEM-encoded) with a key type corresponding to the above-supplied algorithm.
- --exp duration (optional)
Duration of generated JWT expressed as a golang-parseable duration value. Use "never" to omit an expiration field in the JWT. Defaults to "1h" (one hour) if unspecified.

The generated JWT will be the encoded representation of:
```
  {
    "typ": "JWT",
    "alg": "RS256 | ES256"
  }
  {
    "iss": "key",
    "exp": (calculated expiration time)
  }
  (signature)
  
```

CONFIGURATION

ENVIRONMENT

IKM_HOOK

Enables decryption of an encrypted secret store master key by pointing at an executable that returns an encryption seed that is formatted as a hex-encoded (typically 32-byte) string to its stdout. This optional feature, if enabled, requires pointing at the same executable that was used by security-secretstore-setup to provision and unlock the EdgeX the secret store.