Skip to content

How To Retrieve Token For Consul And Kong



Consul is the default registry implementation and provides native features for service registration, service discovery, and health checking. Refer to Secure Consul - EdgeX Foundry Documentation for more detail.


In the current EdgeX architecture, Consul is pre-wired as the default agent service for Service Configuration, Service Registry, and Service Health Check purposes.

Prior to EdgeXpert v2.0.0 release, the communication to Consul used plain HTTP calls without any access control (ACL) token header and thus was insecure. With the EdgeXpert v2.0.0 release, that situation is now improved by adding required ACL token header X-Consul-Token in any HTTP calls. Moreover, Consul itself is now bootstrapped and started with its ACL system enabled and thus provides better authentication and authorization security features for services. In other words, with the required Consul's ACL token for accessing Consul, assets inside Consul like EdgeX's configuration items in Key-Value (KV) store are now better protected.


Consul is no longer the default service as of Edge Xpert v2.1.0. To start Consul, you need to use the --consul option with the edgexpert up command.

How to get Consul ACL token

Consul's access token can be obtained from the following command:

$ docker exec -it consul /bin/sh -c 'cat "$STAGEGATE_REGISTRY_ACL_BOOTSTRAPTOKENPATH" | jq -r '.SecretID' '

This output token is Consul's ACL bootstrap token and thus one can use it to login and access Consul service's features from Consul's GUI on http://localhost:8500/ui.

API Gateway


Refer to API Gateway for more detail.

Creating Access Token for API Gateway Authentication

The API gateway is configured to require authentication prior to passing a request to a back-end microservice.

It is necessary to create an API gateway user in order to satisfy the authentication requirement. Gateway users are created using the proxy subcommand of the secrets-config utility.

JWT authentication

JWT authentication is based on a public/private key-pair, where the public key is registered with the API gateway, and the private key is kept secret. This method does not require exposing any secret to the API gateway and allows JWTs to be generated offline.

Before using the JWT authentication method, it is necessary to create a public/private key-pair. This example uses ECDSA keys, but RSA key can be used as well.

openssl ecparam -name prime256v1 -genkey -noout -out ec256.key
openssl ec -out < ec256.key

Next, generate and save a unique ID that will be used in any issued JWTs to look up the public key to be used for validation. Also we need the JWT used to authenticate to Kong--this JWT was written to host-based secrets area when the framework was started. (Note the backtick to capture the uuidegen output.)

  KONGJWT=`sudo cat /tmp/edgex/secrets/security-proxy-setup/kong-admin-jwt`

Register a user for that key:

edgexpert run -v `pwd`:/host:ro --entrypoint /edgex/secrets-config proxy -- proxy adduser \
   --token-type jwt --id "$ID" --algorithm ES256 --public_key /host/ \
   --user tester --jwt "$KONGJWT"
The group to which the user belongs is admin by default. Any user account that belongs to the admin group has access to all services. To give permissions to user accounts, configure the ACL plug-in as described in the Kong documentation

Lastly, generate a valid JWT. Any JWT library should work, but secrets-config provides a convenient utility:

edgexpert run -v `pwd`:/host:ro --entrypoint /edgex/secrets-config proxy -- proxy jwt \
    --id "$ID" --algorithm ES256 --private_key /host/ec256.key

The command will output a long alphanumeric sequence of the format <alphanumeric> '.' <alphanumeric> '.' <alphanumeric>

The access token is used in the Authorization header of the request. To de-authorize or delete the user:

edgexpert run --entrypoint /edgex/secrets-config proxy -- proxy deluser \
    --user tester --jwt "$KONGJWT"

Back to top