NAME
====
security-file-token-provider – Generate Vault tokens for EdgeX services


SYNOPSIS
========
security-file-token-provider [-h|-help] [-c|--confdir <confdir>] [-p|--profile <name>]


DESCRIPTION
===========
security-file-token-provider generates per-service Vault tokens for EdgeX services
so that they can make authenticated connections to Vault to retrieve
application secrets.
security-file-token-provider implements a generic secret seeding mechanism based
on pre-created files and is designed for maximum portability.
security-file-token-provider takes a configuration file that specifies the services
for which tokens shall be generated and the Vault access policy
that shall be applied to those tokens.
security-file-token-provider assumes that there is some underlying protection mechanism
that will be used to prevent EdgeX services from reading each other’s tokens.


OPTIONS
=======
  \-h, \--help
    Display help text

  \-c, \--confdir <confdir>
    Look in this directory for configuration.toml instead.

  \-p, \--profile <name>
    Indicate configuration profile other than default


FILES
=====

configuration.toml
------------------
This file specifies the TCP/IP location of the Vault service
and parameters used for Vault token generation.

::

  [SecretService]
  Scheme = "https"
  Server = "localhost"
  Port = 8200 

  [TokenFileProvider]
  PrivilegedTokenPath = /run/edgex/secrets/security-file-token-provider/secrets-token.json
  ConfigFile = token-config.json
  OutputDir = /run/edgex/secrets/
  OutputFilename = secrets-token.json


secrets-token.json
------------------
This file contains a token used to authenticate to Vault.
The filename is customizable via *OutputFilename*.

::

  {
    "auth": {
      "client_token": "s.wOrq9dO9kzOcuvB06CMviJhZ"
    }
  }


token-config.json
-----------------
This configuration file tells security-file-token-provider which tokens to generate.

In order to avoid a directory full of `.hcl` files,
this configuration file uses the JSON serialization of HCL,
documented at https://github.com/hashicorp/hcl/blob/master/README.md.

Note that all paths are keys under the "path" object.

::

  {
    "service-name": {
      "edgex_use_defaults": true,
      "custom_policy": {
        "path": {
          "secret/non/standard/location/*": {
            "capabilities": [ "list", "read" ]
          }
        }
      },
      "custom_token_parameters": { }
    }
  }


When edgex-use-default is true (the default),
the following is added to the policy specification
for the auto-generated policy.
The auto-generated policy is named ``edgex-secrets-XYZ``
where ``XYZ`` is ``service-name`` from the JSON key above.
Thus, the final policy created for the token will be the union
of the policy below (if using the default policy)
plus the ``custom_policy`` defined above.

::

  {
    "path": {
      "secret/edgex/service-name/*": {
        "capabilities": [ "create", "update", "delete", "list", "read" ]
      }
    }
  }

When edgex-use-default is true (the default),
the following is inserted (if not overridden) to the token parameters for the generated token.
(See https://www.vaultproject.io/api/auth/token/index.html#create-token.)

::

  "display_name": token-service-name
  "no_parent":    true
  "policies":     [ "edgex-service-service-name" ]

Note that ``display_name`` is set by vault to be "token-" + the specified display name.
This is hard-coded in Vault from versions 0.6 to 1.2.3 and cannot be changed.

Additionally, a meta property, ``edgex-service-name`` is set to ``service-name``.
The edgex-service-name property may be used by clients to infer the location in the
secret store where service-specific secrets are held.

::

  "meta": {
    "edgex-service-name": service-name
  }


{OutputDir}/{service-name}/{OutputFilename}
-------------------------------------------
For example: ``/run/edgex/secrets/edgex-security-proxy-setup/secrets-token.json``

For each "service-name" in ``{ConfigFile}``,
a matching directory is created under ``{OutputDir}``
and the corresponding Vault token is stored as ``{OutputFilename}``.
This file contains the authorization token generated
to allow the indicated EdgeX service to retrieve its secrets.


PREREQUISITES
=============
``PrivilegedTokenPath`` points to a non-expired Vault token that the security-file-token-provider
will use to install policies and create per-service tokens.
It will create policies with the naming convention ``"edgex-service-service-name"``
where ``service-name`` comes from JSON keys in the configuration file and the Vault policy
will be configured to allow creation and modification of policies using this naming convention.
This token must have the following policy (``edgex-privileged-token-creator``) configured.

::

  path "auth/token/create" {
    capabilities = ["create", "update", "sudo"]
  }
  
  path "auth/token/create-orphan" {
    capabilities = ["create", "update", "sudo"]
  }
  
  path "auth/token/create/*" {
    capabilities = ["create", "update", "sudo"]
  }
  
  path "sys/policies/acl/edgex-service-*"
  {
    capabilities = ["create", "read", "update", "delete" ]
  }
  
  path "sys/policies/acl"
  {
    capabilities = ["list"]
  }

AUTHOR
======
EdgeX Foundry <info@edgexfoundry.org>