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 subpage for an example on how to set up Keycloak as an Open ID provider for 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:
tls_key = "/bgw/certs/<your_key>.pem"
tls_cert = "/bgw/certs/<your_cert>.pem"
address = "demo.linksmart.eu"
port = 8883.0
username = "linksmart"
password = "demo"
tls = true
tls_ca = ""
tls_client_key = ""
tls_client_cert = ""
local_address = "<address_of_your_local_service>:<port>"
issuer = "https://auth.fit.fraunhofer.de/kc/realms/bgw-jannis-local"
authorization_endpoint = "https://auth.fit.fraunhofer.de/kc/realms/linksmart-demo/protocol/openid-connect/auth"
token_endpoint = "https://auth.fit.fraunhofer.de/kc/realms/linksmart-demo/protocol/openid-connect/token"
audience = "bgw_client"
client_id = "bgw_client"
client_secret = ""
jwks_uri = "https://auth.fit.fraunhofer.de/kc/realms/linksmart-demo/protocol/openid-connect/certs"
realm_public_key_modulus = "y1lGnR7-Smc6qPxl7D4OxNX60T0UVkZu7O6xn4m-4QaTsweI1kgHqN8GB1ooPSQr6THNnjmIcHpMVxL4THncpaHpXn-8vMN6mKxiD6MPPdOUO7NpZEZpeUxvPdyLSaL5Vs3k-c2X1uQ7nphr1ZXN0SmhgARY73rMK5aAL_gjvK3EGqZUzeeakZdIOuWjxO58Z6HkarQLVJ6bXfM8dfUKksJp7rGK-4YBccjdnbBssb_3EsQYFnoeDXHWTgu8NiKEsyI6JRtbbbeV_ZlKAHMZhdN6NUInS35tvw0VX2tK5TiASihN4VyaLa17dQ3988HkSLU1d2niIcKyW--ykjDnzQ"
realm_public_key_exponent = "AQAB"
redirect_uri = "https://<your_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.json is available, e.g.:
Optional: Set up Redis as an access token cache
You can use key-value database Redis to cache access tokens for connections using username / password. Without caching, each request to one of your services will lead to a post a request to the OpenID Connect provider to retrieve an access token containing the authorization rules. Caching may speed things up. You can add a Redis instance to your Docker deployment by extending your docker-compose file like this:
Add this to your config.toml (by default, Redis support is not enabled):
redis_expiration = 120
redis_host = redis
redis_port = 6379
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 is set to a value > 0 the BGW auth service will always try to get an access token from Redis first before posting a request to the OpenID Connect provider. Make sure that the value
auth_service_redis_expiration is not higher than the configured lifespan of the access tokens!