Configuring KeyCloak Open ID Connect

You must register your thingshub tennat with Keycloak instance in order to use Keycloak OIDC with thingshub. You will need the client ID and client secret key that Keycloak generates for you after the registration.

Configure OpenID Connect and register Thingshub in Keycloak Instance

1. Open the Admin Console of your Keycloak installation in your browser.

2. Sign in with keycloak admin account with appropriate privilege, if not done already.

3. Hover over Select realm and click on Add realm.

4. Type thingshub in the Name field and set Enabled to ON. Click on Create. Your Realm is created.

5. On the next page, click on Clients from the left plane and click on Create.

6. Type thingshub-sso in the Client ID field. Set Client Protocol to openid-connect.

7. In the Root URL, type the domain address of your thingshub tenant. This is the address where your thingshub system is running.
   (Eg: https://foo-bar.thingshub.smartmakers.de)

8. Click on Save. You will be taken to the client settings page.

9. Scroll, find the Access Type option, and select confidential from the dropdown.

10. Find the Service Accounts Enabled option and switch it to ON. Find the Authorization Enabled option and switch it to ON.

11. Scroll to the bottom and Click on save.

12. Go to the Credentials tab from the top and find the value Secret under the Client Authenticator section. This is your Client Secret. Your Client ID is thingshub-sso.

Enable and configure Keycloak OIDC in Thingshub

global:
  domain: foo.bar.com
  tenant_mode: trackinghub

...

  identity_providers:
    keycloak_oidc:
      enabled: true
      params:
        realm: thingshub
        client_id: thingshub-sso
        client_secret: <Client Secret from above>
        root_url: <Addresss of your keycloak installation>
        skip_verify: true
        self_signed: true
        ca_certificate: "<base64 encoded CA Certificate>"
      button:
        logo: "data:image/png;base64,iVBORw0KG........"
        text: "Sign-in with KeyCloak"
        btn_color: "#B12B28"
        text_color: "#402306"

...

keycloak_oidc configurations:

• enabled: The enabled flag is used to toggle keycloak_oidc on or off.

• params: This block provides the configurations for thingshub to set up keycloak_oidc

  • realm: The name of the realm in keycloak where the thingshub is registered as a client. It is the value you put in the Name field while creating the realm ( here “thingshub” ).

  • client_id: This is the ID of the thingshub client registered to the Keycloak realm. It is the value you put in the Client ID field while creating the client (here “thingshub-sso” ).

  • client_secret: This is the secret provided by the Keycloak for the thingshub client after client creation. You can access it from the Credentials tab of thingshub client settings in the Keycloak Admin Console.

  • root_url: This is the URL of the Keycloak installation that you are using.

• button: The button block holds the theme for the button for Keycloak OpenID Connect displayed on the thingshub login page.

  • logo: It is the base64 encoded string of the image to be displayed in the login button for Keycloak OpenID Connect. The base64 encoding should be in Data URI format.

  • text: Text is the message to be displayed in the login button for Keycloak OpenID Connect.

  • btn_color: It sets the color of the login button for Keycloak OpenID Connect.

  • text_color: It sets the color of the message in the text field that is to be shown in the login button for Keycloak OpenID Connect.

Self Signed Keycloak

We can enable thingsHub to connect a Keycloak server that is using a self-signed certificate.

In the keycloak_oidc configurations and under the params section, we need to configure in the following way:

• self_signed: Boolean flag indicating a self-signed certificate. Off by default. This indicates if the configured Keycloak Server is using a Self-signed certificate.

• ca_certificate: Base64 encoded CA certificate used by the self-signed Keycloak server to verify the signed server certificate (mandatory when self_signed is used)

Security Implications of Using Self-Signed Keycloak

When the self_signed option is turned on, thingsHub will verify the authenticity and validity of the configured Keycloak Server’s certificate with the CA Certificate explicitly provided to thingsHub through the ca_certificate option, and not through the trusted Certificate Authorities. This is not recommended as well and can cause unwanted security issues as the provided CA Certificate of the Self-signed server might be scammed or fake or the CA itself is not trusted. We encourage you to turn this option off (which is by default) and recommend using publicly verified and trusted certificates issued by a trusted Certificate Authority on the server side.

Insecure Keycloak

We can enable thingsHub to connect a Keycloak server and bypass or skip server certificate validation completely.

In the keycloak_oidc configurations and under the params section, we need to configure in the following way:

• skip_verify: Boolean flag indicating if TLS verification should be skipped or not. Off by default. If true, thingsHub will not verify the authenticity and validity of the configured Keycloak ServerSecurity Implications

Security Implications of Using Insecure Keycloak

When the skip_verify option is turned on, thingsHub will not verify the authenticity and validity of the configured Keycloak Server. This is not recommended and can cause unwanted security breaches as the server-provided certificate might be scammed or fake and thingsHub will directly ignore those due to this option. We encourage you to turn this option off (which is by default)

Different combinations of Insecure and Self-Signed Settings and thingsHub System Behavior

This section outlines the different scenarios that can come as a result of different setting used in the Keycloak configuration to connect to a self-signed Keycloak Instance. Insecure (skip_verify) option skips any TLS certificate checks and errors that might have occurred and also has the precedence over the self-signed setting in the Keycloak.

The table below shows how thingsHub System behaves for different Keycloak settings when connecting to a self-signed Keycloak.