Configuring Generic OpenID Connect | thingsHub Public Documentation

You must register your ThingsHub tenant as an OpenID Connect (OIDC) application at the customer's identity provider. You will need the issuer_url, client_id, and client_secret from the registered application.

Generic OIDC can be used with standards-compliant providers such as Microsoft Entra ID, Okta, Auth0, Keycloak, or PingFederate. The names of the settings may differ between providers.

Configure OpenID Connect and register ThingsHub at the identity provider

Open the administration console of the customer's identity provider and sign in with an account that can manage applications.
Create a new application or client.
Select OpenID Connect and the Web Application or Confidential Client application type.
Enable the Authorization Code flow.
Enter a name such as ThingsHub SSO.
Add the ThingsHub tenant callback URL as an allowed redirect URI:
```
 https://<tenant-domain>/generic-oidc/callback
```
For example:
Enable the following scopes:
```
 openid profile email
```
Configure the provider to include the user's email address in the ID token as the email claim.
Save or enable the application.
Copy the generated client_id and client_secret.
Copy the provider's canonical issuer URL. The issuer must provide an OIDC discovery document at:
```
  <issuer_url>/.well-known/openid-configuration
```

Use the exact issuer URL published by the provider. Do not use its authorization URL or token URL as the issuer.

Enable and configure Generic OIDC in ThingsHub

YAML

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

...
  
  identity_providers:
    generic_oidc:
      enabled: true
      params:
        issuer_url: <Issuer URL from above>
        client_id: <Client ID from above>
        client_secret: <Client Secret from above>
        scopes:
          - openid
          - profile
          - email
        skip_verify: false
        self_signed: false
        ca_certificate: ""
      button:
        logo: "data:image/png;base64,iVBORw0KG........"
        text: "Sign in with company SSO"
        btn_color: "#192E35"
        text_color: "#FFFFFF"

generic_oidc configurations:

enabled: Enables or disables Generic OIDC for the tenant.
params: Contains the settings ThingsHub uses to connect to the identity provider.
- issuer_url: The provider's canonical OIDC issuer URL. ThingsHub uses it to discover the authorization, token, and signing-key endpoints.
- client_id: The ID assigned to the ThingsHub application by the identity provider.
- client_secret: The secret generated for the ThingsHub application. It must be kept confidential.
- scopes: The OIDC scopes requested during login. ThingsHub requires openid and an email claim. The recommended values are openid, profile, and email.
- skip_verify: Disables TLS certificate verification when set to true. It is false by default and must remain false for production tenants.
- self_signed: Set to true only when the identity provider uses a certificate issued by a private or self-signed CA.
- ca_certificate: The Base64-encoded PEM CA certificate used when self_signed is true.
button: Defines the Generic OIDC button shown on the ThingsHub login page.
- logo: Base64-encoded image in Data URI format.
- text: Text displayed on the login button.
- btn_color: Background color of the login button.
- text_color: Color of the button text.

User account requirement

Generic OIDC authenticates an existing ThingsHub user; it does not create users automatically. Before testing the login, create the user in ThingsHub with the same email address returned in the OIDC email claim and assign the required ThingsHub roles.

Email matching is case-insensitive. If no ThingsHub user has the returned email address, the login is rejected with USER_NOT_FOUND.