Bosch IoT Insights

Custom Identity Provider (IDP) Authentication

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.