Update Notes

The update notes inform about new features, changes and bug fixes. Find here anything noteworthy about the Bosch IoT Permissions service.

For Bosch employees we additionally publish such announcements at the internal Single Point of Information, short SPoI.

Please subscribe there for BOSCH IOT PERMISSIONS (DE1) to get informed:

  • Navigate to inside Portal > My Work > Management & Support > SPoI.
  • On the new page select Platforms > Bosch IoT Cloud Services (BICS) > BIC2 (DE1).
  • Click on the subscription button and confirm your subscription.
    If the service is subscribed successfully, it will be displayed in a green color.

2018-10 - Automatic deletion of users which were not activated

Changes in Service API 1 and 2

Automatic deletion of users which were not activated

Self-registered users which did not activate their account and invited users which did not accept the invitation are now automatically deleted after 30 days. An audit log entry will be written for each deleted user.

Changes in service documentation

The Privacy Guide was renamed into Privacy Leaflet.

2018-09 - Support tenant name in authorization resources

Changes in Service API 2

Tenant name can be used instead of tenant id for authorization

The resources

are now accepting the tenant name as an alternative to the tenant id.

The query parameter tid of the resource /web/authorization was renamed to authorization-tenant and also accepts a tenant name or ID now.

Token refresh resource for web applications does not require tenant id anymore

The beta resource

no longer requires a tenant id query parameter because it can be retrieved from the provided authorization token.

Removed obsolete authorization resource for web applications

The beta resource

has been removed because it was not functional yet and its purpose was unclear.

Removed deprecated beta resources

As anounced on 01-2018 via update notes and on 30.05.2018 and 29.08.2018 via SPoI, some deprecated beta resources have been removed:

Removed beta resource name Replacement since 01-2018
/password/enforcechange /password/enforce-change
/password/resetcode /password/reset-code
/password/resetemail /password/reset-email
/users/{$user-id}/acceptinvitation /users/{$user-id}/accept-invitation
/users/{$user-id}/activationcode /users/{$user-id}/activation-code
/contractingtenants /contracting-tenants
/password/agentcredentials /users/current/agent-credentials

Changes in Service API 2 Client for Java

Migration required

Replace deprecated methods with new ones. See API 2 Client for Java - Migrations for more information.

Some methods related to authorization have been deprecated and are now replaced with new ones.

A list of all the updated methods can be found here : API 2 Client for Java - Migrations

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

Replacement of old error codes

Service API 2 Client for Java supports only the new error codes from now on.

List of last replaced error codes:

replaced error codes new error code

com.bosch.ims.authentication.agentcredentials

com.bosch.ims.authentication.agent_credentials

com.bosch.ims.authentication.jwtcredentials

com.bosch.ims.authentication.jwt_credentials

com.bosch.ims.authentication.passwordexpired

com.bosch.ims.authentication.user_credentials.password_expired

com.bosch.ims.authentication.ratelimiting

com.bosch.ims.authentication.rate_limiting

com.bosch.ims.authentication.usercredentials

com.bosch.ims.authentication.user_credentials
com.bosch.ims.authentication.usercredentials.no_password_set com.bosch.ims.authentication.user_credentials.no_password_set
com.bosch.ims.authentication.userexternal com.bosch.ims.authentication.user_external
com.bosch.ims.authentication.userinactive com.bosch.ims.authentication.user_inactive
com.bosch.ims.authentication.userlocked com.bosch.ims.authentication.user_locked

Changes in Service API 1 Client for Java

New artifact names and removal of OSGi support

From now on, the releases of the Service API 1 Client for Java will use new artifact names. The new names will help developers to clearly identify the API 1 Client artifacts:

Old artifact name New artifact name
im-rest-client im-api1-client
im-cf-rest-client im-api1-client-cf

Please update the Maven/Gradle coordinates when you want to update to the latest API 1 Client version.

Find the download links and the Maven/Gradle coordinates at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

The new Service API 1 Client for Java artifacts are no longer OSGi bundles. OSGi will be no longer supported because it was legacy of the old on-premise version which is hardly used today. In case you still need OSGi support we recommend using the latest im-rest-client version.


2018-08 - Self-Service settings

Changes in Service API 2

User self-service settings are provided by tenant information resource

The tenant information resource (https://permissions-api.s-apps.de1.bosch-iot-cloud.com/2/rest-documentation/ > Login user > tenants/{tenant-id}/info) now provides information about the user self-service settings of the respective tenant:

  • Self-registration enabled
  • Password reset enabled
  • Email address verification enabled

It also provides the configured code timeouts for all of these three functionalities. Note that the tenant information resource is still in beta status and might be changed before it is marked as stable.

Data structure of tenant information response body defined

The response body of the tenant information resource has been defined. See the Swagger documentation for details: https://permissions-api.s-apps.de1.bosch-iot-cloud.com/2/rest-documentation/ > Login user > tenants/{tenant-id}/info

Note that the tenant information resource is still in beta status and might be changed before it is marked as stable.

JavaScript based application can keep Bosch ID user logged in

There is a new token-refresh resource which can be used to keep a Bosch ID logged in. It is intended to be used by JavaScript based applications to refresh the values of the ID and authorization token cookies. For more information about JavaScript based application support see: JavaScript support for web applications

Changes in Service API 1 and 2

Trace ID support for Service API 1 and 2

A Trace ID (also known as "Correlation ID") can be provided when an HTTP endpoint of Bosch IoT Permissions is invoked. For details see Tracing.

New Swagger documentation style

The Service API 2 Swagger documentation (REST documentation) has been modernized: https://permissions-api.s-apps.de1.bosch-iot-cloud.com/2/rest-documentation/

Service API 2 Client for Java 1.10 released

A new version of im-api2-client has been released.

The DTO which is returned by the tenant information request has been extended to provide the user self-service settings of the respective tenant.

Find the download links at Developer Guide > Downloads > Client Downloads.

2018-07 - Unlocking via password reset

Changes in Service API 2

This update contains changes to API behavior

New unlocking functionality by resetting the password

A user account may be locked due to multiple login attempts with a wrong or outdated password. A user with such a locked account has now the possibility to "unlock" the account in self-service via password reset functionality. A successful password reset will unlock an account. It will also reset the failed login counter for the user. 

In order to realize this feature the following resources may now also be used by users with a locked account. Before the update this resulted in an error of HTTP 409 Conflict with error code com.bosch.ims.conflict.user_locked:

  • /2/rest/password/reset-code (and its already deprecated counterpart /2/rest/password/resetcode)
  • /2/rest/password/reset-email (and its already deprecated counterpart /2/rest/password/resetemail)
  • /2/rest/password/reset

Enhanced user info resource

The current user information resource provides the tenant ID as well as the privileged state of the user.

Enhanced tenant info resource

The tenant information resource provides the tenant ID in addition to the tenant name.

Changes in Service API 2 Client for Java

Migration required

Configure the expected audience value when parsing tokens. See API 2 Client for Java - Migrations for more information.

The client is able to validate the audience value when a token will be parsed. If the audience check fails an InvalidAudienceException will be thrown. Audience validation is enabled by default and could be deactivated if necessary. The client logs a warning message if the audience validation is enabled but no audience is configured. More information could be found at Developer Guide > API Description > API 2 Client for Java > API 2 Client for Java - Audience validation.

Changes in Service API 1

This update contains changes to API behavior

New unlocking functionality by resetting the password

A user with a locked account has now the possibility to "unlock" the account in self-service via password reset functionality.

In order to realize this feature the following resources may now also be used by users with a locked account. Before the update this resulted in an error of HTTP 400 Bad Request with error code com.bosch.im.service.entity.lockedusermanipulation:

  • /1/rest/password/reset/<userId>
  • /1/rest/password/resetemail

Name of the tenant as placeholder in email templates

The new placeholder ${tenantName} provides the technical tenant name of the tenant the user belongs to. By providing this new placeholder it is possible to support UIs which use the technical name instead of the tenant ID in URLs without adapting the template per tenant.

Changes in the Service UI

A user who authenticates with the Bosch ID will keep his session active in the Administrator UI as long as he does not close the browser or the active Service UI tab.

In previous versions, users authenticated with the Bosch ID were automatically logged out after five minutes when working with the Administrator UI. This happened because the ID tokens issued by the external authentication provider (CIAM) only had a validity of five minutes. Issued Authorization Tokens were stored in the application state of the UI. As the token refresh were not populated to the Administrator UI a logout happened.
Our Administrator UI now uses only the tokens from the cookies. By this the user will stay logged in automatically as long as the browser window or the Service UI tab is not closed.

Service API 2 Client for Java 1.7 released

A new version of im-api2-client has been released.

The QueryUserInfoResponseDto and QueryTenantInfoResponseDto was adjusted to provide the identity provider information of the last given ID Token and the new user and tenant properties. Additionally the audience value of issued tokens could be validated now.

Find the download links at Developer Guide > Downloads > Client Downloads.

2018-05 - Enhanced User Information Resource

Changes in Service API 2

Dropped support for tokens issued by eIDP

As the identity provider system eIDP was replaced by the successor system CIAM (support for CIAM was added in the release 2017-07), we drop the support of accepting tokens at the authorization resource which are issued by eIDP.

User Information Resource provides user information from external identity provider

For users authenticated via external identity providers (currently Bosch CIAM or Google), the user information resource now includes additional profile information which is named "linked profile".
A linked profile is derived from the properties of the ID Token. The linked profile includes the user's identifier provided in the claim sub of the ID Token as well as the email address if it is available. A user's linked profile is updated each time when an authorization is performed with an ID Token from the external identity provider.

The feature is documented at Developer Guide > API Description > Service API 2 > Integration with third-party identity providers

Changed naming of external identity provider IDs

Migration required

Adjust existing REST calls of the Service API 2 as described below.

The IDs of the supported external identity providers have been changed from upper-case to lower-case. This change affects the JavaScript web resource to log in a user with an OpenID Connect flow, which is is currently in beta status.

Migrations

Change path parameter provider

Replace the old provider ID with the new one on the REST calls of the resource /web/openid-connect/{user-tenant}/{provider-id}

The parameter was also renamed from provider to provider-id to unify the naming.

Old provider ID New provider ID
CIAM ciam
GOOGLE google

For details about supported identity providers see Developer Guide >  API Description > Service API 2 > Supported external identity providers

2018-04 - Expiration of Agent Credentials

Changes in Service API 2

Agent Credentials resource accepts an expires-in query parameter

Agent Credentials with a limited time of validity help you to protect your resources the convenient way.

The new parameter in a nutshell:

  • The "expires-in" parameter set while creating the agent credentials, takes care that these get invalidated automatically after the time specified.
  • Expired Agent Credentials will automatically be deleted.
  • If the parameter is not set, the Agent Credentials will never expire.

Changes in the Service UI

A user who authenticates with the Bosch ID will keep his session active as long an he does not close the browser.

In previous versions, users authenticated with the Bosch ID were automatically logged out after five minutes. This happened because the ID tokens issued by the external authentication provider (CIAM) only had a validity of five minutes.
Our Service UI now uses the refresh mechanism of CIAM to issue new ID tokens before the currently used ID token expires. By this the user will stay logged in automatically as long as the browser window is not closed.

Audit Logging

If you are interested in Audit Logging for your tenant please contact service-permissions@bosch-si.com.
The Audit logging feature is experimentally and not productive yet. Audit logs can be written, but an API for downloading such logs is not provided.
For details about the logged data see Developer Guide > Concepts > Audit Logging.

Service API 2 Client for Java

The new version 1.5.0 of im-api2-client has been released.

The new client support the new expires-in parameter for Agent Credentials as described above.

Find the download links at Developer Guide > Downloads > Client Downloads.

2018-03 - Public resources accept tenant name

Changes in Service API 2

Public resources accept tenant name as alternative to tenant id

Migration required

Adjust existing REST calls of the Service API 2 as described below.

The following resources were extended to accept tenant names:

  • /users/registration: the tenant of the user to create can be specified by id or name with the new property user_tenant in the request body. The tenant_id property is deprecated now and should no longer be used.
  • /password/reset-email: the tenant of the user to send a password reset email to can be specified by id or name with the new property user_tenant in the request body. The tenant_id property is deprecated now and should no longer be used.
  • /password/validation: if the password should be validated with the settings of a specific tenant, this tenant can be specified by id or name with the new property tenant in the request body. The tenant_id property is deprecated now and should no longer be used.
  • /tenants/{tenant}/info: the tenant to query can be specified by id or name with the tenant path parameter. This path parameter has been renamed from tid. This rename will not break existing clients.
  • /authentication/{user-tenant}: the path parameter has been renamed from user-tid-or-tn to user-tenant. This rename will not break existing clients.
  • /authorization/{user-tenant-id}: the path parameter has been renamed from user-tid to user-tenant-id. This rename will not break existing clients.

The resources where the request body properties have been deprecated are still in beta status. The deprecated properties will be removed on the next service release.

Migrations

Change request body property names

Replace the old request body parameters with the new ones on the REST calls of the following resources.

Affected resource Old request body property name New request body property name
/users/registration tenant_id user_tenant
/password/reset-email tenant_id user_tenant
/password/validation tenant_id tenant

Changes in Service API 2 Client for Java

Migration required

Replace existing method calls. See API 2 Client for Java - Migrations for details.

The Service API 2 Client for Java has been adjusted to reflect the changes on the Service API 2 which are described above: tenant names are supported as alternative to tenant ids for specific requests. The property and method names have been adjusted to comply with the new request body property names.

Migrations

With this release, some properties and methods of beta requests were marked as deprecated. They will be removed on the next service release.

The migration steps can be found in the Bosch IoT Permissions - Developer Guide > API Description > API 2 Client for Java > API 2 Client for Java - Migrations.

Bugs fixed in Service API 2

Fixed bug which caused application names to get cut if they contained a dot character.

Service API 1 Client for Java 4.35 released

The client could be configured using environment variables. An existent system property based configuration will override the one specified in environment variables. When using im-cf-rest-client the configuration values resolved from the environment variable VCAP_SERVICES may be overridden using system properties or environment variables on an individual basis. See API 1 Client for Java for details.

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.



2018-02 - Self registration in Service API 2

Changes in Service API 2

New resources for the self registration scenario

The new resource /users/registration adds support to perform a self-registration. In contrast to the respective API 1 resource, it is not possible to specify user attributes for the created user with this resource.

The new resource /users/{user-id}/activation-email adds support for sending an activation email for a self-registered user.

Changes in the Service API 2 documentation

We grouped resources based on use cases. By this an API user can see which resources belong logically together to perform specific workflows.

Service API 2 Client for Java 1.2 released

A new version of im-api2-client has been released.

The newly provided resources of Service API 2 can be invoked with the new client.

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

2018-01 - Release 1.1 of API 2 Client for Java

Changes in the service documentation

We merged the documentation for the User Self Service UI into the Sevice UIs documentation. By this all bookmarks related to the User Self Service UI are getting lost. 

We added a new Privacy Leaflet to the documentation. This new documentation covers data protection and privacy topics related to Bosch IoT Permissions. It is provided as an information source for your application specific data protection concept. 

Changes in Service API 2

Migration required

Adjust existing REST calls of the Service API 2 as described below.

New JavaScript resources for performing web requests

Added support for JavaScript based web applications. The stability level of all new resources is BETA.
The following new resources have been introduced:

  • Issue an ID Token as a cookie: /web/authentication
  • Issue an Authorization Token as a cookie: /web/authorization
  • Issue an ID and Authorization Token as cookie: /web/login
    The resource also provides supports for a 'Remember Me' functionality by issuing a 'Remember Me' cookie.
  • Resources for supporting the OpenID Connect Authorization Code Flow: /web/openid-connect/
    After completing the flow, the user gets an ID Token cookie which contains the ID Token of the identity provider and an Authorization Token from the Bosch IoT Permissions Service.
  • Return the current payload of a token which is stored in a cookie: /web/token/

All existing resources accept the cookies issued by the resources above. Existing resources can be protected against CSRF attacks. A CSRF cookie is issued by new resources /web/csrf, /web/authentication /web/login, and /web/openid-connect/callback. CSRF protection can be enabled in the reverse proxy by providing a special header. If that feature is not enabled the solution is responsible for CSRF protection.

Other new features

  • A new User Info resource is provided. This resource currently provides user information based on the UserInfo Endpoint which is defined by the Open ID Connect specification. The resource could be accessed with Authorization Tokens issued by the authorization resource. Currently the resource returns all claims and the resource is currently not aware of claims like "profile" or "email" in the Authorization Token. This might be changed until the resource is declared as stable.
  • Password validation resource has been extended. A new optional property user_id was added to the request body so passwords could be validated in context of a specific user. The resource also validates the given tenant_id or user_id for existence if one is provided.

Changes

Changes at the Agent Credentials resource
  • Creation and deletion of Agent Credentials gained stability level STABLE (former stability level BETA).
  • The resource is now available at path /users/current/agent-credentials (former path /password/agentcredentials).
  • Changed resource such that there are different URLs for delete by ID /users/current/agent-credentials/<agentCredentialsId> and delete by tag /users/current/agent-credentials?tag=<tag>
  • The resource for authentication via Agent Credentials gained stability level STABLE (former stability level BETA).
Changed resource paths
old resource new resource
/publickeys /public-keys
/password/enforcechange /password/enforce-change
/password/resetcode /password/reset-code
/password/resetemail /password/reset-email
/users/{$user-id}/acceptinvitation /users/{$user-id}/accept-invitation
/users/{$user-id}/activationcode /users/{$user-id}/activation-code
/contractingtenants /contracting-tenants

The Public Keys resource available at the path /publickeys has been deprecated and will be removed in one year from this release. The other resources had the stability level BETA and will be removed in one of the next releases.

Changed error codes

The error codes were changed to make them more readable and easier to understand:

old error code new error code
com.bosch.ims.authentication.usermarkedasdeleted com.bosch.ims.authentication.user_deleted
Note: The same error code is used for users which have been moved to trash and users which have been deleted permanently.
com.bosch.ims.authentication.usererased com.bosch.ims.authentication.user_deleted
com.bosch.ims.authentication.clientaccesstoken com.bosch.ims.client_access_token
com.bosch.ims.authorization.missingpermission com.bosch.ims.authorization.missing_permission
com.bosch.ims.authorization.wrongtenant com.bosch.ims.authorization.wrong_tenant
com.bosch.ims.authorization.wronguser com.bosch.ims.authorization.wrong_user
com.bosch.ims.requestdata.constant com.bosch.ims.request_data.constant
com.bosch.ims.requestdata.passwordinvalid com.bosch.ims.bad_request.password_invalid
com.bosch.ims.requestdata.codeinvalid com.bosch.ims.bad_request.code_invalid
com.bosch.ims.requestdata.entitynotfound com.bosch.ims.not_found.*
(* is a placeholder for the type of the object which could not be found, e.g. com.bosch.ims.not_found.user)
com.bosch.ims.requestdata.userlocked com.bosch.ims.conflict.user_locked
com.bosch.ims.requestdata.userinactive com.bosch.ims.conflict.user_inactive
com.bosch.ims.requestdata.userexternal com.bosch.ims.conflict.user_external
com.bosch.ims.requestdata.duplicateentity com.bosch.ims.bad_request.duplicate_entity
com.bosch.ims.requestdata.mediatype com.bosch.ims.bad_request.mediatype
com.bosch.ims.requestdata.url com.bosch.ims.bad_request.url
com.bosch.ims.requestdata.httpmethod com.bosch.ims.bad_request.http_method
REQUEST_DATA.tenantfeaturedisabled com.bosch.ims.conflict.tenant_feature_disabled
REQUEST_DATA.sendemail com.bosch.ims.conflict.send_email
REQUEST_DATA.missingemailtemplate com.bosch.ims.not_found.email_template
com.bosch.ims.internalservererror com.bosch.ims.internal_server_error
com.bosch.ims.internalservererror.dataaccess com.bosch.ims.internal_server_error
New error codes
  • com.bosch.ims.authentication.tenant_feature_disabled
  • com.bosch.ims.authentication.wrong_tenant
  • com.bosch.ims.bad_request.csrf
  • com.bosch.ims.too_many_requests
  • com.bosch.ims.too_many_requests.rate_limiting
  • com.bosch.ims.conflict
  • com.bosch.ims.conflict.user_active
  • com.bosch.ims.not_found.constraint
  • com.bosch.ims.not_found.cookie
  • com.bosch.ims.not_found.opend_id_connect_provider
  • com.bosch.ims.not_found.user
  • com.bosch.ims.not_found.tenant
  • com.bosch.ims.not_found.client_access_token
  • com.bosch.ims.not_found.group
  • com.bosch.ims.not_found.application
  • com.bosch.ims.not_found.offering_type
  • com.bosch.ims.not_found.permission
  • com.bosch.ims.not_found.role
  • com.bosch.ims.not_found.entity_relation
  • com.bosch.ims.not_found.agent_credentials
Other changes
  • Some response errors contained a property cause. As error codes are used for the concept to define a specific error handling for different causes the property cause have been removed.

  • The property user_name has been removed for the error code com.bosch.ims.authentication.usercredentials.
  • The property agent_credentials_id has been removed for the error code com.bosch.ims.authentication.agentcredentials.
  • The property password_expiration_enforced has been renamed to is_password_expiration_enforced for the error code com.bosch.ims.authentication.passwordexpired.
  • The property entity_name has been renamed to permission_name for the error code com.bosch.ims.authorization.missing_permission.
  • The error responses with the error codes com.bosch.ims.not_found.* now provide one of the following properties: id, name, or tag. The property value contains the identifier which has been used to query the object which has not been found. The property entity_name is not provided anymore.

Bugs fixed in Service API 2

  • User activation resource does not send rate limiting error code and wait time although there is a rate limiting
  • Fixed an issue that prevented to create an Authorization Token with the right permissions for an Act on Behalf relation between a service tenant and a child of that service tenant.

Planned changes in Service API 2

Migration required

When accessing the Service API 2 without the Service API 2 Client for Java and you evaluate the error codes it is required to recognize both error codes till Service API 2 returns only the new error codes.

Complete the migration until 31.03.2018.

To unify the error codes it is planned to rename some error codes in one of the next releases. The new released Service API 2 Client for Java supports the old and the new error codes. The following error codes are affected:

current error code new error code

com.bosch.ims.authentication.agentcredentials

com.bosch.ims.authentication.agent_credentials

com.bosch.ims.authentication.jwtcredentials

com.bosch.ims.authentication.jwt_credentials

com.bosch.ims.authentication.passwordexpired

com.bosch.ims.authentication.user_credentials.password_expired

com.bosch.ims.authentication.ratelimiting

com.bosch.ims.authentication.rate_limiting

com.bosch.ims.authentication.usercredentials

com.bosch.ims.authentication.user_credentials
com.bosch.ims.authentication.usercredentials.no_password_set com.bosch.ims.authentication.user_credentials.no_password_set
com.bosch.ims.authentication.userexternal com.bosch.ims.authentication.user_external
com.bosch.ims.authentication.userinactive com.bosch.ims.authentication.user_inactive
com.bosch.ims.authentication.userlocked com.bosch.ims.authentication.user_locked

Changes in the Service UI

It is now possible to delete Client Access Tokens via the service UI.

Service API 2 Client for Java 1.1 released

Migration required

Replace existing classes and method calls. See API 2 Client for Java - Migrations for details.

A new version of im-api2-client has been released.

Methods which are not stable yet, are marked with the annotation Beta.

New supported features

  • The client could be configured automatically by binding to a cloud foundry user provided service. See API 2 Client for Java - Configuration for details.
  • New exception class com.bosch.im.api2.client.exception.server.ClientAccessTokenException was introduced to map the error code com.bosch.ims.client_access_token.

Migrations

This release contains some breaking changes to the previous beta version. The migrations steps could be found in the Bosch IoT Permissions - Developer Guide > API Description > API 2 Client for Java > API 2 Client for Java - Migrations.

Service API 1 Client for Java 4.32 released

The client could be configured automatically by binding to a cloud foundry user provided service. See API 1 Client for Java for details.

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.


2017

2017-11 - New factory methods in API 2 Client for Java

New Service URL for BIC 2.0

To get rid of BIC 1 service URLs it is highly recommended to upgrade the Service API Clients to the latest release as well as to replace all manually configured service URLs in BIC environment variables or configuration files.

Migration required

The old value https://permissions-api.apps.bosch-iot-cloud.com must be replaced with https://permissions-api.s-apps.de1.bosch-iot-cloud.com. In case you are using the binding mechanism of BIC the new URL is provided automatically.

Browser bookmarks to the management console of the Bosch IoT Permissions Service or any other page like deep links to the documentation must be updated to the redirected URLs. If the DNS mapping for the old BIC 1 URL is removed, all non migrated bookmarks will not work anymore.

Currently there might be some issues related to SSL with the new service URL. Have a look into the System Requirements how to fix it.

User invitation works together with CIAM "Login with Bosch"

If you have integrated "Login with Bosch" in your application, you can now also implement an invitation workflow for users with CIAM Bosch ID accounts. The resource /users/{user_id}/acceptinvitation has been extended, to accept a CIAM Bosch ID token. With a request to this resource, the CIAM Bosch user is linked to the invited user in Bosch IoT Permissions. A description of this workflow and the relevant API resources can be found in the Developer Guide, at section Implementing an invitation workflow.

New SPoI subscription endpoint

Related to the migration of the service to BIC 2.0, the SPoI registration must be updated. The new subscription endpoint is "BOSCH IOT PERMISSIONS (DE1)".

If you are a Bosch employee and you are not yet registered for SPoI messages, subscribe to the SPoI endpoint to get automatically informed about new updates.

Migration required

Update your subscription for the new SPoI endpoint.

When providing a token from an external identity provider, the audience claim is verified

As announced in the update notes 2017-09 - Login with Bosch and Google the client ID verification was activated on the service. When your client tries to access resources of Service API 2 with tokens issued by Google and CIAM, it will now be rejected, if your external identity provider client ID was not configured at your tenant.

This change improves security for tenants because they are able now to accept only users which are authenticated by Google or CIAM with their registered client ID. The registration of no client IDs empowers solutions or project to explicitly disallow the creation of Bosch IoT Permissions users entities if they don't want to accept authentications via external identity providers.

This is how you can configure your external identity provider client ID:

Click on the image to see how this dialog can be opened.

Changes in Service API 1 and 2

There is a behavior change in the validation of the Service API 2 Authorization Tokens. Tokens will only be accepted by both APIs if the user for whom the token was issued is not erased and not in the marked as deleted status. This change prevents some unexpected behavior that deleted or erased users are still able to perform operations which do no affect themselves. Typically this change should not affect you.

Changes in Service API 2

  • The already deprecated change password PUT resource has been removed. It was replaced with an according POST method.
  • The tenants information resource was refactored to group tenant settings. This improves the usability of the resource.

Service API 1 Client for Java 4.31 released

A new version 4.31 of im-rest-client has been released.

The constant ImServiceEndpoint.BIC_EU is going to be deprecated and will be removed in one of the next releases. Use the constant BIC_DE1 instead.

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

Service API 2 Client for Java 1.0-beta7 released

A new version of im-api2-client has been released.

The new class Permissions is the new entry class to Service API 2 Client. It provides factory methods to create configuration builders as well as methods which are able to create clients without the necessity to call a builder.

This release contains some breaking changes to simplify the client initialization and to support static imports. The following changes must be applied.

  • The client and configuration builders were moved to the package builder. Update your package references by organizing your imports.
  • The static initialization methods were moved to a single central class Permissions. This allows you to import the new methods in a static way.
    • IClientBuilder.newInstance() must be replaced with Permissions.createClientBuilder().
    • IClientConfigurationBuilder.newInstance() must be replaced with Permissions.createClientConfigurationBuilder().
    • IProxyConfigurationBuilder.newInstance() must be replaced with Permissions.createProxyConfigurationBuilder().
    • IIssuerConfigurationBuilder.newInstance() must be replace with Permissions.createIssuerConfigurationBuilder().

There are additional breaking changes in the TenantInfoDto. The TenantInfoDto was refactored. New methods must be invoked to access the tenant settings.

The constant ServiceEndpoint.BIC_EU is going to be deprecated and will be removed in one of the next releases. Use the constant BIC_DE1 instead. This change simplifies the usability because DE1 is part of the domain name of the first BIC installation in Germany.

Migration required

Use the new classes and methods to initialize the client.

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

2017-09 - Service API 2 Client for Java allows to override client configuration properties

New release of Service API 2 Client for Java

A new version 1.0-beta6 of im-api2-client has been released. By this release it is possible to override all client configuration properties with environment variables and system properties.
See the section Developer Guide -> API 2 Client for Java - Configuration for more details.

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

Deprecation of Servlet Utils

The servlet utils were part of IM3 version 3.x (Maven Group ID: com.bosch.im, Artifact ID: im-servlet-util). The jar was not published to the public maven repository. The servlet util classes are not relevant for the Bosch IoT Permissions service and are deprecated, now.

2017-09 - Login with Bosch and Google

Changes in the Bosch IoT Permissions Service UI

Login via Bosch and Google via the Service UI

Up to now, only users originated from the IoT Permissions Service could log in at the Service UI. Now, users originated from Bosch are able to login with their Bosch-ID as well as users from Google who can perform self-service functions and administrative tasks.

In the Administrator UI it is possible to access tenant settings to allow or to deny a Login for each supported identity provider. By default the login via Bosch is enabled on each tenant. Google must be activated explicitly. You can activate or deactivate the providers with new tenant settings (See below: "New tenant specific settings to control acceptance of identity provider tokens").

The section "Sign in with external account" will only be displayed if a tenant ID is given via the imtid URL parameter.

Display tenant name on the Service UI login dialog

As displayed on the screenshot above the tenant name will be displayed on the Service UI login dialog if a tenant ID was given via the imtid URL parameter.

Permissions for users who signed in with Bosch or Google

Please be aware, that users who sign in with a Bosch or Google account for the first time, have only the Permissions offered via the All Users Group inside the Tenant by default. You need a second user (e.g. your initial Admin account) to assign permissions to a new user who signed in with an external account (highlighted in screenshot below).

Changes in Service API 1 Client for Java

Deprecation of obsolete classes

Some classes which are no longer needed have been marked as "deprecated" and will be removed with one of the next releases. The functionality that these classes belong to has never been activated on the IoT Permissions Service. Hence, projects using the Service API 1 Client for Java will probably not use or reference them.

List of deprecated interfaces, classes and methods:

  • Method com.bosch.im.command.ICommandFactory.queryExternalIdentityProviderConfigurations()

  • Method com.bosch.im.model.IUser.getExternalIdentityProviderType()

  • com.bosch.im.command.commands.IQueryExternalIdentityProviderConfigurationCommand

  • com.bosch.im.model.IExternalIdentityProviderConfiguration

  • com.bosch.im.model.ExternalIdentityProviderType

  • com.bosch.im.authentication.OpenIdConnectCredentials
  • com.bosch.im.identityprovider.IdentityProviderCommunicationException 

Changes in Service API 1

Deprecation of obsolete types in the IM schema definition

The following types are deprecated and will be removed from the im.xsd file with one of the next releases:

  • AbstractExternalIdentityProviderConfigurationType

  • OpenIdConnectIdentityProviderConfigurationType

  • OpenIdConnectIdentityProviderConfiguration
  • OpenIdConnectAuthenticationType

Changes in Service API 1 with impact on Service API 2

New tenant specific settings to control acceptance of identity provider tokens

Currently the authorization resource of Service API 2 generally accepts tokens of Bosch CIAM and Google. Hence, users from those identity providers could log in at each tenant.

In order to allow tenant administrators to control whether users of identity providers are allowed to log in at their tenants, new tenant specific settings were introduced. These tenant settings allow to specify which client IDs should be accepted per identity provider. They can be configured in the IoT Permission's administrative UI (see screenshot below) or via the tenant settings resource of Service API 1.

To give tenant administrators time to configure their client IDs of the identity providers, the Bosch IoT Permissions Service API 2 authorization resource does not yet enforce these tenant settings. But it will do it in the future, denying all authorization attempts using identity provider tokens with client IDs not explicitly allowed in the tenant specific settings.

Migration required

We strongly advise all clients using CIAM or Google as identity providers to configure their client IDs of the desired identity providers now.

The Service API 2 authorization resource will be updated soon to activate client ID verification. If no client IDs are configured then, all login requests with Bosch or Google tokens will be denied!

New release of Service API 1 Client for Java

A new version 4.28 of im-rest-client has been released.

With this release, it is possible to use all printable ASCII characters in a username. The service API does already allow this since the last update in 07/2017.

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

  • API 1 Client for Java in version 4.28

2017-08 - Routes starting with im3 will be shut down

Routes starting with im3 will be shut down on 01.09.2017

The Bosch IoT Permissions service is currently reachable under the base URLs

In addition these routes are currently available, but will be shut down on 01.09.2017:

  • im3-api.apps.bosch-iot-cloud.com
  • im3.apps.bosch-iot-cloud.com
  • im3-self-service.apps.bosch-iot-cloud.com
  • im3-admin.apps.bosch-iot-cloud.com

The route for the "IM3 JS Support API" will be shut down on 15.09.2017:

  • im3-js-api.apps.bosch-iot-cloud.com

Please check if you are using any of these im3 routes. If so, switch to the permissions routes which are listed in the detailed instructions below. The service functionality is not affected by this change.

Detailed instructions
  1. If you use the Cloud Foundry Service Binding mechanism, check your service Binding. If it contains im3-api.apps.bosch-iot-cloud.com you MUST rebind and restart your app until 01.09.2017.
    Go into the Cloud Foundry developer console and click on the "Env Variables" tab of your app. Search for the key named "im3-service". If it looks as in the following screenshot, you have to rebind and restart your app.

  2. If you aren't using the binding mechanism in your application, check which URL endpoint your are actually using. If it is im3-api.apps.bosch-iot-cloud.com you need to switch to https://permissions-api.apps.bosch-iot-cloud.com 
  3. Update any bookmarks or any links inside your UI code, which point to the old routes:
    im3-api.apps.bosch-iot-cloud.com -> https://permissions-api.apps.bosch-iot-cloud.com
    im3-js-api.apps.bosch-iot-cloud.com -> https://permissions-api.apps.bosch-iot-cloud.com/js
    im3.apps.bosch-iot-cloud.com -> https://permissions.apps.bosch-iot-cloud.com
    im3-self-service.apps.bosch-iot-cloud.com -> https://permissions.apps.bosch-iot-cloud.com/self-service
    im3-admin.apps.bosch-iot-cloud.com -> https://permissions.apps.bosch-iot-cloud.com/admin
Reason for this change

When the service migrates to BIC 2.0, the permissions.apps and permissions-api.apps route will be kept. The older im3 routes will not work any more, as soon as Bosch IoT Permissions service is running on BIC 2.0. Therefore it is required to switch to the stable routes until September 2017.

2017-07 - CIAM Token Support

New functionality in Service API 2

Bosch Customer Identity & Access Management (CIAM) Token Support

Bosch IoT Permissions now accepts an ID token from CIAM system for authentication. Tokens from the former eIDP system are still supported. This functionality is described in the Developer Guide: Integration with third-party identity providers

Please be aware, that tokens from CIAM D-system (the system used for tests) are not accepted.

New functionality in Service API 2 Client for Java

A new version 1.0-beta3 of im-api2-client has been released.

New version of Jackson used

The API 2 Service Client now depends on jackson-databind version 2.8.9 (was 2.5.1)

Issuer claim validation

The API 2 Service Client now validates the issuer claim of the Bosch IoT Permissions id tokens and authorization tokens. The issuer validation is always enabled. It works without the need for any changes for clients configured to run against the service on BIC 1 or AWS

Migration to im-service-client im-api2-client 1.0-beta3

The expected issuer needs to be configured for Clients which work against other endpoints than BIC1 or AWS (e.g. against BIC2 test-temp service instance or the Docker SDK). Find a description how to configure the client at the Developer Guide: API 2 Client for Java - Configuration

If you are running the client against the "BIC 2.0 test-temp" Bosch IoT Permissions service, you need to configure the following values:

im_authentication_issuer = https://permissions-test-temp.apps.bosch-iot-cloud.com/authentication
im_authorization_issuer = https://permissions-test-temp.apps.bosch-iot-cloud.com/authorization

Changes in Service API 1 and Service API 2

More special characters allowed in usernames

Up to now, @ and . were the only allowed special characters in usernames (additional to the alphabetic and numeric characters). The username restrictions have been relaxed so that all printable ASCII characters are allowed. These are the characters between 0x20 and 0x7E (see https://de.wikipedia.org/wiki/American_Standard_Code_for_Information_Interchange).

Most email addresses can now be used as usernames - only email addresses with non-printable ASCII characters and non-ASCII characters are not supported.


2017-06 - User Invitation and Identity Context refresh

New documentation design and functionality

We are happy to present our documentation in the new Bosch brand style. Apart from the bright colors we hope you enjoy the “infinite scrolling”, which offers an efficient way to browse our pretty large amount of information, without having to wait for pages to pre-load.

What is more: you are now able to bookmark a deep link, to easily share the information, or to find it again, at a later point in time.

Enjoy, and let us know about how you experience the new style.

New functionality and changes in Service API 2

User invitation

The API provides a new resource /users/invitation to realize an invitation process. Invitation means, that an administrator for user entities is able to create a new user with only a minimal amount of information (e.g the email address) and is able to assign roles and groups to the user. The invited user receives the user ID together with an activation code. With this information the user is able to complete the invitation by providing his self defined user name and password and maybe together with use case specific data.

Find a description how an invitation process could be implemented in detail at Developer Guide > Implementing an invitation workflow.

Enforce a password change

The API provides a new resource /password/enforcechange to force a user to change the password at the next login.
The new functionality is also provided at the Administration UI when displaying user's the details (see Service UIs > Update User). This is the trigger where an administrative user can actually apply such an password change enforcement.

The Service API 2 Client for Java also implements this new feature.

Change password resource: HTTP method changed from PUT to POST

The HTTP method has been changed from PUT to POST for the change password resource.

The PUT method is deprecated now and will be removed in one of the next releases. The new client release uses the new POST resource.

Changes at the Service API 2 Client for Java

Support for proxy authentication

The client provides a new API to configure proxies which require authentication.

Find a description how to configure the client for proxy authentication at Developer Guide > API 2 Client for Java.

Replaced Unirest with Async HTTP Client

The client implementation was built on top of Unirest and the Apache HTTP Client API. As Unirest does not support proxy servers which require authentication, we needed to switch to another API which supports this. The new base API of the client is the Async Http Client.

Support for client initialization in a try-with-resource statement

The interface IAnonymousClient extends the AutoClosable interface. By this it is possible to initialize the client in a try-with-resource statement. The client will be closed automatically if the block statement is completed no matter if the code block throws an exception or not. An example initialization with a try-with-resource statement might look like this. For an example have a look into the Javadoc of class IClientBuilder.

If you already invoked the destroy method of the client, you will need to call close now.

New functionality in Service API 1

Support for refreshing an Identity Context

The new API offers the possibility to refresh an Identity Context without the necessity to hold the Basic Credentials of the user. For a detailed description for the new concept Identity Context Refresh Token at Developer Guide > Identity Context Refresh Token.

User self-service related functionality is now configurable per Tenant

User self-service related functionality can now be controlled with new tenant settings:

  • User self-registration enabled
  • Password reset enabled
  • Verified email address update enabled
  • User activation code timeout
  • Password reset code timeout
  • Verified email address update code timeout

See Self-service related settings for details. These properties can be set via the Service API 1 tenant settings resource.

Further, the Administrative UI now offers a new Self-Service Settings dialog to configure these settings.

 

For all existing tenants the self-service settings are initially set to meaningful values, depending on the existence of email templates for the respective functionality. E.g. if a password reset email template is configured for a tenant, the password reset functionality is enabled in the tenant-specific self-service settings.

Changes at the Service API 1 Client for Java

Detailed exception types for self-service related resources

New exceptions were introduced for user self-service related commands to report error cases more precisely.

Find details which exceptions could be thrown in the Javadoc of the classes:

  • ICreateSelfRegisteredUserCommand

  • ISendActivationEmailCommand

  • ISendPasswordResetEmailCommand

  • IUpdateEmailAddressWithVerificationCommand

Client Updates

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

  • API 2 Client for Java in version 1.0-beta2
  • API 1 Client for Java in version 4.23


2017-04 - Self-Registration enhanced and other changes

New stability level Beta replaces Alpha

To unify the stability level between the APIs of Bosch IoT Suite services we changed the name from Alpha to Beta. There is no change in the definition of this stability level, only the name has been changed. The API 2 Client for Java will therefore be released with the version postfix beta.

New functionality in Service API 2

Support of further channels for user self-service

Bosch IoT Permissions uses emails to notify users for self-registration and password reset purposes. But in some scenarios an email is not the desired way to notify a user. E.g. there could be requirements to notify users by SMS or by letter.

For such scenarios, new REST resources have been added at Service API 2. These allow to generate and retrieve user activation codes and password reset codes. Such codes can be sent to a user by any project specific mechanism. Upon user confirmation, they can be used to activate users and to reset passwords (in the same manner as if they were sent by Bosch IoT Permissions via email).

An example workflow description can be found in the developer guide, in section "Support other channels than email for account activation or password reset".

Support deletion of Agent Credentials via reference key

The DELETE operation of the Agent Credentials resource supports also to delete by reference key (in the previous release it was named reference ID). By this it is possible to easily implement a scenario like Remember Me to automatically authenticate a user after a session expiration. A description, how to implement such functionality, can be found in the developer guide, in section "Utilizing Agent Credentials for a "Remember Me" functionality".

New functionality in Service API 1

Possibility to specify self-service related properties per tenant

A new type of tenant-specific settings has been added to define self-service configuration.

This configuration includes the following properties:

  • User activation code timeout
  • Email address confirmation code timeout
  • Password reset code timeout

A new dialog has been added to the Administrative UI which allows to edit these properties. It can be opened with the "Edit self-service configuration" button in the "Tenant" dropdown menu.

Changes at the Service API 2 Client for Java

Support of new self-service resources

Added support for the newly introduced activation code and password reset code generation resources.

Replaced Date by Instant

With Java 1.8 the new immutable class java.time.Instant has been introduced as an improved alternative to the mutable class java.util.Date. We updated the DTOs of the Service API 2 Client to replace usage of Date by Instant.

This change affects the properties issuingDate and expirationDate of an IJsonWebToken. The deriving types IAuthorizationToken, IChangePasswordToken, and IIdToken are also affected.

If you access these properties of the mentioned token classes, you must update your code as well. If you need to convert an Instant to a Date, you can use the  java.util.Date.from(Instant) factory method.

Renamed method for erasing Agent Credentials

In conjunction with the support of erasing Agent Credentials via reference key, the method agentCredentialsId of the interface IEraseAgentCredentialsRequest was renamed to agentCredentialsIdOrReferenceKey.

Client Updates

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

  • API 2 Client for Java in version 1.0-beta1
  • API 1 Client for Java in version 4.22

2017-03 - New registry for Docker images

The Docker images for our Bosch IoT Permissions SDK have been moved to the new Bosch Docker Trusted Registry as of March 22th 2017.

https://rb-dtr.de.bosch.com/orgs/iot-permissions/repos

Login at Bosch Docker registry works with your Bosch NT user. To get access, please refer to instructions at the Bosch Connect community "Container as a Service Platform".

Please note however, that the Bosch IoT Permissions service software - including the Docker images - is not provided as licensable product.
Thus, there will be no liability for productive usage of the Docker images.

Find details in our Developer Guide > Docker Images - Developer Package.

2017-03 - Agent Credentials for Service API 2

With the latest release it is possible to create, delete, and use Agent Credentials. Agent Credentials are a new concept for Service API 2 and is the successor for API Keys from Service API 1.

Agent Credentials
An Agent Credential is a secret token which a user can generate for himself using the Service API 2. The user can give Agent Credentials to applications that should act on behalf of him, thus eliminating the need to authenticate via user name and password. While creating the Agent Credential the user defines a sub-set of his roles and permissions by defining the applications and scopes that should be bound to the Agent Credentials.

The authorization resource of Service API 2 provides a new feature to accelerate the expiration date of an Authorization Token. The old behavior to use the expiration date from the provided ID Token is the default behavior if no accelerated expiration is given. It is not possible to create Authorization Tokens with an extended expiration than the one defined by the given ID Token.

To simplify the usage of API 2 Client for Java we performed some breaking changes:

  • As we are expecting the client to grow in functionality we started to categorize the request factory methods on the client interfaces. Only methods related to the resources password and applications are affected by this change. 
    This results in the following example change: client.validatePassword() must be replaced with client.password().validate().
  • Together with the grouping we reorganized the Java package which contains the request interfaces to match the factory methods.
    This may result in a change that you have to organize your imports. If you are using method chaining you don't have imports to the request interfaces and no change must be done. 
  • The method names to set a DTO to a request was renamed for all requests to dto.
    This results in the following example change: client.validatePassword().validatePasswordDto(validatePasswordDto) must be replaced with client.password().validate().dto(validatePasswordDto).
  • The method IAuthorizationToken.getAuthenticationInformation() returns an empty Optional value instead of null if the claim AuthorizationClaim.orig was not provided by the Authorization Token.
    If you are using the method and you perform a check for null, change it to one of the Optional methods to handle the null case.
  • The method InvalidUserCredentialsAuthenticationException.getUserName() returns an empty Optional value instead of null if no name of the user was provided by the error response.
    If you are using the method and you perform a check for null, change it to one of the Optional methods to handle the null case.

Bugs fixed

  • [IM-5720] - Chrome should not cache documentation frames
  • [IM-5738] - Authorization resource should not accepts eIdP tokens without the claim sub

Improvements

  • [IM-5014] - User scoped Authorization Token can be created with an Agent password (Successor for API 1 Api Key)
  • [IM-5725] - Move DTOs of the Password Resource to the password package
  • [IM-5728] - Group IRequests and their collections to a proper package
  • [IM-5729] - IAuthorizationToken.getAuthenticationInformation() should return an Optional
  • [IM-5732] - InvalidUserCredentialsAuthenticationException.getUserName should return an Optional
  • [IM-5737] - Swagger docs refer to related API 2 Client methods

Client Updates

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

  • API 2 Client for Java  in version 1.0.alpha10

2017-02 - Application registration without tenant ID

With the new Service API 2 it is possible to register an application without specifying the target tenant ID. The tenant ID of the currently logged in user will be used. This change causes some changes in the DTOs of the API 2 Client for Java. Updating it could therefore cause some easy to fix compile errors.

Bugs fixed

  • [IM-5640] - Password reset fails if password history length policy is getting disabled
  • [IM-5374] - First password change not possible if a login cookie is present
  • [IM-5625] - API 2 Client for Java - When chaining multiple remote invocations via a CompletableFuture in the same thread the thread is blocked

Improvements

  • [IM-5573] - API 2 Client for Java - Application registration without tenant ID in the payload
  • [IM-5626] - API 2 Client for Java - Map com.bosch.ims.authorization to PermissionDeniedException in API 2 Client
  • [IM-5627] - API 2 Client for Java - A new method andCreateAuthorizedClient was introduced on the IAuthenticationRequest to simplify the creation of an IAuthorizedClient.

Client Updates

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

  • API 2 Client for Java  in version 1.0.alpha9

2017-01 - Service improvements regarding Application Management

The major changes of this update address the Service API 2 and the "Application Management" processes.

Service API 2 was enriched with three new resources to register/migrate, erase, and query an application. The functionality is also supported by the new API 2 Client for Java.

Also the compatibility between Service API 1 and Service API 2 was improved. Service API 1 is able to create an Identity Context out of a Service API 2 Authorization Token. This feature should only be used if you invoke third-party services which invoke the Service API 1 and expect an Identity Context ID to be present on service invocations. This feature could be used as a workaround if these third-party services could not be migrated to Service API 2.

The API 2 Client for Java was also enriched with a functionality to be instantiated without a Client Access Token. By this it is possible to use the client also for scenarios where it is only required to validate provided tokens. The requirement to provide a Client Access Token for querying the Service API 2 public keys was removed to support this scenario.

Service API 2 changes

Removed Deprecations in Service API 2

The resources "/authentication" and "/authorization" have been available with HTTP GET and POST.
With this update, these resources are available only with HTTP POST for better future extensibility.
The usage of HTTP GET for these resources is not supported anymore. This removes the deprecations announced in 2016-10 - Service improvements regarding Password Reset and new API 2 Client version.

Improvements

  • [IM-4999] - API2 Application registration
  • [IM-5535] - Map com.bosch.ims.internalservererror to InternalServerErrorException in API 2 Client
  • [IM-5259] - An IdentityContext can be created when an API 2 Authorization Token is available
  • [IM-5442] - API 2 Public Key resource accessible without Client Access Token
  • [IM-5481] - Adapt instantiation of im-service-client without Client Access Token

Client Updates

Find the download links at Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

  • API 1 Client for Java in version 4.19 
  • API 2 Client for Java  in version 1.0.alpha8

2016

2016-11 - First stable Service API 2 resources and token issuers changed

New

The Service API 2 documentation was enriched by information regarding the Service API 2 stability level.

At the same time part of the resources of Service API 2 have now become stable. The stable resources are labeled accordingly in the API 2 resource documentation: https://permissions-api.apps.bosch-iot-cloud.com/2/rest-documentation

Service API 2 changes

Breaking changes in Service API 2

The issuer value of the JWT tokens issued by Service API 2 have changed.

The new issuer values are:

  • https://permissions.apps.bosch-iot-cloud.com/authentication (issued by authentication resource)
  • https://permissions.apps.bosch-iot-cloud.com/authorization (issued by authorization resource)
  • https://permissions.apps.bosch-iot-cloud.com/passwordchange (issued by authentication resource in case of a required password change)

Update steps

In case you have implemented checks which ensure that the issuer value of the JWT tokens is the expected one these checks need to be adapted to expect the new issuer values.

Bugs fixed

  • [IM-5393] - User creation for external token fails (=> Improved approach for uniqueness of usernames)
  • [IM-5313] - Querying ApiKeys which have no role or permission fails

Improvements

  • [IM-5399] - Provide possibility to create Tenant Role including UUID for migration

2016-10 - Improved exception responses for Service API 1 and 2

New

The major changes of this update address the Service API 1 and 2 regarding exceptional response messages.

Bugs fixed

  • [IM-5100] - Malformed authentication request XML causes a HTTP 500 instead of 400
  • [IM-5357] - User self-registration in a subtenant fails

Improvements

  • [IM-5198] - Handle generic errors in Service API, so that response is in defined JSON error format

2016-10 - Service improvements regarding Password Reset and new API 2 Client version

New

The major changes of this update address the Service API 2 and the User Self-Service UI regarding the "Reset Password" process.

Service API 2 was enriched with two new resources to send a password reset email and to reset the password. Service API 2 supports all use cases now to implement a custom login dialog, to handle login errors which require a password change as well as the option to reset a password.

Service API 2 changes

API 2 is in alpha state and still evolving. However, we plan to define the token resources and the public key resource as stable resources, soon.

Breaking changes in Service API 2

Please be aware that the Service API 2 public key response format changed. The modulus and exponent value of the public key were Base64 encoded. With the update, these values are Base64 URL encoded. This is the encoding defined by the JWK standard.

Update steps
  • If you use the public key resource "/publickeys", adapt your decoding logic to decode Base64 URL values.
  • If you use the API 2 Client for Java, there might be runtime errors when validating the public key. Please update to the latest client version 1.0.alpha6.jar.
Deprecations in Service API 2

The resources "/authentication" and "/authorization" were available with HTTP GET. With this update, these resources are available with HTTP POST for better future extensibility. The usage of HTTP GET for these resources is now deprecated and will be removed in a service update in November 2016.

Update steps
  • Use HTTP POST instead of GET when issuing requests to the "/authentication" or "/authorization" resource. There is no body data required. The supported parameters are still the same and are still provided as URL query parameters.

Bugs fixed

  • [IM-5270] - Password change should use correct validation settings for privileged users
  • [IM-5273] - Public keys should be Base64 URL encoded

Improvements

  • [IM-4546] - Restrict tenants by client access token for self-registration scenarios
  • [IM-5036] - Password reset is provided in API2
  • [IM-5145] - Improve performance for authorization via Service API 2
  • [IM-5260] - Improve performance by removing count distinct and select distinct when querying entities
  • [IM-5271] - Use HTTP Post for API 2 authentication and authorization endpoints

Client Updates

You can find the download links for all artifacts in version 1.0.alpha6 at:  Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

2016-09 - Service improvements regarding Change Password and new API 2 Client version

New

The major changes of this update address the Service API 2, the User Self-Service UI, and the Administrator UI regarding the "Change Password" process.

With Service API 1 there was an issue with missing information of the user for a password change in case the password was expired or an initial password change had to be done. Service API 1 was therefore improved that these error responses contain additional information about the user like the privileged state and the tenant ID the user belongs to.

Service API 2 was enriched with two new resources to validate and to change the password. The validate password resource works similar to the one from Service API 1. The change password resource introduces a new token type - the Change Password Token. This token will be created by the service and is part of the error response in case the given password is expired or an initial password change is necessary. This token contains some data about the user and can be used as alternative to an Authorization Token at the change password resource.

Service API 2 Breaking Changes

API 2 is in alpha state. Please be aware that the Service API 2 generic error response format changed. The new format is documented at  in the Developer Guide at Bosch IoT Permissions - Developer Guide > API Description > Service API 2 > REST Response Format.

If you use an API 2 Client for Java, there might be compile errors when updating the version or some run-time errors while converting an error response to an ErrorMessageDto. Please update to the latest client version 1.0.alpha5.jar in this case.

Beside the change of the error response format there are no other breaking changes.

Bugs fixed

  • [IM-5158] - Wrong task description on change password dialog
  • [IM-5226] - Users are able to change the "from" email address in the templates which is not supported by the IoT Permissions service 
  • [IM-5233] - Unable to login via eIDP ID token because multiple usernames are registered at eIDP for the same user

Improvements

  • [IM-5234] -  Add privileged flag to list of email template placeholders

Client Updates

You can find the download links for all artifacts in version 1.0.alpha5 at:  Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

2016-08 - Usage of API 2 in Bosch IoT Permissions dashboard and dual-location HA

New

The main change addresses the usage of the authentication and authorization functionality of Service API 2 for our Bosch IoT Permissions dashboard, including the Administrator UI, User Self-Service UI etc.

We have also scaled up our services to ensure that at least one instance is running at both BICS data center locations.

Regarding API 2, we have increased the length of the public key to 2,048 bits in compliance with the JWK specification (https://tools.ietf.org/html/rfc7517).

Improvements

  • [IM-5108] - Reflect unique application names in API Key management UI

Bugs fixed

  • [IM-5119] - The contracting tenants delivered by API 2 are not always correct

2016-07 - Service improvements and new API 2 Client version

New

The main change addresses Service API 2. While the former version supported only to authenticate via username, password and tenant ID, from now on, you can also authenticate by providing the username, password and tenant name. The API 2 Client for Java also allows to communicate via a proxy server with the server. A proxy server can be configured via the system properties http.proxyHost and http.proxyPort.

Improvements

  • [IM-4842] - Unify token access
  • [IM-4880] - Adapt audience claim value to contain client ID
  • [IM-4990] - API2 client works with a proxy
  • [IM-5022] - Ensure that queries by a user who has access to more than 1000 tenants are possible
  • [IM-5023] - Improve query "single user by id" by a user who has access to multiple tenants

Bugs fixed

  • [IM-4836] - Invalidate of IdentityContext does not work as expected.
  • [IM-4977] - Groups not always part of IdentityContext
  • [IM-4988] - Redirect from Login Dialog does not work with Firefox

Client Updates

You can find the download links for all artifacts in version 1.0.alpha3 at:  Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

2016-06 - Service improvements and new API 1 Client version

Authentication resource - Service API 1

The Bosch IoT Permissions service update comes with the possibility to create an Identity Context, but pass only the context ID to other applications.

Find details on how to use the  idOnlyResponse parameter at: Bosch IoT Permissions - Developer Guide > API Description > Service API 1 > REST Resources overview > Resources related to authentication > Authentication Resource.

User self-registration

We also worked on the experience of the user self-registration.
The administrative user interface now enables you to change the behavior of the UI for the end-user.
Thus, in case an end-user needs to confirm his registration (in order to activate his account), instead of being redirected to our Bosch IoT Permission specific login page he just gets the message that his account was activated successfully.

Details on how an administrative user can activate this feature, especially such an "Activation link with suppressed redirect example" can be found at: Bosch IoT Permissions - Developer Guide > API Description > Service API 1 > Email template > Constructing links in templates.

Client Updates

The API 1 Client for Java was improved regarding its performance and the Cloud Foundry integration.

You can find the download links for all artifacts in version 4.11 at:  Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

2016-06 - New API 2 Client for Java

The Bosch IoT Permissions service team is proud to announce the first Java Client for the new Service API 2.

  • This client can be used for an easy integration of the Bosch IoT Permissions Service API 2 into your Java applications.
  • It provides a synchronous and an asynchronous Java API to authenticate and authorize your Bosch IoT Permissions users.
  • On Cloud Foundry you will not need any configuration, as it reads all needed information from the binding to the Bosch IoT Permissions service.

Find the download link for the im-api2-client at: Bosch IoT Permissions - Developer Guide > Downloads > Client Downloads.

2016-05 - New HTTPS URLs - New client version - New password rule

The Bosch IoT Permissions service update comes with following improvements:

2016-04 - New Service API 2 goes ALPHA

The Bosch IoT Permissions service is proud to announce the ALPHA version of its new Service API 2.

The new API is JSON-based, and provides JWT-based authentication and authorization.

The new API applied some improvements which also impact the current operational Service API 1.
These are:

  • The name of an application instance formerly needed to be unique within a domain of a tenant. As the domain concept was not adopted by our customers we consider to completely make it obsolete at the new API.
    Thus, an application name now needs to be unique over all tenants. This results in simpler references within the token, as no fully qualified instance name (tenant:domain:application) must be provided to evaluate permission or instance role names.
    However, we aim to continue supporting multiple installations of the same application for the same Permissions service. Therefore, we highly recommend to make the instance name configurable at the time of deploying the application.

  • A new naming pattern is applied to all application instance related entities.
    The characters pipe (|) and paragraph (§) are from now on reserved for use cases in the future.

The new API can be used in combination with Service API 1 by using the class AuthorizationTokenHolder instead of the class IdentityContextHolder.

Further details: Developer Guide

2016-03 - Improved Service Broker

The Bosch IoT Permissions service improved the brokerage related functionality: You can now define your Tenant Name (as well as the name and password of your initial user) and you can change from one service plan to another with just one statement.

Further details: Developer Guide

2016-03 - Use of PBKDF2-based password hashes

Over time password hashing algorithms get steadily weaker as computation capabilities of computers increase. We therefore decided to update our password hashing algorithm to be prepared for the next years.

For users which are maintained in the Bosch IoT Permissions database we switched the password hashing algorithm from SHA512 to PBKDF2.

With this new hashing algorithm the login process is slowed down by about 30 msec. We think that this performance is acceptable while providing solid security.

Service users will not notice this change directly as the migration of the existing passwords is performed transparently on-the-fly as part of the user authentication.

2016-03 - Improved Send Activation Email Resource

Self-registered users who missed to activate their account (within a given time frame) formerly only had the possibility to re-register with the same data for the same tenant.
This behavior is now improved by giving such "unauthorized" users the possibility to re-send such an activation email (in case it is expired) and to administrative users the possibility to better support them.

Further details:

2016-02 - UI for tenant-specific password configuration

Since December 2015 our service provides for each tenant the possibility to define its own password rules.

Now, the Bosch IoT Permissions Administrator UI supports your service administrator with an overview of the current settings and the possibility to instantly change these.

Each Service Administrator should be by default granted the Tenant-specific security settings permission (technical name TENANT_SECURITY_ADMINISTRATION).
This allows him to read and change the password rules valid for all users of the respective tenant.

By default, the tenant is provisioned by Bosch IoT Permissions with default password rules. However, if a tenant needs to enforce different password rules, these can be easily changed via the UI.

Preconditions

You will need to be logged in and have permission to edit password rules for the tenant you are currently logged in for.
The administrator of a new tenant should already have assigned all permissions defined by the IM application.

Procedure Description

  1. Click the Settings for current tenant icon.
  2. Click Edit password rules ...
  3. A dialog opens, providing you further guidance:
    1. The left column describes all possible rules.
    2. The second column shows the rules which apply for all common users of this tenant.
    3. The third column shows the rules which apply for all privileged users of this tenant.
  4. Edit the values you need to change, e.g. set a number (or "off" in order to disable this rule).
  5. Confirm by clicking one of the buttons at the bottom of the dialog box.
    1. Save & Close - will store the password rules and close the dialog box.
    2. Reset to default - will delete the custom password rules. As a result, the default password rules of the Bosch IoT Permissions will become active.
    3. Cancel - will close the dialog box without storing the changes.

Results

You have successfully changed the password rules.

It may take up to 10 minutes before changes to the tenant-specific settings will become active on all instances. 

The next time one of the users change his password, the new password will be validated according to the new values.

All password rules can be disabled by setting the value "off".

2015

2015-12 - Tenant-specific password configuration

The latest version provides for each tenant the possibility to define its own password rules.

In case you are a Service Administrator and interested in applying the feature for your tenant, please get familiar with the new sub-resources for tenant-specific settings which are described in detail at Tenant Resource.

Note: The method com.bosch.im.command.ICommandFactory#validatePassword(java.lang.String) was marked as deprecate as it does not support to specify in which context the password validation should take place. Please use the new method com.bosch.im.command.ICommandFactory#validatePassword(java.lang.String, com.bosch.model.EntityId, boolean) instead.

Note: The Admin UI will expose this new feature in a later version.

Example: Create and update tenant-specific settings using the Service API 1



2015-12 - API 1 Client for Java in public Maven repo

The API 1 Client for Java is available via our public Maven repo

In case your IDE works with Maven, your user settings could be similar to following example:

settings.xml
<?xml version="1.0" encoding="UTF-8"?>
 
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
 
 
	<profiles>
		<profile>
			<id>IM3</id>
			<repositories>
				<repository>
					<id>IM3</id>
					<url>http://maven.bosch-si.com/content/repositories/im3-releases/</url>
                    <releases>
						<enabled>true</enabled>
						<updatePolicy>never</updatePolicy>
					</releases>
					<snapshots>
						<enabled>true</enabled>
						<updatePolicy>daily</updatePolicy>
					</snapshots>
				</repository>
			</repositories>
			<pluginRepositories>
				<pluginRepository>
					<id>IM3</id>
					<url>http://maven.bosch-si.com/content/repositories/im3-releases/</url>
					<releases>
						<enabled>true</enabled>
						<updatePolicy>never</updatePolicy>
					</releases>
					<snapshots>
						<enabled>true</enabled>
						<updatePolicy>daily</updatePolicy>
					</snapshots>
				</pluginRepository>
			</pluginRepositories>
		</profile>
	</profiles>
	<activeProfiles>
		<activeProfile>IM3</activeProfile>
	</activeProfiles>
 
	....
 
</settings>

2015-11 - Improved Client Access Token management

IM3 improves your Client Access Token management

The update of the IM3 Service includes improvements of the Client Access Token management and the usability of the user interface.

The Client Access Token is used to authenticate your application at the IM service. The token itself consists of a client ID and a client secret.

It is essential that the received Client Access Token is kept secret and that it is only used by your application for communication with the IM3 Service.
Find the full concept description at Client Access Token.

Highlights
  • New user interface to manage your Client Access Tokens.
    There you can see all Client Access Tokens your tenant owns so far, or create new Tokens.
  • The new IM3 entry page gives you access to all user interfaces and documentation.
Migration steps
New features and improvements
  • [IM-3795] - Creation of Client Access Tokens for non-CloudFoundry applications from UI
  • [IM-3879] - Configure an IM3 Landing Page that is reached on "Manage Service"
  • [IM-4191] - Move im3-docs behind the UI reverse proxy
  • [IM-4234] - Move im-monitoring-app behind the UI reverse proxy
  • [IM-3406] - Use privileged password rules while handling privileged users in the Admin UI
  • [IM-3921] - Improve line breaks and margins of API Key UI
  • [IM-4012] - Usability improvement of im-server error page: Show error message
  • [IM-4022] - Prevent disclosure of Jersey version via OPTIONS request to im-server
  • [IM-4069] - ImExceptionMappingFilter should check for status code first
Bugs fixed
  • [IM-3755] - Move AutoAssignException to the IM API
  • [IM-3940] - Change Password of an user deletes the activation code
  • [IM-3992] - Stack trace disclosed when request URL ends with % (ERNW issue 8.5.4)
  • [IM-4036] - AMRA-INT: NullPointerException thrown during login after migration from 3.5.x to 3.7.0

2015-09 - Service integration is being improved

Improvements for Bosch IoT Permissions service integration

The service was updated. It provides some nice improvements for integrating the service into your application or into your own service with multi tenancy.

Highlights
  • We summarized how to switch from a self-hosted IM Server to the Bosch IoT Service: Migration from IM Server to the cloud service
  • When binding your Cloud Foundry application to an Bosch IoT Permissions service instance, your app will get all relevant information to use our service.
    See Bind your application running in Cloud Foundry to your Bosch IoT Permissions service instance for details.
    Example:

     "VCAP_SERVICES": {
      "im3-service": [
       {
        "credentials": {
         "imApiKeyId": "4b40f308-3402-4065-81ee-9424b5cbd427",
         "imClientId": "869eb850-3b41-11e5-ab75-d6cc6094be34",
         "imClientSecret": "3G8xMUKtWaxb1X7EcQY5io",
         "imServerUrl": "https://im3-api.apps.bosch-iot-cloud.com/",
         "imTenantId": "168276b0-3b41-11e5-ab75-d6cc6094be34"
         ...

    We added an initial API Key for you, so that you don't need to provide username/password to your app. Your app just needs to read the VCAP_SERVICES environment variable and parse the JSON. In a Java based app you can use the im-cf-rest-client library. This client makes use of the Bosch IoT Permissions service credentials without further configuration from your side.

  • Bosch IoT Permissions uses the BICS Mail Service. It will send an email on self-registration and for the reset password functionality.
  • You can provide your own application or service roles and permissions to an existing other tenant. Additionally, you can also see all tenants to which you provided a roles and permission offering.
New features and improvements
  • [IM-2959] - Limit max size of message body of REST POST/PUT
  • [IM-3724] - Resolve IM3 credentials from VCAP properties by tag
  • [IM-3910] - Prevent information disclosure about Tomcat server version (ERNW Issue 8.5.3)
  • [IM-3600] - IM validates JWT issued by Bosch IdP
  • [IM-3635] - Service can provide its roles/permissions to an existing tenant
  • [IM-3654] - Multitenancy features are available in IM3 Service
  • [IM-3751] - API Key is provided when binding the IM3 service
  • [IM-3869] - IM3 sends emails with the BIC Mail Service
  • [IM-3892] - On IM3 Service deprovisioning a tenant is erased instead of deleted
  • [IM-3924] - A tenant can see the consuming tenants of his tenant relations
Bugs fixed
  • [IM-3820] - Response of user list shows wrong number of totalEntries
  • [IM-3823] - SSOFilter can't be configured at runtime
  • [IM-3870] - Success Message is not shown in Login Dialog

2015-08 - IM3 is available as Service

IM3 is available in the BICS as a fully managed cloud service. You can administrate your users, groups, roles, permissions and tenants with IM3 as a service.