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
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} 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. |