Page tree
Skip to end of metadata
Go to start of metadata

Set up OpenID Connect provider

Set up an OpenID Connect authentication provider (e.g. Keycloak as a local deployment or Auth0 a a cloud service). See subpages on how to setup the OpenID Connect provider of your choice for use with the Border Gateway:

Create a TLS certificate for your deployment

Simplest option is to use Let´s encrypt. You will need the two .pem files containing the certificate itself (including chain) and the private key. See below on how to provide the necessary information in a config file.

Create config file

Create a file config.toml with the following entries (the example assumes using Keycloak as OpenID Connect provider):

tls_key = "/bgw/certs/<your_key>.pem"
tls_cert = "/bgw/certs/<your_cert>.pem"


  address = ""
  port = 8883
  username = "linksmart"
  password = "demo"
  tls = true
  tls_ca = ""
  tls_client_key = ""
  tls_client_cert = ""




      local_address = "<address_of_your_local_service>:<port>"

redis_host = redis
redis_port = 6379


    audience = "bgw_client"
    client_id = "bgw_client"
    client_secret = "<client_secret>"
    redirect_uri = "https://<your_application_domain_name_used_in_certificate>:443/callback"
    anonymous_bgw_rules = "HTTPS/GET/# MQTT/#"

Note that anonymous access is limited to read-only for HTTP to start with. Full anonymous access to MQTT is granted. Find out more about authentication and authorization in the dedicated section.

Start Docker container

Run the Border Gateway with docker-compose with Docker in swarm mode (this allows using the convenient functionality for secrets and configs). Make sure the .pem files and the config.toml are available, e.g.:

version: '3.5'
    image: "linksmart/bgw:latest"
      replicas: 1    
    container_name: "bgw"
      - redis
      - 443:443
      - 8883:8883
      - 9002:9002
      - source: bgw-ssl.cert
        target: "/bgw/certs/<your_cert>.pem"
      - source: bgw-ssl.key
        target: "/bgw/certs/<your_key>.pem"
      - source: config
        target: "/bgw/config/config.toml"

      replicas: 1
    image: redis:5-alpine
      - 6379:6379

    file: "./certs/<your_cert>.pem"
    file: "./certs/<your_key>.pem"
    file: "./config.toml"

Set up Redis as an access token cache

You need to set up key-value database Redis to cache access tokens for connections using username / password. The BGW auth service will store keys and values in Redis like this:

  • Key: SHA256 hash of string token_endpoint + username + password
  • Value: Access token encrypted using AES-256 with the user password as symmetric key
  • Key and value automatically expire after the number of seconds defined in auth_service_redis_expiration

The access tokens will be cached for the duration of their lifespan according to the expiration timestamp sent inside the token.

  • No labels