secrets-config

README

% 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 | oauth2 (required)

    Create user using either the JWT or OAuth2 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.

  The following options are used when token-type == "oauth2":

  • --client_id (optional)

    Optional manually-specified OAuth2 client_id. Will be generated if not present. Equivalent to a username.

  • --client_secret (optional)

    Optional manually-specified OAuth2 client_secret. Will be generated if not present. Equivalent to a password.

  • --redirect_uris url_for_browser_redirection (optional)

    OAuth2 redirect URL for browser-based users. Defaults to "https://localhost". This is not currently used by EdgeX but the API gateway requires a value.

  Upon completion, for token-type == "oauth2", the command outputs a JSON structure containing the client_id and client_secret.

• 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)
    

• oauth2

  Utility function to create an OAuth2 proxy authentication token using the client_credentials OAuth2 grant flow. This command does not require secret store access, but the values supplied must match those presented to the adduser command earlier. Requires additional arguments:

  • --client_id client_id (required)

    OAuth2 client_id from previous "adduser" command. Equivalent to a username.

  • --client_secret client_secret (required)

    OAuth2 client_secret from previous "adduser" command. Equivalent to a password.

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.

SEE ALSO

secrets-config(1)

EdgeX Foundry Last change: 2020