Service Specification

About Bosch IoT Permissions

Bosch IoT Permissions - also known as Identity Management, or IM3 - is a fully-managed cloud service to administrate your users, groups, roles, permissions and tenants. The service provides RESTful APIs, an administrative user interface, user-self-service interfaces and Java client libraries.

Features at a Glance

Bosch IoT Permissions is a service for managing user accounts, authorization information, and multiple tenants for your application.

User management

User management addresses the management of user accounts for your application. A user account holds basic user properties such as user name, first name, last name, and email address. Additionally, you can make use of multiple custom user attributes, e.g.  mobile number.

The API provides several ways to authenticate users, as well as a range of self-services for users (e.g. registration with customizable email notification).

By integrating with an external identity provider such as Bosch ID or Google, your application can delegate all authentication requests to the external provider, and still get a local user account at Bosch IoT Permissions, which facilitates additional user data and authorization management.

Authorization management

Build your own IoT application that registers its roles and permissions at Bosch IoT Permissions. In your application, you are free to decide which permission should be checked when a specific functionality is executed, and how to group various permissions into application roles.

Once your roles and permissions are registered at our service, you can empower your users with all necessary permissions. You can directly grant roles to users, or even group your users and assign the roles to the group. Since the groups support hierarchies, even highly sophisticated scenarios can be represented. In case you need to authenticate software tools or end-user devices, you can issue credentials that authorize use of a subset of a user’s permissions.

After authentication, the service provides authorization information, such as the user’s roles and permissions as a JSON Web Token (JWT). This token is used by your application to check for permissions and can also be passed along to other services in a multi-service architecture. Since authenticity can be verified locally without a remote request, authorization checks can be executed efficiently on the token.

Tenant management

The multitenancy principle is fully implemented by Bosch IoT Permissions. All entities belong to one tenant to ensure data and services between tenants remain strictly separate. Each tenant is empowered to manage its own users, groups, and roles.

The service also supports you in developing a multitenant application for your business customers. Each of you customers can be managed as an own tenant. In your application, you need to ensure that the application is shared with each customer; each customer can only manage their own application data.

Tenant management provides a model and an API to implement this. Additionally, it allows controlled sharing of application data between tenants.

  • Sharing an application – Offering an application as a service to a tenant.
    Provider tenants can offer other tenants access to their applications. Each receiving tenant works on its own data that results from using the application.
  • Sharing data – Using an application with another tenant’s data.
    Provider tenants can also offer access to the application and their own data. The receiving tenant can act transparently on behalf of the provider.

The service API allows for setting up and managing these cross-tenant access scenarios via the tenant relations concept.

Bonus features *)

  • Manage entities within the administrator Web user interface
  • Java client for our service APIs (optional)

* ) Although these features are provided in all currently offered service plans without additional fees, the bonus features may be subject to revision without advance notice, and the offering may even be cancelled without prior written consent from our customers. Such a change will be announced via our documentation channel.

Service provisioning

  • A Bosch IoT Cloud account or a Bosch ID is needed to use this service
  • The Bosch IoT Permissions service is provided as a HTTP based API in the Bosch IoT Cloud and in the Internet

Pricing

The pricing is based on a service plan. The service plan can be selected when subscribing to the service. The plan can also be changed afterwards, if necessary.

Service Plans

Free

  • Try-it-for-free: No restriction in functionality compared to the Standard package
  • User Management
  • Authorization Management
  • Tenant Management
  • Best choice for developers
  • Limited to 10 Users and 5 Tenants

Starter

  • Production-ready package
  • User Management
  • Authorization Management
  • Best choice for an application in production
  • Included: 500 Users and 1 Tenant
  • Possibility to manage more users (additional charge per user)

Standard

  • Production-ready package for your multitenant application
  • User Management
  • Authorization Management
  • Tenant Management
  • Best choice for a multitenant application
  • Possibility to manage more users and tenants (additional charge per user and tenant)


How to change your service plan

Please use the Cloud Foundry command line interface. Find an example in our Developer Guide > Change the Service Plan of your Bosch IoT Permissions instance.

Notes on billable entities

User

A "User" comprises a user account, stored and managed at Bosch IoT Permissions service. At least one User is needed for each single person who is authenticated or authorized with Bosch IoT Permissions service.

The Bosch IoT Permissions service provides IoT solutions which subscribe our service the opportunity to manage their user accounts (or to re-use such from another identity provider) and to grant them permission to access the IoT solutions.

A User comprises all data stored at the Bosch IoT Permissions persistence regarding a specific user account.
Depending on the tenant specific settings and assignments via the user management functionality, Bosch IoT Permissions calculates for each user session the current set of his permission. This calculation is based on additional information, manageable within the service. Such entities are for example Groups, Group hierarchies, and Roles.

From a functional point of view, a user might be unable to login using our service, as he might be:

  • Locked - due to multiple fails login attempts,
  • Pending - in case of self-registration last step of activation is missing,
  • Marked as deleted - by an administrative user or by himself trying to delete his account.

However, from the billing point of view, our system still provides data about such a user and is thus still counted as managed user.

Each user is associated to one tenant and thus on account of that tenant. In case a person is granted access to work on behalf of another tenant, still the one he “belongs to” will be accounted for this user, as long as from our system’s perspective it is the same managed user (i.e. the user account was not duplicated on the tenant he is active for).

A single person however, might need more than one managed user, if he is using different accounts at signing-in. For example, if your tenant is configured to accept users from another identity provider (such as a Bosch customer account and a Google account) and the person actually signs in with both, he will have two “digital representations” in our service and thus the tenant will be accounted for 2 managed users.

Another scenario for more managed users than persons might be a (technical) user account for applications.

Tenant

A "Tenant" is intended to be used for representing one legal organizational unit. A Tenant owns a set of User entities and can manage these users on its own. Your service account makes use of at least one Tenant.

The Bosch IoT Permissions service is fully multi-tenant ready. Beside the strict separation of their data and all privacy claims (e.g. a tenant must not know about the existence of the other tenant) Bosch IoT Permissions service provides the option for tenants who already know each other to work across tenant boundaries in a defined manner.

A tenant entity was designed to represent one legal organizational unit that is generally the representative of a company. Thus in any case you will be accounted for at least one Tenant. 

However, we provide the possibility to define further tenant entities within your Bosch IoT Permissions instance, each of them constituting a Tenant from the billing point of view. However, the first initial tenant will meet all expenses over all entities each tenant might create himself within our persistence.

Each stored tenant entity is counted as managed tenant, regardless of whether it is in special state (e.g. marked as deleted). The total number of managed tenants also includes the own initial tenant.

In case of discordance, or whenever you as a service subscriber assume any discrepancy about the number of billed managed entities, please do not hesitate to contact us.

Public API

The Bosch IoT Permissions service declares and supports the following public APIs:

Relevant links for API endpoints and service Web console can be found at: Developer Guide  > Service Endpoints.

API Stability and Client Compatibility

The service provides backwards compatibility for its public APIs, i.e. it guarantees that your existing API 1 Client for Java (starting with version 4.x) or existing HTTP API requests still work with the current service. However, in case your application is already integrated with Bosch IoT Permissions service please consult our API documentation regarding the current functionality we support. Do not hesitate to report any discrepancy between the public API documentation and service behavior. We will do our best to re-establish the compatibility as soon as possible.

We reserve the rights to add security related features (which might not be handled respectively by an older client) without further notice.
An example of such a feature is throttling of API requests to mitigate denial of service attacks. For such cases we may need to introduce a new error response, which will not be known to existing clients.

For a complete definition for API and client stability have a look into the documentation: Developer Guide > API Description

System Requirements

Service API 1 and 2

HTTPS with TLS 1.2 is required to use the Service API 1 and 2.

The client must support one of the following TLS cipher suites:

  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Note: Windows 10 supports these cipher suites. Windows 7 and Windows 8 do not provide these cipher suites (https://msdn.microsoft.com/en-us/library/windows/desktop/mt767780(v=vs.85).aspx)

API 1 and API 2 Client for Java

Oracle Java SE 8 is required to use the clients.

Browser support

The following desktop browsers are supported to use the Administrator UI and User Self-Service UI:

  • Firefox, latest ESR version
  • Internet Explorer 11 (on Windows desktop operating systems)
  • Chrome, latest stable version

Limits

There are some limits that have to be considered when integrating and working with Bosch IoT Permissions. The currently identified limits are documented here but are subject to change in upcoming versions without notice. Not all limits are explicitly checked by the service but must be adhered to by other means.

Using Bosch IoT Permissions without complying to or exceeding these defined limits may be possible but is not recommended and is not supported.

Please contact us in case of demands beyond these limits.

Category Topic Limit Comment
Rate Limits Max. number of requests per minute per client 360

A constant rate of 360 requests per minute ( 6 requests/second) is the maximum which is allowed per client. If a client exceeds this rate, further requests may fail with a descriptive error.

Quantity limits Max. number of domains 50
Max. number of applications 100
Max. number of groups / maximum depth 100 / 10 Each group is supported with maximum 10 levels of hierarchical subordinated groups.

Max. number of roles

(per tenant / per application)

200 / 50
Max. number of permissions per application 200
Administration User Interface Max. number of objects used for multi selection operations 2 000

Multi selection operations in the UI (e.g. assigning many users to a group) are supported only up to an amount of 2 000 involved objects.
Theoretically more objects can be used in a multi selection, but the duration of these operations can get very long and the UI cannot guarantee a good user experience.

Others All date fields Year 2037

Date fields can store values up to 12/31/2037 11:59 PM. No value that exceeds this limitation is accepted.

Size of email templates 2 MB

The size of email templates should not exceed 2 MB. Bigger email templates might cause problems on some internet browsers.

Unicode support Only 3-byte UTF8
characters are supported
Full unicode (4-byte character) is not supported with Bosch IoT Permissions.
As a consequence, it is not possible to name entities with UTF8 characters that require the fourth byte. If you do so anyway, the name will be cut at the place where the unsupported 4-byte UTF8 characters is located.

Service Status

Status page

The current state of the Bosch IoT Permissions service is reported at the Bosch IoT Cloud Status page.

Check Bosch IoT Cloud Status to see our latest status update.
Please consider, that the time stamp presented there is in Coordinated Universal Time (UTC).

In case our service is reported there to be not operational, we are alerted already and most probably have started solving the problem.

Service Updates

The latest service updates notes can be found on the service dashboard (Update Notes). Changes and enhancements to the service clients are also published there.

Notifications

You may subscribe to notifications about service incidents and service updates. The notifications are currently only available for Bosch employees. 

Please use the Single Point of Information (SPoI) to subscribe. We will use this way to inform you about Bosch IoT Permissions incidents and service updates.
Find details on how to subscribe at Status Updates Bosch IoT Cloud (SPoI - Single Point of Information).
Our service is located at Platforms > Bosch IoT Cloud Services (BICS) > BIC2 (DE1) > BOSCH IOT PERMISSIONS (DE1).

Incident Reporting

Reporting an incident is currently only possible for Bosch employees.

If you notice that Bosch IoT Permissions is not available, please open a ticket at the CI-Hotline either by email to CI-Hotline@de.bosch.com or by phone: 3311.
INST colleagues may use the number of Waiblingen-2: +49 (711) 811 3311
Include tag words: "BICS Bosch Internet of Things Cloud " and "BICS - IM3 Identity Management CSG".

Incident Information

It would help us a lot, if you fill in the following form, to give us some information about the incident.

IM3 incident report (please copy&paste) Example
What is your tenant and user name?
tenant: TenantA, user: john.arnold
Which part isn't working as expected? The login with the browser.

Description

At the "BICS Bosch Internet of Things Cloud" I try to  work with "BICS - IM3 Identity Management CSG".

Login UI isn't working.
Browser URL is https://permissions.s-apps.de1.bosch-iot-cloud.com/fusion/login"
After providing correct credentials and clicking "Log in", the login form shows "Technical Error".

From which network do you send requests to the service? INST network
Your contact information John Arnold, Tel +49 12435689, john.arnold@example.com

After submitting your ticket you will receive an email for confirmation. You can also view your tickets at My IT Tickets in the Bosch inside.Portal.

If you want to get us informed immediately send an additional email to:  service-permissions@bosch-si.com.

Reporting other Bugs or Malfunctions

If you suspect a malfunction, please notify the service team.
Create an issue in our JIRA at: https://products.bosch-si.com/jira/browse/IM, or send us an email to: service-permissions@bosch-si.com.

Security Policy

Our service provides "state of the art" methods to detect security issues and a respective follow-up process.

Security monitoring

  • Dependency monitoring
    We monitor continuously if our Third Party Dependencies have reported security issues (CVEs).
  • Penetration tests
    We engage external security companies to run penetration tests against our system at irregular intervals.

Handling security issues

Report a security issue

If you find a possible vulnerability, please handle the vulnerability in a responsible manner.

Please write an email to service-permissions@bosch-si.com and provide the following information:

  • Product version or date when vulnerability was discovered
  • Descriptive summary and clear description of the security issue
  • Steps to reproduce

Please encrypt sensitive information with GnuPG using this public key:

Service-Permissions Key service-permissions@bosch-si.com(125D6F0881B118F9)_pub.asc

Fingerprint: C61D 28EE D847 D870 0C57 6E4E 125D 6F08 81B1 18F9

One of the core team members will review, reply, and if necessary ask for additional information. We will then discuss the means of fixing the vulnerability.

Customer notification

In case we have knowledge about a security vulnerability, and one of our customers can do anything about preventing this vulnerability to be exploited, we will inform this customer about appropriate measures.

In case we decide that from customer's side there is no possibility to do anything to reduce the risk, but our customer's data was at risk for some period of time, we will inform about the fix afterwards.

Communication channel

All fixes and security improvements will also be mentioned at our service documentation in section Update Notes.

Additionally we publish notifications about updates, downtime, and security incidents via SPoI. How to subscribe to these messages is described in the section Update Notes.

Vulnerability levels

Internally we distinguish following categories:

  • Blocker:
    A vulnerability that potentially allows access to user credentials, or modification of data, or execution of attack code inside the service environment.
  • Critical:
    A vulnerability that potentially allows access to data managed at Bosch IoT Permissions Service.
  • Major:
    A vulnerability that potentially allows unauthorized access to Bosch IoT Permissions data, but is significantly limited by factors such as default settings, required certain behavior from the Permissions service, or is very difficult to exploit.

Procedure in case of security alerts

In general, all security issues, even potential ones, are handled "private". This means only the reporter and the development team are involved in analyzing and fixing the issue.

  1. Analysis:
    1. Our development team will instantly become active and determine the severity and impact of the issue.
    2. Based on this the vulnerability level of the issue is defined.
    3. Customers get informed as describe in section “Customer Notification” above.
  2. Fix: We agree on a fix, implement it and test it. If necessary, we ask for support by the reporter of this issue.
  3. Release:
    1. As soon as possible a bugfix version is released and will be deployed on our cloud service first.
    2. Afterwards the bugfix will be provided to our on-premises customers.
  4. Inform: After the release and cloud deployment, we will inform our all our customers about the issue.