Project specific REST APIs of Bosch IoT Insights can be accessed with OpenID Connect based JWT access tokens. A project can trust multiple OpenID Connect issuers.

This feature is useful for project owners that want to manage identity and authorization information for their technical clients within their own identity management system.

Use cases

images/confluence/download/attachments/4306999390/Access-Insights-with-access-token-version-1-modificationdate-1716968811000-api-v2.png

To use this feature you need to bring your own IDP, in which you manage clients, that represent e.g. an application (App). The App usually requests an access token from the IDP using the client credentials flow. The access token is then sent to the Bosch IoT Insights API.

Basic use case

I want my app to access the REST API of Bosch IoT Insights to send or manage data of one or more projects
I want to manage the clients and credentials in my own identity provider (IDP)

Use case 1: Authorization managed in my IDP

I want to manage the roles my App has in a Bosch IoT Insights project within my IDP

For this use case the Custom IDP can be configured with roleDetection=CLAIM, see Custom IDP Configuration below.

In this case the roles are contained in the Access Token.

Use case 2: Authorization can't be managed in my IDP

I want to define which roles my app has in a Bosch IoT Insights project

For this use case the Custom IDP can be configured with roleDetection=DEFINED and a list of roles, see Custom IDP Configuration below.

Token requirements

A JWT access token which can be sent to Bosch IoT Insights project specific REST API endpoints in a Authorization Bearer header, expects the following claims in the payload:

Claim	Type	Required	Description
iss	string	yes	The URL to the OpenID Connect issuer
exp	number	yes	When the token expires
iat	number	yes	When the token was issued
azp	string	no	Authorized party, which identifies the client that requested the token.
configurable id (default: sub)	string	yes	The subject, or unique id of the client that is authorized. This id is used within Bosch IoT Insights to document who did the request.
configurable roles claim	list of strings	no	Optionally project specific roles can defined that the client should have during the request.

Example token payload

This token is issued by https://my-specific-issuer.com/auth which provides it's OpenID Connect configuration under: https://my-specific-issuer.com/auth/.well-known/openid-configuration

It defines the unique user id in the sub claim as "707f4062-c6b8-495e-b57e-d96f995d5f26".

It provides project specific roles in the scp claim, that the user has the roles access and data_provider in the project pxy12345.

A custom IDP configuration for the project is required to trust the token.

{
  "aud": "...",
  "iss": "https://my-specific-issuer.com/auth",
  "iat": 1708350706,
  "exp": 1708354606,
  "azp": "707f4062-c6b8-495e-b57e-d96f995d5f26",
  "sub": "707f4062-c6b8-495e-b57e-d96f995d5f26", // the clientId
  "scp": [
    "pxy12345.access",
    "pxy12345.data_provider"
  ]
}

OpenID Connect compatible identity and authorization systems like Keycloak or Microsoft EntraID already generate compatible tokens. Only the roles claim configuration is highly individual, if needed.

Custom IDP configuration

The custom IDP configuration for a Bosch IoT Insights project can be configured as project owner via REST APIs:

GET /project-management-service/v1/projects/{project}/custom-idp // List custom identity providers
POST /project-management-service/v1/projects/{project}/custom-idp // Add a new identity provider
PUT /project-management-service/v1/projects/{project}/custom-idp/{idpId} // update identity provider
DELETE /project-management-service/v1/projects/{project}/custom-idp/{idpId} // delete identity provider

The request endpoints can be found the latest API documentation.

To accept the example token from above, an IDP configuration could look like this:

{
  "id": "myIDP",
  "idClaim": "sub",
  "iss": "https://my-specific-issuer.com/auth",
  "label": {
    "en": "My IDP"
  },
  "roleDetection": "CLAIM",
  "roleTemplate": "{project}.{roleName}",
  "rolesClaim": "scp",
  "allowedAzp": null
  "allowedRoles": null
  "definedRoles": null
}

Because the IDP configuration is project specific, only REST APIs of Bosch IoT Insights can be accessed that have the project name within the request path.

Configuration options

Property	Required	Description
id	yes	Unique technical name to identify the identity provider within the project. Between 2 and 16 characters [a-zA.Z0-9_-]
iss	yes	The URL to the issuer, which has to be the exact issuer that is also contained in the token. The <iss>/.well-known/openid-configuration must accessible.
label	yes	Human readable label by language (English is mandatory)
allowedAzp	no	Optional array of allowed values for the azp claim of the token. If the azp claim value does not match any entry in the proved list, this idp config will be skipped and the next one will be evaluated.
idClaim	yes	The name of the claim, which is used to uniquely identify the client, which is sending the request. The value of the claim will be used together with the id of the IDP to identify actions in the audit log or input history.
roleDetection	yes	How the roles are detected. CLAIM tries to resolve the roles from the token. DEFINED will use the roles defined in the "definedRoles" property. This is useful if the roles are not contained in the token.
rolesClaim	yes, if roleDetection=CLAIM	The claim which contains an array of roles. The roles can be in a format defined by the "roleTemplate" property.
roleTemplate	yes, if roleDetection=CLAIM	Which format does each role have? The template must contain the mandatory placeholder: {roleName} The placeholder {project} is optional, but useful when the same token can be used to access multiple projects. Example template: "{project}.{roleName}" would extract from a value like "project-xy.admin" the roleName "admin" and the project "project-xy". Example template: "role_{roleName}" would extract from a value like "role_admin", the roleName "admin" for any project.
allowedRoles	no, only for roleDetection=CLAIM	Can be null to allow all roles extracted from the rolesClaim. The value can be an array of role names which are allowed to be contained in a rolesClaim. Other roles in the rolesClaim will be ignored.
definedRoles	yes, if roleDetection=DEFINED	A list of role names which should be used for the request.