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

If you haven´t already, please have a look at the tutorial for an example of a full Border Gateway setup.

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

[external-interface]
tls_key = "/bgw/certs/<your_key>.pem"
tls_cert = "/bgw/certs/<your_cert>.pem"

[mqtt-proxy]

  [mqtt-proxy.broker]
  address = "demo.linksmart.eu"
  port = 8883
  username = "linksmart"
  password = "demo"
  tls = true
  tls_ca = ""
  tls_client_key = ""
  tls_client_cert = ""

[http-proxy]

  [http-proxy.domains]

    [http-proxy.domains."<your_application_domain_name_used_in_certificate>"]

      [http-proxy.domains."<your_application_domain_name_used_in_certificate>"."<location>"]
      local_address = "<address_of_your_local_service>:<port>"

[websocket-proxy]
ws_upstream_base_url = "ws://<hostname_of_your_websocket_service>:<port>/"
openid_configuration="https://<keycloak_domain>/auth/realms/<realm_name>/.well-known/openid-configuration"
audience = "bgw_client"
client_id = "bgw_client"
client_secret = "<client_secret>"

[auth-service]
redis_host = redis
redis_port = 6379

  [auth-service.openid_connect_providers]

    [auth-service.openid_connect_providers.default]
    openid_configuration="https://<keycloak_domain>/auth/realms/<realm_name>/.well-known/openid-configuration"
    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. Make sure the .pem files and the config.toml are available, e.g. in mounted volumes:

version: '3.5'
services:
  
  bgw:
    image: "linksmart/bgw:latest"
    depends_on:
      - redis
    ports:
      - 443:443
      - 8883:8883
      - 9002:9002
    volumes:
      - "./config.toml:/bgw/config/config.toml"
      - "./certs:/bgw/certs"

  redis:
    image: redis:5-alpine
    command: ["--save","","--appendonly","no"]
    ports:
      - 6379:6379

Start it up in the background with

docker-compose up -d

Redis as an access token cache

Key-value database Redis is needed 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