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

The LinkSmart® Border Gateway (BGW) can authenticate and authorize access to HTTP and MQTT services for users defined in an OpenID Connect provider. 

Authentication

HTTP

Browser

If anonymous access to an endpoint accessed via browser is not allowed, the browser will present fields for username and password. You can either type in username and password (Basic access authentication) or put an access token (see below) in the username field. Leave the password field empty if you do the latter.

Basic Auth

>>> How to: send credentials in header.<<<

  1. User provides username/password in the REST request
  2. BGW intercepts the request and negotiates with an OpenID Connect server for an access token
  3. If authenticated, BGW forwards the request to API

Bearer Token

>>> How to: use Bearer authentication in Postman <<<

  1. User directly negotiates with an OpenID Connect server for an access token. Example via curl for Keycloak:

    curl -d "client_id=bgw_client" -d "username=<username>" -d "password=<password>" -d "grant_type=password" "https://auth.fit.fraunhofer.de/kc/realms/linksmart-demo/protocol/openid-connect/token"
  2. User provides the access token in the request
  3. BGW intercepts the request and validates the token
  4. If authenticated, BGW forwards the request to the API

MQTT

If you connect to the Border Gateway via MQTT protocol, you can deliver username and password as defined in the MQTT standard. You can also deliver an access token (as described above for HTTP) in the MQTT username field. Leave the password field empty if you do. Both types of credentials will be validated against the OpenID Connect provider.

WebSocket

By default the BGW WebSocket proxy expects that you use protocol MQTT over WebSockets so the data is forwarded to the BGW MQTT proxy and authenticated and authorized there. You can configure the WebSocket proxy to forward to any upstream server though. In this case, the WebSocket proxy expects the last value of the "protocol" field to be an OpenID Connect access token obtained from Keycloak. JavaScript Example:

let ws = new WebSocket("wss://<your_domain>", ["protocol1","protocol2", "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJGZFVBS2JVZjlDWVNod3g5ZFlXa1ptR1plQlNhZHZ2Y1dkTGNQZUprSTU4In0.eyJqdGkiOiI2NTVhZGRmMi05Mzg0LTRmYTUtOTM5MS1lYWIxNDczMjE2M2EiLCJleHAiOjE1NTA1NjkxODEsIm5iZiI6MCwiaWF0IjoxNTUwNTY1NTgxLCJpc3MiOiJodHRwczovL2F1dGguZml0LmZyYXVuaG9mZXIuZGUva2MvcmVhbG1zL2Jndy1qYW5uaXMtbG9jYWwiLCJhdWQiOiJiZ3dfY2xpZW50Iiwic3ViIjoiMGZkNjBmMjEtZjFhNi00NTNlLWFmOTItZTQ1NjlkZTM2ZDFiIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiYmd3X2NsaWVudCIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjVkMGU2MDNkLTc5YTYtNDExMC05OTQxLTljMjFiYTMwNjQ3YSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOltdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiIiwiYmd3X3J1bGVzIjoiSFRUUFMvR0VULyMgTVFUVC8jIFdTL0NPTk5FQ1QvbG9jYWxob3N0LzUwNTEiLCJiZ3dfcnVsZXNfd3JpdGVfYWNjZXNzIjoiSFRUUFMvUFVULyMgSFRUUFMvREVMRVRFLyMiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJsaW5rc21hcnQifQ.gvbNRb2_d9eMc9f7HDRhZFNzc1rLozhgAfl4Nt_pP1oR4rlloO2BRN4bGkWF4RRZCELQXK-_9y1sCLaG9WCATxqaJmsf9MJog7eamzRkzw8d_6eUfUx_3nwaiW4AdVtgSulAzVb7l9HDdq9M-q5JJiB4hT2LMRdmau2OXnNh0r0TfwHq01H2fRFn8DGXnojPsYbrDdzy-EVcN0hf3uclJynKoixZbkP9JHd5qNjSgklmBwBqbfneaqMTf1zOrC9GuJNeBastift-Y2p9L3dmyH-KOh-oWE-8tQq-OkKkYVn78uB9kRQw154qDgcDCybsFdPKz6aasX_DrKyqxX347A"]);

The access token is then verified and authorized (see below). If everything is ok, the WebSocket connection is established, otherwise rejected.

Authorization

The LinkSmart® Border Gateway also offers some basic authorization capabilities. Authorization rules are defined as user and / or group attributes in the OpenID Connect Provider (see subpage). 

Rule Syntax

PROTOCOL/METHOD/DOMAIN/PORT/PATH

where:

  • PROTOCOL is the transfer protocol (currently HTTP, HTTPS, MQTT or WS)
  • METHOD is the method in regards to the protocol, e.g. GET,POST,DELETE for HTTP and PUB,SUB for MQTT. For WebSocket connections only method CONNECT is allowed.
  • DOMAIN is the fully qualified domain name (FQDN)
  • PORT
    • Case MQTT / WS: TCP port of the target / upstream service
    • Case HTTPS: In a standard deployment the BGW External Interface will add headers x-forwarded-proto and x-forwarded-host (including port) and forward to the BGW HTTP proxy so in the rules regarding HTTP services you need to use protocol HTTPS and port 443 in your rule definitions. If you deploy a BGW HTTP Proxy without the BGW External Interface, you can configure your web server (e.g. nginx) to set headers x-forwarded-proto and x-forwarded-host and define rules in the same way.
    • Case HTTP: If you do not use TLS at all or cannot configure your web server to set headers x-forwarded-proto and x-forwarded-host, you need to use HTTP in your rule definitions and the TCP port of BGW HTTP proxy. 
  • PATH is resource information and may contain slashes itself. For HTTP, it is the resource path (e.g. confluence/display/COM). For MQTT, it is the topic. For WebSocket connections PATH is currently not relevant.

Loolsely based on MQTT topic specification: https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices

In summary:

  • Every slash adds a new section. E.g.: a/b consists of two sections and a/b/ consists of three sections last of which contains an empty string.
  • Strings are case-sensitive
  • A plus + is a single section wildcard. E.g.: a/+ matches a/b but not a/b/ and a/b/c
  • A hash # is a multi-section wildcard and may only be used in the end. E.g.: a/# matches all a/b and a/b/ and a/b/c

Examples

RuleDescription

HTTPS/GET/demo.linksmart.eu/443/sc

and

HTTPS/GET/demo.linksmart.eu/443/sc/#

Allows

  • method GET
  • over HTTPS
  • on domain intra.composition-ecosystem
  • port 443
  • path sc and starting with sc
HTTPS/+/demo.linksmart.eu/443/#

Allows

  • all methods
  • over HTTPS
  • on domain intra.composition-ecosystem
  • port 443
  • with any path
HTTPS/+/demo.linksmart.eu/443/sc/admin

Allows

  • all methods
  • over HTTPS
  • on domain intra.composition-ecosystem
  • port 443
  • with sc/admin
HTTPS/#

Allows

  • everything over HTTPS
WS/CONNECT/localhost/5059

Allows

  • WebSocket connection to upstream service at localhost:5059
  • No labels