Service UIs

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.

About this Guide

This document is intended to help users to understand how to use Bosch IoT Permissions to manage their user account, other users, organizations, tenants, authorities (e.g. roles, permissions), Client Access Tokens, and API Keys.

Developers can also use some of the functions described. The range of options mainly depends on the user's role (thus, implicitly, the permissions granted).

This document assumes that you are versed in using Web technologies. Further, it assumes, that you have booked already our Bosch IoT Permissions service. 

At the moment, not all services provided by Bosch IoT Permissions are included in the Web-based user interface. If you need more information on the services offered, please consult the Developer Guide.


General functionality

This section is intended to help users understand how to login at the Service Management UI and managing their own account.

Login - Logout

Bosch IoT Permissions provides a global login page for authenticating to use all user interface Web applications of this service.

The initial default credentials for your tenant's administrative user are set to Admin / ChangeThis1! .

Even if the login page might offer to log in with "Bosch" or "Google", as an administrative user please consider to use the Bosch IoT Permissions credentials as long as you set up the tenant
Further we explicitly do not recommend to empower external users as "privileged" in the context of Bosch IoT Permissions, as in case of emergency we cannot reset such a user's password, nor check the latest email address he might have stored at the external identity provider.

For security reasons, it is strongly recommended that you change your password after your first login.
The service is configured to enforce the initial password change by default, but the default setting can be overwritten per tenant as part of a tenant-specific password configuration.
Example:

Details on how to change your password can be found at Change your password, and for changing another user's settings at Update User.

For security reasons, your session will automatically time out according to the settings configured by your administrator. As our SSO mechanism adds an authorization cookie on your browser, closing all browser windows is not sufficient to delete the cookie.

To properly terminate the session you must log out.

However, you cannot be logged in with different users in different tabs of the same browser.

As an authenticated user, your authorization to read, write or execute other applications can be managed using the IM application.

User Session

The user session begins with a login and ends with a logout request (or at least after a pre-defined timeout). For this session all roles and permissions the user has at the time he logs in will apply. If an administrative user or an application changes something related to a user account, please note that these changes will only take effect in the next user session (i.e. one will need to log out and log in again).


Authenticate with your Bosch IoT Permission credentials

Preconditions

We assume you need to access a page which requires authentication. In case of using the Bosch IoT Permissions user interfaces the login dialog is configured accordingly.

Note: If you are authenticated already, the requested page is displayed without requesting a login. Thus this example assumes your last session timed out.

Procedure Description

In this example the user's profile should be displayed after successful login.

  1. Your browser opens a Login dialog box.
    Example: <fully qualified domain name>/im-user-profile?imtid={tenantid}.
  1. Your Username is required.
  2. Your Password is required.
  3. Click Log in to authenticate.

Results

You are authenticated by Bosch IoT Permissions service.

User Session

The user session begins with a login and ends with a logout request (or at least after a pre-defined timeout). For this session all roles and permissions the user has at the time he logs in will apply. If an administrative user or an application changes something related to a user account, please note that these changes will only take effect in the next user session (i.e. one will need to log out and log in again).


However, the duration of a user session will differ for users who authenticate with an external provider.

Authenticate with external account

In case your tenant offers authentication with Bosch or Google, these options will be visible at the first login page.

Please note, that in such a case "Change Password" as well as the "Logout" entry at the upper corner might work differently.

  • As your primary user belongs to the external identity provider you will need to change your password there and not at our service.
  • Further, our logout functionality will log you out of our application, but will not automatically invalidate the Authentication Token which we received from the external identity provider.
    Thus the validity time of a user session might differ, e.g.
    • Bosch-Identity: xx hours
    • Google: xx hours

Authenticate via Bosch-Identity

Preconditions

We assume you need to access a page which requires authentication. In case of using the Bosch IoT Permissions user interfaces the login dialog is configured accordingly.

Note: If you are authenticated already, the requested page is displayed without requesting a login. Thus this example assumes your last session timed out.

Your tenant must be registered at the Bosch-Identity service (CIAM) already, and must have enabled this at the Permissions service for his users.

In case you don't have a Bosch account yet, at the Bosch login page you get the possibility to register for an account.

Procedure Description

In this example the user's profile should be displayed after successful login.

  1. Your browser opens a Login dialog box.
    Example: <fully qualified domain name>/im-user-profile?imtid={tenantid}.

  2. Click the Sign in with Bosch button.
  3. Authenticate there with the credentials of your Bosch account.

     
  4. Afterwards you will get re-directed back to Bosch IoT Permissions.
    1. In case this was the first usage of your Bosch authentication within our service, this will automatically create an user account with your email as username.
    2. As any user you will:
      1. Automatically get all roles assigned to the "all users group" of your tenant.
      2. Have rights to see your User Profile
        (i.e. the data known by the Bosch IoT Permissions about you).

Results

After being authenticated by Bosch as the identity provider, our Bosch IoT Permissions service will take care for your authorization. E.g. empower you to use other applications, which integrate with this Single-Sing-On mechanism.

To close the session, please use the Logout menu entry at the top.

Authenticate via Google

Preconditions

We assume you need to access a page which requires authentication. In case of using the Bosch IoT Permissions user interfaces the login dialog is configured accordingly.

Note: If you are authenticated already, the requested page is displayed without requesting a login. Thus this example assumes your last session timed out.

Your tenant must be registered at the Google identity service already, and must have enabled this at the Permissions service for his users.

In case you don't have a Google account yet, at the Google login page you get the possibility to register for an account.

Procedure Description

In this example the user's profile should be displayed after successful login.

  1. Your browser opens a Login dialog box.
    Example: <fully qualified domain name>/im-user-profile?imtid={tenantid}.
  2. Click the Sign in with Google button.
  3. Authenticate there with the credentials of your Google account.
     
  4. Afterwards you will get re-directed back to Bosch IoT Permissions.
    1. In case this was the first usage of your Google authentication within our service, this will automatically create an user account with your email as username.
      Your first and last name are also taken over from your Google account.
    2. As any IM user you will:
      1. Automatically get all roles assigned to the "all users group" of your tenant.
      2. Have rights to see your User Profile
        (i.e. data known by the Bosch IoT Permissions about you).

Results

After being authenticated by Google as the identity provider, our Bosch IoT Permissions service will take care for your authorization. E.g. empower you to use other applications, which integrate with this Single-Sing-On mechanism.

To close the session, please use the Logout menu entry at the top.

Basic concepts of user self-registration

Bosch IoT Permissions provides a Web based user self-registration application which can be used as a default implementation or as a template for custom registration forms.
The Web application also contains a login form with password reset functionality.

The self-registration process is a sequence of three use cases:

  • User self-registration:
    • The user creates a new user account by filling out a registration form.
      • Required fields are: username, email address and the initial password.
      • The ID of the tenant is provided via the URL.
      • The browser language is stored in form of a user attribute.
    • The user submits the registration request to the Bosch IoT Permissions service.
    • The service validates and stores the given data.
  • Send activation email:
    • After the form was submitted successfully to the service, the Web application triggers the service to send an activation email to the given email address.
    • The email contains an activation link which contains the user ID, the tenant ID and an activation code.
  • Activate user account:
    • After receiving the activation email, the user needs to click the link prepared within the activation email to continue the self-registration.
    • By following the link within the activation email the user is delegated to a Web site provided by the user self-registration Web application.
    • The site has a button which needs to be pressed by the user to trigger the activation. It uses the user ID and the activation code to activate the user at the Bosch IoT Permissions service.
      The response of this call is used to pre-fill the login form with the name of the user. The tenant ID is passed within the URL.
    • The user account is active from now on and the user is therefore able to login at Bosch IoT Permissions service from now on.

Examples

Self-register as user

Preconditions

You will need to know the URL for self-registration.

Example: https://permissions.s-apps.de1.bosch-iot-cloud.com/fusion/app/registration?imtid={tenantId}

Also, the login dialog provides unregistered users a link to the registration page.

Procedure Description

  1. The page will display a form for completing all the information required to self-register as user (for the tenant specified within the URL).
  2. You must complete at least all required fields in the dialog box (marked *)

    1. The username must not start or end with a blank space.

    2. The email address is required, as after submitting this registration form an activation link will be sent at that address.
    3. The requirements regarding the characters to be used or minimum length for the new password etc. can be configured by the administrator and thus will differ per tenant.
    4. The additional check Repeat password is meant to guard against typos occurring in the password.
    5. By checking the checkbox you need to explicitly accept  the “Terms and conditions” as well as the “Privacy policy” in the current version related to the service.  However, as the linked documents will differ for some providers, the checkbox and the links might also be absent. In such a case just finish this dialog with “Register”.

  3. Click Register to confirm the registration.

Results

The registration dialog should report the success respectively.

Your data for self-registration is now available at the Bosch IoT Permissions service. However your user account is marked as "Activation Pending".

To complete the registration by activating your new account see Activate your self-registered user account

For a service administrator your registration data is visible.
See Bosch IoT Permissions - Service UIs > Administrator UI > Administrative tasks for supporting user self-services > Identifying self-registered users for the description of an administrator's view.

Troubleshooting

  • For the case another user with the same username exists already, the message would help respectively.
  • For the case the communication with the service or the email server failed, the message would change respectively.

Activate your self-registered user account

Preconditions

Procedure Description

  1. Click the "activation link" within the email you have received.

    The validity period of the activation link (i.e. secret code to activate a user account) is restricted to currently 3 hours. Thus we recommend reading the email carefully and activating your account as soon as possible.
    The code is valid only once. If you would try to re-use it, a failure message would be displayed.
  2. Your browser opens a pre-configured activation site.
    The activation site uses your user ID and an activation code as parameters to activate your account.

  3. Click the Activate account button.
  4. If the activation was successful the login form with a success message is shown.
    Your user account is active from now on.
  5. Log in with your username and your password to authenticate.

Results

Your user account is fully activated within Bosch IoT Permissions.

In case the activation fails, you will be informed respectively and can request a new activation email.

In case you have no access to the email account (e.g. due to a typo while registering) an administrative user could correct the address and re-send an activation email.

Please note, that a self-registered user is overwritten in case an activation with the same tenant, same user name and the same email address occurs.

This might happen e.g. if you miss to proceed with your user activation and re-register with the same data.

Edit your user profile

The user profile was designed for managing user data stored at Bosch IoT Permissions. Although we do not prevent users form external identity providers to enrich their profile data here, please be aware that we will not synchronize the data with such external providers.


Preconditions

In case of using the UI Integrator component, the User Profile menu entry can be found
  • Go To navigation bar or
  • At the landing page via the icon

You will need to log in with your credentials.


Display mode

Your browser opens an User profile dialog box in display mode and shows all currently filled or pre-filled attributes with user related data.

The Tenant field is pre-filled with your tenant name.
The field is read-only as IM does not support the concept of moving users from one tenant to another one.

Your Username field is pre-filled with your user name.
The field is read-only. The username can currently only be changed using the Administrative UI.

The First name and Last name are editable and can be modified when User profile dialog box is in edit mode.

You can switch to edit mode by clicking Edit profile button.

Tip: if your user data have been imported from an external identity provider (e.g. Google), the User Profile dialog does not provide you the Edit profile button as imported data are not allowed to be edited.


Edit mode

In edit mode you can modify all available profile attributes. As of now, the user profile provides user attributes according to the vCard 4 standard (see https://tools.ietf.org/html/rfc6350).

Click on Save button will save the data and show User profile dialog box in display mode with saved user profile attributes.

Click on Cancel button will dismiss all changes and show User profile dialog box in display mode with actual user profile attributes.

Change the email address associated to your user account

The user profile was designed for managing user data stored at Bosch IoT Permissions. Although we do not prevent users form external identity providers to enrich their profile data here, please be aware that we will not synchronize the data with such external providers.

Preconditions

In case of using the UI Integrator component, the User Profile menu entry can be found

  • Go To navigation bar or
  • At the landing page via the icon

You will need to log in with your credentials.

Procedure Description

  1. Your browser opens an User profile dialog box pre-filled with user related data.
  2. The Email address section is pre-filled with the current address associated to your user account.
  3. Click the Edit profile button get the editing view.
    1. Edit your email address
      Hint: A new email address will not be carried over immediately. It will be adopted and visible in the Email address field after you activate it by means of the email that we send to you.
    2. Press the Save button to confirm the changes.
  4. A notification is displayed at the Email address section.

    To keep your account secure we provide the service of changing the email address (by someone else than an administrator) only with this additional confirmation step.

    The validity period of the email confirmation link (i.e. secret confirmation code) is restricted. Thus we recommend reading the email carefully and confirming as soon as possible.
    The code is valid only once. If you would try to re-use it, a failure message would be displayed.

  5. Check your emails. We assume the email received looks like the following example:
  6. Click the link.
  7. Your browser opens a site which allows you to confirm the email address change.
  8. Click Use new email address to confirm the changes.

Results

Your change was successful, thus all upcoming emails will be sent to the new email address.

In case the email address change failed, e.g. due to an outdated confirmation code, an according notification is displayed.

The validity period for activating the new email address is restricted to currently 30 minutes. Thus we recommend reading the email carefully and activating the new address as soon as possible.

Change your password

In case you need to change your password and you know your old password, you can request a password change (instead of Resetting your Password).

If you are logged in via an external identity provider, your password can not be changed in Bosch IoT Permissions. In this case, use the functionality of the external identity provider.

Preconditions

You will need to log in with your credentials.
In case of using the UI Integrator component, the Change Password menu entry can be found within the top bar.

Procedure Description

  1. Click Change Password and you will be offered the possibility to change your own password.
  2. The following dialog requires your Old password and Your new password, in order to keep your account secure.

    The requirements regarding the characters to be used or minimum length for the new password etc. can be configured by the Service Administrator of the tenant.

  3. The field to verify the new password is marked as required as well.
    This additional check is meant to guard against typos occurring in the new password.
  4. Click Change password to confirm the password change.
  5. A success message will be displayed within the Password section.

Results

The new password is stored and you must use the new password from the next login onward.

Additionally, if you cannot remember your old password you can Reset your password. That implies an additional security procedure via email.

Note: Users with a certain amount of unsuccessful login attempts (the number is again configured by the service administrator) can be locked. In that case you need to address an administrative user.

Reset your password

In case you have forgotten your password, you can request a password reset.

If you are logged in via an external identity provider, your password can not be reset in Bosch IoT Permissions. In this case, use the functionality of the external identity provider.

Preconditions

We assume you need to access a page which requires authentication. In case of using the Bosch IoT Permissions user interfaces the login dialog is configured accordingly.

Note: If you are authenticated already, the requested page is displayed without requesting a login. Thus this example assumes your last session timed out.

Procedure Description

  1. Open your browser at the site which requires to be logged in.
  2. The Login form is displayed.

    Users with a certain amount of unsuccessful login attempts (the number can be configured by the Service Administrator of the tenant) can be locked. In that case you need to address an administrative user.
    Therefore, we suggest requesting the possibility to define a new password before trying several times.

  3. In case you forgot your password, click the respective link to request a password reset.
  4. The follow-up dialog requires your Username.

    Note: In order to clearly identify you without ambiguity, internally Bosch IoT Permissions uses as well the tenant ID, which is retrieved from the URL. 
  5. The follow-up site will report about having successfully triggered the Bosch IoT Permissions service to send you an email at the email address associated to your user account.

    The email will contain a link with a secret code, which will enable you to authenticate for a short period, in order to change your password.
  6. Check the inbox of your email account. We assume the email received looks like in the following example:
  7. Click the link.
  8. Your browser opens a site which offers a dialog box to define a new password.
  9. Enter your new password twice (the required fields are marked *).

    A user can be locked after a certain amount of unsuccessful attempts to log in. Administrative users can unlock the user and provide him a new password. The requirements regarding the characters to be used or minimum length for the new password etc. can be configured by the Service Administrator of the tenant. However the user interface will support you by providing information on which checks have failed.


  10. Click Change password to store it.
  11. In case the password change was successful, the respective message will appear in the follow-up dialog box.
  12. Log in with your Username and the new Password to authenticate.

Results

You are authenticated by Bosch IoT Permissions.

The validity period of the password reset link (i.e. secret password reset code) is restricted to currently 30 minutes. Thus we recommend reading the email carefully and specifying a new password as soon as possible.

The secret password reset code is valid only once. If you would try to re-use it, a failure message would be displayed.

In such a case feel free to request a new reset code.
However, if you need to reset your password very often, consider that our service will pause 30 minutes before sending the next password reset email.
This helps to avoid sending you multiple password reset mails just because you clicked multiple times the Reset password button.

Close your session - Logout

You will be logged out when you close your Web browser.

For security reasons, your session will also automatically time out according to settings configured by your administrator.

In case of using the UI Integrator component, the Logout is configured accordingly.

User Session

The user session begins with a login and ends with a logout request (or at least after a pre-defined timeout). For this session all roles and permissions the user has at the time he logs in will apply. If an administrative user or an application changes something related to a user account, please note that these changes will only take effect in the next user session (i.e. one will need to log out and log in again).


Unregister your user account

Bosch IoT Permissions provides you the possibility to delete/cancel your own Bosch IoT Permissions user account. However, this action can only be offered for Users with respective permission.

In case your user account is primarily managed at an external authentication provider (e.g. Bosch, Goggle) deleting your user account at this service does not delete the original user account.

Preconditions

You will need to be logged in and have permission to delete your own user account (i.e. "Own user - delete").

Procedure Description

  1. Navigate to your User Profile.

    By default, the link to Unregister is not displayed for users who do not have that permission.
  2. Click Unregister
  3. In order to prevent you from unregistering by mistake the follow-up dialog will require to confirm the deletion.
  4. Click Yes, unregister user to confirm the deletion.
  5. On success a new page is displayed stating your account is deleted.
  6. You will be automatically logged out.

Result

After being automatically logged out, you will not be able to use the old credentials any longer as your user account is marked as "self-deleted".

Administrative personnel will check for further organizational need of your user data (e.g. open invoices etc.) and erase the user account as soon as possible.

Note: As long as the user account is not erased you will not be able to use the same username for a new self-registration.

In case you have no permission to delete your user account, but know the link for unregistering for any reason, and try it out, a failure message is shown

In such a case please contact your administrative personnel.

Client Access Token UI

This section is intended to help administrators understand how to use Bosch IoT Permissions to manage the Client Access Tokens they need in order to use the Bosch IoT Permissions cloud service.

All resources of Bosch IoT Permissions are protected via a Client Access Token based authentication. This token is used to authenticate your application at the service.
The token consists of a client ID and a client secret.
For more details see section Client Access Token in the developer guide.


Get access to the Client Access Token UI

First of all, a user who needs to manage a list of Client Access Tokens will need to be granted the respective permission.

Authenticate with your Bosch IoT Permission credentials.

In case your tenant offers authentication via external providers (e.g. Bosch, Google) you may use that option also. In such a case your user must be assigned meanwhile the CLIENT_ACCESS_TOKEN_ADMINISTRATION permission.

The CLIENT_ACCESS_TOKEN_ADMINISTRATION permission is by default part of the IM Service Administrator role.

After authentication the Bosch IoT Permissions landing page provides users with the respective permission the entry point to manage Client Access Tokens.

Further steps:

List the Client Access Tokens of your Tenant

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

Preconditions

You will need to log in with your credentials. You need the Permission "Client access token administration for the current tenant".
This Permission is part of the "IM Service Administrator" role.
(See Administrator UI > Create a User-Role assignment on how to provide your user with a role).

Procedure Description

  1. Click Client Access Tokens.
  2. You will get a list of the Client Access Tokens generated for your Tenant.
  3. The list of Tokens will be ordered by Client ID.
  4. For each token only the Client ID and the Description are displayed.

Results

The list of Client Access Tokens is displayed.

It is essential that the user who creates the Client Access Token stores the client secret as the complete token used by an application needs to be composed of both parts separated by a colon character ":" e.g.:
client ID:client secret

Create a new Client Access Token

Preconditions

You will need to log in with your credentials. You need the Permission "Client access token administration for the current tenant".
This Permission is part of the "IM Service Administrator" role.
(See Administrator UI > Create a User-Role assignment on how to provide your user with a role).

Procedure Description

  1. Click Client Access Tokens.
  2. You will get a list of the Client Access Tokens generated for your Tenant.
    For each Token only the Client ID and the Description are displayed.
  3. Click Create Client Access Tokens.
  4. The dialog offers a field where you can add a description for your Token.
     You can store there any information which helps you remind the solution which was supposed to use the Token.
  5. Click Create Client Access Token to continue.
  6. The upcoming dialog will display the generated Token parts and inform you about the NEED to copy the secret value, as this information cannot be presented at a later point in time.
  7. Click OK to confirm you have stored the secret on your local machine.

Results

The list of Client Access Tokens is displayed. The Tokens are ordered by Client ID.

It is essential that the user who creates the Client Access Token stores the client secret, as the complete token used by an application needs to be composed of both parts separated by a colon character ":" e.g.:
client ID:client secret

Delete one or multiple Client Access Tokens of your Tenant

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

Preconditions

You will need to log in with your credentials. You need the Permission "Client access token administration for the current tenant".
This Permission is part of the "IM Service Administrator" role.
(See Administrator UI > Create a User-Role assignment on how to provide your user with a role).

Procedure Description

  1. Click Client Access Tokens.
  2. You will get a list of the Client Access Tokens generated for your Tenant.
  3. The list of Tokens will be ordered by Client ID.
  4. For each token only the Client ID and the Description are displayed.
  5. Select one or multiple Client Access Tokens from the list by clicking on them. The selected tokens will be highlighted.
  6. Click on the 'Delete selected Client Access Token(s)' button.
  7. A confirmation view will be displayed which lists the token which should be deleted.
  8. Click the 'Yes, delete' button to confirm and delete the Client Access Tokens.

Results

The list of Client Access Tokens is displayed without the deleted Client Access Tokens.

API Key UI

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

This section is intended to help administrators understand how to use Bosch IoT Permissions to manage the API Keys they need in order to use the Bosch IoT Permissions cloud service.

Get access to the API Key UI

First of all, a user who needs to manage API Keys will need to be granted the respective permission.

Authenticate with your Bosch IoT Permission credentials.

In case your tenant offers authentication via external providers (e.g. Bosch, Google) you may use that option also. In such a case your user must be assigned meanwhile the API_KEY_ADMINISTRATION permission.

The API_KEY_ADMINISTRATION permission is by default part of the IM Service Administrator role.

After authentication, the Bosch IoT Permissions landing page provides the entry point to manage API Keys.

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

When managing API Keys, keep the following concepts and restrictions in mind:

  • A user can define various API Keys valid at the same time, but their names must be unique per user.
  • API Keys are bounded to the user that created them (only this user is able to see or delete them).
  • While using an API Key for authentication, it is not possible to perform API Key related operations (e.g. show or create other API Keys).
  • The effective roles and permissions of an API Key are determined when an API Key is used to authenticate. This means, the Identity Context which is loaded, only contains roles and permissions which are part of the API Key (including permissions assigned to API Key roles) and which the user has at this point in time.
  • When an API Key contains a role the permissions assigned to this role will be part of the corresponding IdentityContext even if they are not specified in the API Key.
    This is useful for scenarios where you want to be able to change the contained permissions transparently.
  • Even though the password of the user who created an API key expires, the API Key of the user still works. Not even the locking state of a user has influence on the viability of his API Keys.
    However, deleting the user or one of the permissions related to the key will take effect immediately.
  • An API Key created by a privileged user is privileged as well. This means that it is possible to perform privileged operations using this API Key (assign additional permissions, create privileged users, etc.). If this is not the desired behavior we suggest to use a non-privileged user to create an API Key.

You will be logged out when you close your Web browser.

For security reasons, your session will also automatically time out according to settings configured by your administrator.

In case of using the UI Integrator component, the Logout is configured accordingly.

User Session

The user session begins with a login and ends with a logout request (or at least after a pre-defined timeout). For this session all roles and permissions the user has at the time he logs in will apply. If an administrative user or an application changes something related to a user account, please note that these changes will only take effect in the next user session (i.e. one will need to log out and log in again).


List your API Keys

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

Preconditions

You will need to log in with your credentials. You need the Permission "API Key Administration".
This Permission is part of the IM roles  "IM Service Administrator" and "IM Tenant Administrator".
(See Administrator UI > Create a User-Role assignment on how to provide your user with a role).

You will get an overview of the API Keys generated on your user account.

Procedure Description

  1. Click API Key and you will be listed the Keys existing so far.
  2. A list of existing API Keys will appear.
    In case there are more than 200 API Keys on your user account, please be aware that only 200 of them are displayed, as no paging is implemented for this view.
  3. The sorting will be chronological.
  4. Roles and Permissions are grouped by the Tenants or Instances they belong to.
  5. You can hover the group titles, Roles and Permissions to see their details.

Results

The current list of API Keys is displayed. On the top the recently created API Key resides.

An API Key created by a privileged user is privileged as well. This means that it is possible to perform privileged operations using this API Key (assign additional permissions, create privileged users, etc.). If this is not the desired behavior we suggest to use a non-privileged user to create an API Key.

Create a new API Key

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

Preconditions

You will need to log in with your credentials. You need the Permission "API Key Administration".
This Permission is part of the IM roles  "IM Service Administrator" and "IM Tenant Administrator".
(See Administrator UI > Create a User-Role assignment on how to provide your user with a role).

You will get an overview of the API Keys generated on your user account.

Procedure Description

  1. Click API Key and you will be listed the Keys existing so far.
  2. Click Create API key to display the API Key creation form.
  3. There you can enter an API Key name and assign Roles and Permissions by clicking them in the list.
  4. To create an API Key the API Key Name as well as the assignment of at least one Role or Permission is required.
  5. You can Select all or Deselect all Roles and Permissions of a group.
  6. Click the Save button to generate an API Key with the information you provided in the form.

Results

The current list of API Keys is displayed. On the top the recently created API Key resides.

An API Key created by a privileged user is privileged as well. This means that it is possible to perform privileged operations using this API Key (assign additional permissions, create privileged users, etc.). If this is not the desired behavior we suggest to use a non-privileged user to create an API Key.

Delete an API Key

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

Preconditions

You will need to log in with your credentials. You need the Permission "API Key Administration".
This Permission is part of the IM roles  "IM Service Administrator" and "IM Tenant Administrator".
(See Administrator UI > Create a User-Role assignment on how to provide your user with a role).

You will get an overview of the API Keys generated on your user account.

Procedure Description

  1. Click API Key and you will be listed the Keys existing so far.
  2. A list of existing API Keys will appear.
    In case there are more than 200 API Keys on your user account, please be aware that only 200 of them are displayed, as no paging is implemented for this view.
  3. Click Delete to permanently remove an existing API Key.
    Note: This action cannot be un-done.

Results

Your list of still existing API Keys is displayed.

Administrator UI

This section is intended to help administrators understand how to use Bosch IoT Permissions to manage users, organizations, tenants, and authorities (e.g. roles, permissions).

Basic Concepts

The Bosch IoT Permissions - Administrator UI is accessible in a Web browser.

If you are authorized to manage users, groups etc. your screen might look like the screenshot below.

Getting Started - Cheat sheet on basic icons and operations

This section focuses on the main options for managing a Bosch IoT Permissions element using the user element as an example. All other Bosch IoT Permissions elements follow the same behavioral pattern. For a detailed description on certain operations, please consult the sections linked accordingly.

To collapse/un-collapse a column please use the arrow at the upper right corner of the respective column.


Create

Use the appropriate element icon with a + to add a new user, group, role etc. A corresponding dialog box providing input fields will then appear.

Icon Function

Add tenant
The required fields will be highlighted in the dialog box that appears.
Once successfully created, the new tenant will be displayed.
Note: The newly created admin for the new tenant will not appear even after a refresh, as the new tenant is "data owner" of this user.

To see and re-edit the tenant name, click the tenant icon
See also Tenant Management

Add user
The required fields will be highlighted in the dialog box that appears.
Once successfully created, the user will be displayed.

To see and re-edit the details, click the user icon .
See also User Management

Add group
The required fields will be highlighted in the dialog box that appears.
Once successfully created, the group will be displayed.

Group hierarchy
If you need to create a sub-group, select the parent group while creating the new group.
To expand or collapse hierarchically-ordered groups, use the arrow next to the appropriate parent group.

To see and re-edit the details, click the group icon .
See also Group Management

Add role
The required fields will be highlighted in the dialog box that appears.
Once successfully created, the role will be displayed.

To see and re-edit the details, click the role icon .
See also Role Management

Roles created this way are "tenant roles", whereas "application roles" (which are defined by applications and get imported into the service) have a slightly different icon .

Add domain
The required fields will be highlighted in the dialog box that appears.
Once successfully created, the domain will be displayed.

To see and re-edit the details, click the domain icon .
See also Domain Management

Add offering
The required fields will be highlighted in the dialog box that appears.
Once successfully created, the offering will be displayed.

To see and re-edit the details, click the offering icon .
See also Offering Management

Add tenant relation
The required fields will be highlighted in the dialog box that appears.
Once successfully created, the tenant relation will be displayed.

To see and re-edit the details click on the tenant relation icon .
See also Tenant Relation Management

Read
  • Moving the mouse pointer over an element will reveal a pin icon  on the right-hand side. By clicking this icon all related elements will be highlighted.
    E.g. click a user's pin icon to see all groups in which the user is a member, as well as all roles and permissions assigned to that user.
    In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.
  • To read the user's details, click the element's icon. A click on Close brings you back to the column displaying all users.
  • Groups marked with a small arrow have at least one subordinate group. To inspect a child group, click first on the arrow, then the group you are interested in.
  • See also Search  
  • See also Filter.
Update
  • To update a user, click the corresponding icon in the table cell.
  • The read view will display the details (all information edited so far and the technical ID, which cannot be changed).
  • Click Edit and a dialog box displaying the input fields will appear.
  • Click Save, Save & Close, or Cancel to resume the dialog.
Delete
  • Drag the element you want to delete and drop it on the recycle bin area
    This action deletes the user, group, role, etc., along with all assignments the element was involved in.
  • Deleted elements can be found in the recycle bin.
  • To view the recycle bin, click the "switch to recycle bin" icon .
Recycle bin - Restore or permanently delete elements

The recycle bin displays all elements that were marked as "deleted". Deleted elements also have a deletion marker () next to the corresponding table cell icon.

  • To view the recycle bin, click the "switch to recycle bin" icon .
  • While the recycle bin is displayed, you will see the recycle bin icon and the headline Recycle bin above all element tables.
    In this view you can
    • restore a deleted element by dragging and dropping it onto the "restore" icon or
    • permanently delete an element by dragging and dropping it onto the "delete permanently" icon .
  • To leave the recycle bin, and switch back to the default view, click the "exit recycle bin" icon .

Some actions cannot be performed within the recycle bin, e.g. showing related elements, or creating or deleting assignments.

Assign - Create a relationship between different element types
  • Drag the element and drop it into the corresponding entry in another row.
    E.g. users that should be added to the members of a group should be dropped into the group table cell.
  • While an element is pinned, all related elements will appear at the top of the column and are highlighted green. Additionally, the total number of elements assigned to the pinned one will be displayed at the foot of the column.
  • Indirectly assigned elements are indicated by a "chain" icon, e.g. a role that was not assigned directly to a user but inherited as a result of group membership would be indicated thus:
  • New assignments are not immediately activated. First they are collected - corresponding messages will appear above the columns - and then they can be applied all at once.
Delete Assignment
  • Drag the element you want to un-assign and drop it on the "remove assignment" area .
  • This action will only delete the relation between the elements, not the elements themselves.

  • Dropped assignments are not immediately activated. First they are collected - corresponding messages will appear above the columns - and then they can be applied all at once.
Search

Each column has a quick-search field .

You can search using either single or multiple terms.
E.g. to find the user "Paul Paulsen" with email address "some@web.de", you can edit the search criteria by typing "Paul web.de" in the search field.

Note: At the moment wildcards (e.g. *) are not supported.

Filter

Columns with a "filter" icon  in the header can be restricted to display only the items connected to a specific element. The roles list, for example, can be restricted to show only the roles provided by a specific application.

  • Click on the filter icon to reveal the options for restricting the list.
    Example: Roles can be filtered according to a specific application.
  • Drag the element that should restrict the column content into the column's header area and drop it there. The column is immediately restricted to the specified element.
    Example: Setting the IM application as filter will hide all roles that are not related to the IM application. Thus, this function allows you to see which particular application exposed that role. 
  • To remove the filter, click the "x" next to the filter criterion that you want to remove.

In general: A list can be filtered by one element per element type only.

For the roles column: it is possible to specify only one application as a filter. The roles cannot be filtered according to multiple applications at the same time.
More details about filtering roles can be found at Read Role > Filter roles list .

Multi-selection in tables

Selecting multiple elements (users, groups, roles, etc.) is helpful if you want to create multiple assignments of the same type all at once.
E.g. you may wish to assign all roles containing "Administrator" (using the search) to one single user or to assign multiple users to one group.

Multi-selection can be used in several ways, as can be explained in relation to the users column:

  • Selecting a "block" of users: Select one user, hold down the Shift key, and select a second user above or below the first one, then release the Shift key again.
    All users located between those two are now selected and can be used for drag and drop operations.
  • Selecting multiple single users: Select one user, hold down the Ctrl key, and select another user. Still holding down the Ctrl key, you can select several more users.
    Once you have selected all the users you want, release the Ctrl key again.
    All the selected users can now be used for drag and drop operations.
  • Multi-selection for power users (without use of the mouse): Click on one user. Now you can navigate the table with the Up and Down arrow keys on your keyboard:
    • Holding down the Shift key while navigating up or down with the arrow keys selects all user rows downwards or upwards.
    • Holding down the Ctrl key while navigating up or down shows a slightly dotted border around the table row that is currently selected.
      Pressing the Space bar on your keyboard while still holding down the Ctrl key adds the row in question to the selection.
Operation on hold - Actions that are not yet stored in the database

Some actions (e.g. creating and deleting assignments) will not be executed automatically (not sent to the back end) because you might want to create various other relations first and only then synchronize with the back end, all at once.

Any operations awaiting your final approval are displayed in the upper part of the Administrator UI. 

  • You can review each action before applying it.
  • You can cancel ALL or send ALL changes to the service for completion.
Refresh - Update the content displayed

If a large number of Bosch IoT Permissions service administrators are working at the same time for the same tenant, the situation might arise where a user you are trying to update has already been updated by one of your colleagues. To avoid such overlap, you can frequently refresh the data display by clicking the "refresh data" icon  at the top right of the page.

Using the refresh functionality of your browser (i.e. pressing the F5 key) does not reload the displayed data. It only reconstructs the UI without fetching any changes from the database.

User related configuration

Change my password

Each user has at least permission to change his own password. Find a detailed description at section Change your password.

Table length

Click the user settings icon to adjust the length of the table.
The number on the slider refers to the amount of elements to be displayed per column.

Tenant related configuration

Edit email templates for user self-services

The emails necessary to communicate to the users must be explicitly defined for each tenant.

Find a detailed description at Edit email templates (see as well a summary of Administrative tasks for supporting user self-services).

Edit password rules

Find a detailed description at Manage the password rules.

Edit self-service settings

If you want to enable users to self-register, this is your entry point

 

Find a detailed description at Manage the user self-service related settings.

Edit identity providers

Here you can enable or disable the login with users of external identity providers.

Find a detailed description at Manage the access via external identity providers.

Help

A quick-start guide will appear when you click on the help icon . In addition, many icons will offer a useful tooltip when you hover over them.

User Session

The user session begins with a login and ends with a logout request (or at least after a pre-defined timeout). For this session all roles and permissions the user has at the time he logs in will apply. If an administrative user or an application changes something related to a user account, please note that these changes will only take effect in the next user session (i.e. one will need to log out and log in again).


Manage the basic entities

To oversimplify the Bosch IoT Permissions Date Model, first of all one could differentiate between organizational and application data.
The entities work as shown in the following picture.

Manage the password rules

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

User Management View

The  Administrator UI contains nine columns which correspond to one type of entity each. When using the UI with all columns enabled on a monitor with small resolution, there might raise some usability inconveniences, e.g. forcing you to collapse some of the columns to get more space for the other ones.

In order to address this problem the Administrator UI allows to define customized views, which hide some of the columns which are assumed to be not necessary for completing a simple task.

The User Management view addresses:

The IM User Manager role holds all permissions one would need to work in this view.

Role name IM User Manager
Description Manages users, groups and roles
Permissions 16
Technical name UserManager
Permission name Description Technical name
Application instances - query Allows to query instances READ_INSTANCE
Groups - create Allows to create groups CREATE_GROUP
Groups - delete Allows to delete groups DELETE_GROUP
Groups - erase Groups - erase ERASE_GROUP
Groups - query Allows to query groups READ_GROUP
Groups - update Allows to update groups UPDATE_GROUP
Modify 'group-role' relations Add or remove relations between groups and roles RELATION_GROUP_ROLE
Modify 'user-group' relations Add or remove relations between users and groups RELATION_USER_GROUP
Modify 'user-role' relations Add or remove relations between users and roles RELATION_USER_ROLE
Roles - query Allows to query roles READ_ROLE
Tenants - query Allows to query tenants READ_TENANT
Users - create Allows to create users CREATE_USER
Users - delete Allows to delete users DELETE_USER
Users - erase Allows to erase users ERASE_USER
Users - query Allows to query users READ_USER
Users - update Allows to update users UPDATE_USER

Example

User Management

User
A user can be a human being, machine, network, etc. that is allocated to use a part of an application.

Within the Web user interface the following icon is used for a user . A user provided by an external system is represented by the following icon .

A default user is generated during the initialization of a Bosch IoT Permissions service instance. This user is granted the role "Administrator" and is usually responsible for creating and managing all other entities.

When managing a user, keep the following concepts and restrictions in mind:

  • Each user belongs to exactly one tenant.
  • Each user is implicitly assigned to the All Users Group of the tenant he belongs to.
  • The user's name must be unique within that tenant.
  • The set of permissions that a user holds is a union of all permissions from:
    • user - group assignments
    • user - role assignments.
  • A user can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries, etc. (except for the "recycle bin" view).
  • Deleting a user also deletes all his existing relationships to groups, roles etc.

User management functionalities

User self-service functionalities

A user can execute the following operations on its own, without administrative rights.

Create User

Preconditions

You will need to be logged in and have permission to create users.

Procedure Description

  1. Click the "add user" icon .
  2. The Users column will display a form for completing all the information required to create a user.
  3. You must complete at least all required fields in the dialog box (marked * )

    1. The Username must consist of alphabetic and numeric characters. Some special characters are allowed, so that most email addresses can be used as usernames. Blanks are allowed, but not as the first or last character.

    2. The requirements regarding the characters to be used or minimum length for the new password etc. can be configured by the administrator and thus will differ per Bosch IoT Permissions service instance.
  4. Confirm by clicking one of the buttons at the bottom of the dialog box
    1. Save - will display a preview of the entries edited so far.
      From there you can continue with
      1. Edit - to amend your entries 
      2. Close - to store the new user.
    2. Save & Close - will store your entries and display all users in the Users column.
    3. Cancel - will ignore the entries and resume the creation dialog, displaying all users in the Users column.

Results

The new user is now available and will be displayed in alphabetical order in the Users column.






Users from an external identity provider

Users originating from an external identity provider (e.g. OpenID Connect provider) can be managed in Bosch IoT Permissions in order to assign them to groups, roles, etc..
These users will be authenticated based on the credentials persisted in the external authentication provider.

External users are added to Bosch IoT Permissions individually, when they log in for the first time at our service.

They are identified with following icon . The Administrator UI will support you in creating and deleting assignments to other Bosch IoT Permissions entities.

For authentication purposes (i.e. token signature check) Bosch IoT Permissions accesses the external provider in some cases in real time. As a result, authentication will fail if the external provider is unavailable.

Form the accounting perspective of the Bosch IoT Permissions service plan, these users are "managed users".

Read User

Preconditions

You will need to be logged in and have permission to read users.

Procedure Description

  1. The Users column displays all users in alphabetical order.
  2. For a quick-view of a user's details hover your mouse pointer over the user. A tooltip appears, displaying some of the user's details.
  3. Click the user's icon to read more details.
  4. For a quick-view of the relations to other elements click the pin icon, which is revealed by moving the mouse pointer over the user cell.

    Click the pin icon again to clear the highlighting.
  5. Alternatively:
    1. Use the search field at the top of the Users column to quickly find a user.
    2. If you don't know the exact spelling of a user's name, click the pin icon of a group in which he is a member, and the user list of that group will be re-ordered automatically at the top of the Users column. Clicking the pin icon of a user's role or permission will highlight the relevant related elements.

Results

The user's details are displayed like a tooltip.

Clicking the pin icon, which is revealed by moving the mouse pointer over the user cell, will highlight all groups to which the user belongs, as well as all roles and permissions assigned to that user. In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.

Enforce a password change

Preconditions

You will need to be logged in and have reading and writing permission for users.

Procedure Description

  1. Click the icon in the left area of the user's cell in the Users column.
  2. The user details will appear in read-only format as they were entered when the user was created.
    The feature to enforce a password change (by an administrative user) is provided at this level

Results

The user will need to change his password.

This option does not apply for users of external identity provides (marked ), as the password is managed at the respective provider and not within Bosch IoT Permissions.

Update User

Preconditions

You will need to be logged in and have reading and writing permission for users.

Procedure Description

  1. Click the icon in the left area of the user's cell in the Users column.
  2. The user details will appear in read-only format as they were entered when the user was created.
  3. Click Edit to change the content of any of the fields.
    Our example shows how to provide a German user description.
  4. Resume the dialog using the buttons at the bottom of the form (as explained for Create User).

Results

The updated user attributes are now stored on the back end. Other administrative users will need to refresh their view to see your changes.

A user can be locked after a certain amount of unsuccessful attempts to log in. Administrative users can unlock the user and provide him a new password. The requirements regarding the characters to be used or minimum length for the new password etc. can be configured by the Service Administrator of the tenant. However the user interface will support you by providing information on which checks have failed.

For information on updating the relation to other units, please see the appropriate section:




Unlock User

Preconditions

A user can be locked after a certain amount of unsuccessful attempts to log in. Administrative users can unlock the user and provide him a new password.

The requirements regarding the characters to be used or minimum length for the new password etc. can be configured by the administrator and thus will differ per service instance.
However, the user interface will support you by providing the password rules defined for your instance.

You will need to be logged in and have reading and writing permission for users.

Procedure Description

  1. Click the icon in the left area of the user's cell in the Users column.
  2. The user details will appear in read-only format as they were entered when the user was created.
  3. Click Edit to change the content of any of the fields.
    1. Provide a new password.
    2. Repeat the new password to avoid typos.
    3. Activate the No Locked radio button.

  4. Resume the dialog using the buttons at the bottom of the form (as explained for Create User).

Results

The updated user attributes are now stored on the back end. Other administrative users will need to refresh their view to see your changes.

Users imported from an external identity provider cannot be unlocked via the Administrator UI, nor can they change their passwords as described above. Instead they need to address the utilities of their external content provider.

By default, our service is configured in a way that the password never expires. However, in case your service instance is configured to mark passwords as expired after a configured number of days, and given the user knows his old password, he will be able to do this using the dialog described at Change your initial or an expired password. Thus an administrative user only needs to interfere when a user is locked.

The common dialog to edit a user's details will not empower administrative users to activate the locking radio buttons unless the user is locked already. However if the aim is to make sure the user cannot authenticate for a certain time, he can be deleted and restored later on.

Privileged User

Preconditions

A User with special needs to distribute Roles of newly installed Applications towards other Users / Groups can be marked as privileged user.

This empowerment should be granted very restrictively.

Only privileged users (e.g. Tenant Administrators) are able to create, update or delete other privileged users.

The concept of privileged users allows to mark specific users as privileged. As a result those users are able to perform some operations which other users are not allowed to perform.

The main reason for this concept is to restrict critical operations to a very limited set of users.
All other users should e.g. not be able to assign additional permissions to themselves (permission escalation) or to delete a privileged user.

Privileged Users
  • Privileged users who are able to create assignments between entities can use all entities for these assignments.
    This means that a privileged user is even able to assign additional permissions to himself or to some other user (e.g. via some role).
  • By default the administration user of each tenant is marked as privileged.
  • Only privileged users are able to create, update or delete other privileged users.
Non-privileged Users
  • Non-privileged users which are able to create assignments between entities can do this only if the action does not (implicitly) exceed the set of own permissions:
    • They can only assign a permission to a role if they have this permission themselves.
    • They can only assign a role to a user if the role contains only permissions which they have themselves.
    • They can only assign a role to a group if the role contains only permissions which they have themselves.
    • They can only assign a user to a group if the group (indirectly) contains only permissions which they have themselves.
    • They can only assign a parent group to a group if the parent group (indirectly) contains only permissions which they have themselves.
    • For all other entities there is no such restriction as these can not be used as part of a permission escalation scenario.

When installing, updating IM, or creating a new tenant the privileged flag will be set to all users, which are directly assigned to the IM Administrator role or the IM Tenant Administrator role.

Procedure Description

  1. Click the icon in the left area of the user's cell in the Users column.
  2. The user details will appear in read-only format as they were entered when the user was created.
  3. Click Edit to change the content of any of the fields.

    1. Activate one of the radio buttons in the Privileged section.

  4. Resume the dialog using the buttons at the bottom of the form (as explained for Create User).

Results

The updated user attributes are now stored on the back end. Other administrative users will need to refresh their view to see your changes.

The icon of a privileged user is decorated with a star.

Delete User

Preconditions

You will need to be logged in and have permission to read and delete users.

Procedure Description

  1. Drag the user you want to delete.
  2. Drop him on the recycle bin
  3. A dialog box appears with the option of confirming or canceling the deletion.
  4. Click Delete to confirm deleting the user.

Results

The user is marked as "deleted" in the back end and will disappear from the default view of the Web UI; it can now only be found in the recycle bin view (). Other administrative users will need to refresh their view to see your changes.

In case the affected user is currently logged in, this action will not automatically terminate his session.
However, the session will finish with his log out or at least after the pre-defined timeout. A deleted user will not be able to log in again.

Identify a self-deleted user

Self-deleted users can be found in the Recycle bin , as all other deleted elements. To view the recycle bin, click the "Switch to recycle bin" icon .

The quick view on moving the mouse over a self-deleted user will show this information respectively.

Additionally the read view will display the "self-deleted" state.

Restore User

Preconditions

You will need to be logged in and have permission to read and update users.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the user you want to restore.
  3. Drag and drop him on the "restore" area .
  4. A dialog box appears with the option of confirming or canceling the restore action.
  5. Click Restore to confirm.

Click the following icon to switch back to the default view.

Results

The user is restored in the back end and will now appear in the default view. Other administrative users will need to refresh their view to see your changes.

In case you need to restore a user who accidentally deleted his user account, that state is visible as well.

Delete User permanently

Preconditions

You will need to be logged in and have permission to read and permanently delete users.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the user you want to delete permanently.
  3. Drag and drop him on the "delete permanently" area .
  4. A dialog box appears with the option of confirming or canceling the permanent deletion.
  5. Click Delete permanently to confirm.

Click the following icon to switch back to the default view.

Results

The user is permanently deleted from the back end with no option to restore. Other administrative users will need to refresh their view to see your changes.

In case the affected user is currently logged in, this action will not automatically terminate his session.
However, the session will finish with his log out or at least after the pre-defined timeout. A deleted user will not be able to log in again.

Create a User-Group assignment

Preconditions

You will need to be logged in and have permission to create user-group relations.

The user and group you want to relate must both pre-exist (otherwise see Create User and Create Group).

Procedure Description

  1. Select and drag the user that should be added to the members of a particular group.
  2. Drop him on that group.
    In our example, Mr. Arnold becomes a member of the "Technical support team".
  3. The assignment is not automatically sent to the back end because you might want to create various other relations first and only then synchronize with the back end, all at once.
  4. To resume the assignment, use the appropriate link provided in the upper part of the application, or go to your list of outstanding actions and decide whether to proceed or cancel.
  5. To complete the assignment click Save changes.

Results

The new user-group relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin one of the related units:

  • Click the pin icon of the newly assigned user. The group will be highlighted. Additionally, the group now displays the "chain" icon.
  • Click the pin icon of the group. Now the new member will appear at the top of the Users column displaying the "chain" icon.
  • If the group is allocated particular roles and permissions, these will be highlighted as well, as the newly-created relation grants them automatically to all members.
  • In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.


Delete a User-Group assignment

Preconditions

You will need to be logged in and have permission to delete user-group relations.

The user-group relation you want to delete must pre-exist (otherwise see Create a User-Group assignment).

Procedure Description

  1. Starting with the User:
    1. Click the user's pin icon to highlight the groups of which he is a member.
    2. Select and drag the relevant group and drop it at the end of the columns, on the "remove assignment" area .
  2. Alternatively: Starting with the Group:
    1. Click the pin icon of the group to highlight the users.
    2. Drag the relevant user and drop it at the end of the columns, on the Remove assignment icon.
  3. The action is not immediately sent to the back end but stored in your list of actions pending execution. The relation icon next to the group changes, now displaying a red marker.
  4. Complete the action by either following the Save link in the upper section, or go to your list of unsaved changes and confirm with Save changes.

Results

The removal of the user-group relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin the user and you will see that the attributes stemming from the old group assignment (i.e. all roles and permissions assigned implicitly) have also disappeared.

Create a User-Role assignment

Preconditions

You will need to be logged in and have permission to create user-role relations.

The user and role you want to relate must both pre-exist (otherwise see Create User and Create Role).

Procedure Description

In our example, Mr. Arnold should be specifically accorded the privileges of a "Manager" role (as opposed to simply becoming a manager, e.g. via group membership as described in Create a User-Group assignment).

  1. Select and drag the user who should be allocated a particular role.
  2. Drop him on the role in question
  3. The assignment is not automatically sent to the back end, because you might want to create various other relations first and only then synchronize with the back end, all at once.
    To resume the assignment use the appropriate link provided in the upper part of the application or go to your list of outstanding actions and decide whether to proceed or cancel.
  4. To complete the role assignment, click Save changes.

Results

The new user-role relation is now stored on the backend. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin one of the related units:

  • Click the pin icon of the "Manager" role. The newly-assigned user will be highlighted. As you might have noticed "Arnold, John" now displays the chain icon, indicating some relation to other units:
  • Click the user's pin icon. All the roles granted to that user are highlighted.
  • In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.
Delete a User-Role assignment

Preconditions

You will need to be logged in and have permission to delete user-role relations.

The user-role relation you want to delete must pre-exist (otherwise see Create a User-Role assignment)

Procedure Description

  1. Starting with the User
    1. Click the pin icon of the user to highlight the roles he has been allocated.
    2. Select and drag the role and drop it at the end of the columns, on the "remove assignment" area .
    3. Our example shows the assigned directly "Manager" role, as well as other roles that were assigned by virtue of group membership.
       
    4. Drag the "Manager" role and drop it on the "remove assignment" area .
    5. If you try to drag and drop the "Network Administrator" role on the field for removing an assignment, this will not succeed, as the assignment was created via group (note this role’s chain icon)
  2. Alternatively: Starting with the Role:
    1. Click the pin icon of the role in question to highlight the users.
    2. Drag the user (displaying a chain icon) and drop him at the end of the columns, on the "remove assignment" area .
  3. The action is not immediately sent to the back end but stored in your list of actions pending execution. The relation icon next to the unit changes, now displaying a red marker.
  4. Complete the action by either following the Save link in the upper section, or go to your list of unsaved changes and confirm with Save changes.

Results

The removal of the user-role relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin one of the related units, and the other one should no longer be highlighted.

See also Role assignment using hierarchical groups.

Create a User-Permission assignment

Preconditions

You will need to be logged in and have permission to create user-group and user-role relations.

The user and group or role you want to relate must pre-exist (otherwise see Create UserCreate Group, and Create Role).

Procedure Description

A permission cannot be directly assigned to a user; thus, you will need to grant the user a permission via a group or role.

  1. Select the permission the user needs, and decide whether assigning it via a group or role would be more efficient (in order to still restrict permissions as much as possible).
  2. Drag and drop the user on the appropriate group or role.
  3. The assignment is not automatically sent to the back end, because you might want to create various other relations first and only then synchronize with the back end, all at once.
    To resume the assignment, use the appropriate link provided in the upper part of the application, or go to your list of outstanding actions and decide whether to proceed or cancel.
  4. To complete the assignment click Save changes.

Results

The new user-group or user-role relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin one of the related units. The related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.

For further details see also:

Delete a User-Permission assignment

Preconditions

You will need to be logged in and have permission to delete user-group and user-role relations.

Procedure Description

A permission cannot be directly assigned or un-assigned to a user; thus, if you have to restrict a user's permission, first you must analyze whether it was inherited via a group or role.

  1. Starting with the permission:
    1. Click the pin icon of the permission to highlight the roles and groups.
    2. Drag and drop the role or group at the end of the columns, on the "remove assignment" area .
  2. If the permission remains assigned, try to un-link also another related role or group.
  3. The un-link action is not immediately sent to the back end but stored in your list of actions pending execution. The relation icon next to any units you are un-linking now display a red marker.
  4. Complete the actions by either following the Save link in the upper section, or go to your list of unsaved changes and confirm with Save changes.

Results

The removal of the user-role (and/or user-group) relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin the permission and make sure the user you want to restricted is no longer highlighted.

For further details see also:

Administrative tasks for supporting user self-services

Bosch IoT Permissions provides a Web based user self-registration application which can be used as a default implementation or as a template for custom registration forms.
The Web application also contains a login form with password reset functionality.

The self-registration process is a sequence of three use cases:

  • User self-registration:
    • The user creates a new user account by filling out a registration form.
      • Required fields are: username, email address and the initial password.
      • The ID of the tenant is provided via the URL.
      • The browser language is stored in form of a user attribute.
    • The user submits the registration request to the Bosch IoT Permissions service.
    • The service validates and stores the given data.
  • Send activation email:
    • After the form was submitted successfully to the service, the Web application triggers the service to send an activation email to the given email address.
    • The email contains an activation link which contains the user ID, the tenant ID and an activation code.
  • Activate user account:
    • After receiving the activation email, the user needs to click the link prepared within the activation email to continue the self-registration.
    • By following the link within the activation email the user is delegated to a Web site provided by the user self-registration Web application.
    • The site has a button which needs to be pressed by the user to trigger the activation. It uses the user ID and the activation code to activate the user at the Bosch IoT Permissions service.
      The response of this call is used to pre-fill the login form with the name of the user. The tenant ID is passed within the URL.
    • The user account is active from now on and the user is therefore able to login at Bosch IoT Permissions service from now on.

The tasks in detail:

Manage the user self-service related settings

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 user self-service related settings of the respective tenant.

By default, the tenant is provisioned by Bosch IoT Permissions with default settings.
However, if a tenant needs to explicitly enable or disable self-service functionality or change the validity period for any self-service related codes, these can be easily changed via the UI.

Preconditions

You will need to be logged in and have permission to read and change the settings 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 self-service settings ...
     
  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.
  4. Edit the values you need to change, e.g. change the time how long a specific code should be valid for self-registration, or uncheck the corresponding checkbox to disable functionality.
  5. Confirm by clicking one of the buttons at the bottom of the dialog box.
    1. Save & Close - will store the new settings and close the dialog box.
    2. Reset to default - will delete the custom settings. As a result, the default settings 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 self-service settings.

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 attempts any self-service function, the new settings will be taken into account, according to the new values.

Additionally to enabling self-service functions, you will need to provide email templates. Find details at Administrative tasks for supporting user self-services > Edit email templates.

Managing email templates for user self-services

The emails necessary to communicate to the users must be explicitly defined for each tenant. 

In order to activate this service out of the box for all our customers in the cloud, all descendants of the DEFAULT tenant will be provided a default version of these email templates.

The DEFAULT tenant does not activate this service itself, however for test cases you can activate the functionality by editing the templates accordingly.

We support following types:

  • "User activation" template - such a mail will be sent to a self-registered user to activate his user account
  • "Password reset" template - such a mail will be sent to a user whenever he requests a password reset
  • "Email address update" template - such a mail will be sent to a user whenever he requests to change the email address associated to his user account.

See procedure description at Tenant Management > Edit email templates.

The email template administrator is supposed to fulfil following requirements:

  • Is registered as user within Bosch IoT Permissions and empowered at least with permission EMAIL_TEMPLATE_ADMINISTRATION, which is part of the default IM Tenant Administrator role and the IM Default Offering.
  • Should be familiar with our concepts described in the Developer Guide

  • Should be familiar with the FreeMarker syntax see http://freemarker.org/docs/dgui.html.
  • Should be aware of the validity period for the codes which are entangled within the links in the specific email. These are configured as IM backend properties.
  • Needs to be aware of the domain specific userAttributes he is allowed to use for personalizing the email content.
  • Needs to be aware of the actual deployment of the tenant-specific application and the syntax to compose the links.
Edit email templates

Preconditions

You will need to be logged in and have permission to edit email templates for the tenant you are currently logged in for.
The administrator of the DEFAULT 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 email templates...
  3. A dialog opens, providing you further guidance:
    1. A drop down to select the email template type
    2. A button to load an example
    3. An input field as edit area
    4. Buttons to close the dialog box.
  4. Select the type of email you need to edit.
    At the time of writing we support following types:
    1. User activation
    2. Password reset
    3. Email address change
  5. Click Load example to pre-fill the editing area with the according example.
  6. Confirm by clicking one of the buttons at the bottom of the dialog box.
    1. Save - will store the entries edited so far. From there you can continue editing.
    2. Save & Close - will store your entries and close the dialog box.
    3. Cancel - will ignore the latest entries and close the dialog box.

Results

If you have successfully changed the template, the next emails of this type will look accordingly.

To "disable" the distribution of a specific type of email, just store an empty version for that type.

To "reset" the content to the default delivery of the IM service use the "Reset to default" button.

Identifying self-registered users

Self-registered users look and behave the same as all other users from the administrator's point of view.

The only difference to other users is visible after the registration form has been submitted and while the user activation is pending.

The following screenshot shows a user who has not yet confirmed his registration by clicking the "activation link" received via email.

In case a self-registered user requires your support (e.g. due to a typo while registering) please Edit the correct data and Save it. Afterwards you can and re-send an activation email to the new email address.

An activated user account does not show any particular differences compared with a user who was created another way than by self-registration.

Administrative tasks for supporting users of external identity providers

Users originating from an external identity provider (e.g. OpenID Connect provider) can be managed in Bosch IoT Permissions in order to assign them to groups, roles, etc..
These users will be authenticated based on the credentials persisted in the external authentication provider.

External users are added to Bosch IoT Permissions individually, when they log in for the first time at our service.

They are identified with following icon . The Administrator UI will support you in creating and deleting assignments to other Bosch IoT Permissions entities.

For authentication purposes (i.e. token signature check) Bosch IoT Permissions accesses the external provider in some cases in real time. As a result, authentication will fail if the external provider is unavailable.

The tasks in detail:

Manage the access via external identity providers

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 settings related to the external identity providers of the respective tenant.

By default, the tenant is provisioned by Bosch IoT Permissions with default settings.
However, if a tenant needs to explicitly enable or disable the external identity providers he integrates with, these settings can be easily changed via the UI.

Users originating from an external identity provider (e.g. OpenID Connect provider) can be managed in Bosch IoT Permissions in order to assign them to groups, roles, etc..
These users will be authenticated based on the credentials persisted in the external authentication provider.

External users are added to Bosch IoT Permissions individually, when they log in for the first time at our service.

They are identified with following icon . The Administrator UI will support you in creating and deleting assignments to other Bosch IoT Permissions entities.

For authentication purposes (i.e. token signature check) Bosch IoT Permissions accesses the external provider in some cases in real time. As a result, authentication will fail if the external provider is unavailable.

Preconditions

You will need to be logged in and have permission to read and change the settings 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 identity providers ...
  3. A dialog opens, providing you further guidance:
    1. The left column describes all possible settings.
    2. The second column shows the current values.
  4. Edit the values you need to change, e.g. allow additionally to log in via Google.
  5. Confirm by clicking one of the buttons at the bottom of the dialog box.
    1. Save & Close - will store the settings and close the dialog box.
    2. Reset to default - will delete the custom settings. As a result, the default settings 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 settings for external identity providers allowed for your users when using the default login mask provided by Bosch IoT Permissions.

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 tries to log in at our service user interfaces, the login dialog will apply the new values.

Example

The box checked for Bosch and Google will result in the following login page:

In case you prefer not to allow any users of an external identity provider to log in for your tenant, please make sure the checkboxed are unchecked, as the default offering comes with the allowance for "Bosch" accounts.

Identifying external users

A user provided by an external system is represented by the following icon . Hence, an administrative user can easily identify him.

E.g. in case of a forgotten password the Bosch IoT Permissions administrative user can not reset his password.

However, as the username equals the email address he has subscribed with at the external provider, it should be pretty clear where the user might try next:

Role assignment via All Users group

The "All Users" group is created for every tenant automatically and behaves slightly different than common groups.

Within the Web user interface the symbol used for this group is .

As an administrative user, you can add all roles your users will need to this group, thus defining a set of rights which all users of your tenant will be granted automatically.

As soon as a new user is created, he is automatically a member of the "All Users" group and is thus already empowered with the rights defined for this group.

Find details at Group Management.

Group Management

Group
A group is an organizational unit that is useful for grouping together users with similar functions.

Within the Web user interface the symbol used for a group is .

As groups are ordered hierarchically, each group that includes sub-groups is called a parent-group. A user who is assigned to a particular group is automatically also a member of all higher-ranking groups in the hierarchy.

When managing a group, keep the following concepts and restrictions in mind:

  • Each group belongs to exactly one tenant.
  • The group's name must be unique within that tenant.
  • The set of permissions that a group holds is a union of all permissions from:
    • group - role assignments
    • roles assigned to the group's parents in the hierarchy.
  • A group can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries, etc. (except for the "recycle bin" view).
  • Deleting a group also deletes
    • all existing relations to users, roles etc.
    • all sub-groups and their assignments.

The All Users Group is created for every tenant automatically and behaves slightly different than common groups:

  • All users of this tenant are assigned to this group automatically.
  • Within the Web user interface the symbol used for this group is .
  • You will not be able to manually add or delete the membership to this group.
  • You will not be able to create sub-groups of the All Users Group.
  • You will not be able to delete the group explicitly. However, when deleting and/or permanently deleting a tenant, its "All Users" group will also be deleted.
  • You will not be able to restore the group explicitly. However, when restoring a tenant this group will also be restored.

As an administrative user, you can add all roles your users will need to this group, thus defining a set of rights which all users of your tenant will be granted automatically.

Examples

Create Group

Preconditions

You will need to be logged in and have permission to create groups.

Procedure Description

  1. Click the "add group" icon .
  2. The Groups column will display a form for completing all the information required to create a group.
  3. You must complete at least all required fields in the dialog box (marked * )
  4. Confirm by clicking one of the buttons at the bottom of the dialog box:
    1. Save - will display a preview of the entries edited so far.
      From there you can continue with
      1. Edit - to amend your entries 
      2. Close - to store the new user.
    2. Save & Close - will store your entries and display all groups in the Groups column.
    3. Cancel - will ignore the entries and resume the creation dialog, displaying all groups in the Groups column.

Results

The new group is now available and will be displayed in alphabetical order in the Groups column.

Create a Sub-Group

For a fine-grained assignment of permissions to just part of a group, you can organize your users in sub-groups. 

The members of a sub-group will automatically inherit all roles and permissions granted to the parent group, but they can also be granted exclusive additional permissions.

The user interface offers two ways to create sub-groups:

  • Select the parent group at creation
  • Edit an existing group (see Update Group) and assign a parent.

Further details and examples are available at Role assignment using hierarchical groups.

Read Group

Preconditions

You will need to be logged in and have permission to read groups.

Procedure Description

  1. The Groups column displays all groups in alphabetical order.
  2. For a quick-view of a group's details, hover your mouse pointer over the group.
  3. Click the group's icon to read more details.
  4. For a quick-view of the relations to other elements, click the pin icon, which is revealed by moving the mouse pointer over the group cell.

    Click the group's pin icon again to clear the highlighting.
  5. Alternatively: Use the search field at the top of the Groups column to quickly find a group.

Results

The group's details are now displayed like a tooltip.

Clicking the pin icon, which is revealed by moving the mouse pointer over the group cell, will highlight all users as well as all roles and permissions assigned to that group. In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.

Update Group

Preconditions

You will need to be logged in and have reading and writing permission for groups.

Procedure Description

  1. Click the icon in the left area of the group's cell in the Groups column.
  2. The group details will appear in read-only format as they were entered when the group was created.
  3. Click Edit to change the content of any of the fields.
    Our example shows how to provide a German group description.
  4. Resume the dialog by using the buttons at the bottom of the form (as explained for Create Group).

Results

The updated group attributes are now stored on the back end. Other administrative users will need to refresh their view to see your changes.

For information on updating the relation to other elements, please see the appropriate section:

Delete Group

Preconditions

You will need to be logged in and have permission to read and delete groups.

Procedure Description

  1. Drag the group you want to delete.
  2. Drop it on the recycle bin
  3. A dialog box appears with the option of confirming or canceling the deletion.
  4. Click Delete to confirm deleting the group.

Note: Deleting a group that was assigned as a parent to other groups will also delete all its sub-groups.

Results

The group is marked as "deleted" in the back end and will disappear from the default view of the Web UI; it can now only be found in the recycle bin view (). Other administrative users will need to refresh their view to see your changes.

Deleting a group will also delete any related assignments of roles, users etc.
If a user was automatically granted permissions via the group that has now been deleted, the new restriction will apply immediately (without notifying the user), at the latest when the user next makes a request requiring such a permission,

The Administrator UI will not enable you to update or delete the initial set of Bosch IoT Permissions entities (i.e. the IM application itself including its group, roles and permissions, the default domain, tenant, offering, tenant relation) as these are elementary parts of the application and are therefore protected for manipulation. It is also not possible to remove or to create new assignments between Bosch IoT Permissions entities. When trying to manipulate such entities or relations, an exception will be thrown by the service.
There are three entities which have some special rules:

  • The default user (Admin) can be updated, deleted and erased.
    However, in case of deleting this user, make sure another user has the same privileges.
  • The default tenant (DEFAULT) can be updated but not deleted.
  • The All Users group cannot be updated, deleted or erased.
    It is not possible to remove users from this group (all users are assigned) but it is possible to assign roles to this group.

Example when trying to delete the IM application.

Restore Group

Preconditions

You will need to be logged in and have permission to read and update groups.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the group you want to restore.
  3. Drag and drop it on the "restore" area .
  4. A dialog box appears with the option of confirming or canceling the restore action.
  5. Click Restore to confirm.

Note: Restoring a group (e.g. Accounting)  does not automatically restore any of its sub-groups (e.g. Controlling). Thus, in our example you would need to perform the procedure twice over. However, you can select both and drop them in the restore area simultaneously.

Click the following icon to switch back to the default view.

Results

The groups are restored in the back end and will now appear in the default view. Other administrative users will need to refresh their view to see your changes.

Delete Group permanently

Preconditions

You will need to be logged in and have permission to read and permanently delete groups.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the group you want to delete permanently.
  3. Drag and drop it on the "delete permanently" area .
  4. A dialog box appears with the option of confirming or canceling the permanent deletion.
  5. Click Delete permanently to confirm.

Click the following iconto switch back to the default view.

Results

The group is permanently deleted from the back end with no option to restore. Other administrative users will need to refresh their view to see your changes.

Create a Group-User assignment

A description of this procedure is provided in the section Create a User-Group assignment.

Example

Mr. Arnold should become a member of the Controlling group:

This assignment automatically grants the user all roles that were assigned to the group and all its parent groups.

Delete a Group-User assignment

A description of this procedure is provided in the section Delete a User-Group assignment.

Create a Group-Role assignment

Preconditions

You will need to be logged in and have permission to create group-role relations.

The group and role you want to relate to each other must both pre-exist (otherwise see Create Group and Create Role).

The most efficient way to provide all users of your tenant with an initial set of rights is to assign all roles they will need to the "All Users" group (decorated ).


Procedure Description

In our example, the "Technical support team" will be assigned the "User Admin" role. Thus, all members of the group - see Create a User-Group assignment - are also automatically granted the same role, and thus, all permissions associated with this role.

  1. Select and drag the group that should be allocated the particular role.
  2. Drop it on the role in question
  3. The assignment is not automatically sent to the back end because you might want to create various other relations first and only then synchronize with the back end, all at once.
    To resume the assignment, use the appropriate link provided in the upper part of the application, or go to your list of outstanding actions and decide whether to proceed or cancel.
  4. To complete the assignment, click Save changes.

Results

The new group-role relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin one of the related units:

  • Click on the pin icon of the "User Admin" role. The newly-assigned group will be highlighted.
    Our example shows that "Mr. Arnold" was assigned the role via group membership, while the "Admin, Admin" was assigned the role directly.
  • Click on the pin icon of the "Technical support team" group. All roles granted to the group will be highlighted.
  • In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column. 

The steps to assign an element to a role are pretty much the same for all types of units.
If you need a restrictive role assignment, however, keep in mind that assigning a role to a group grants the associated permissions to all members of this group and to all members of its sub-groups.
See Role assignment using hierarchical groups.

Delete a Group-Role assignment

Preconditions

You will need to be logged in and have permission to delete group-role relations.

Procedure Description

The steps to delete the assignment between two elements are pretty much the same for all types of element.

Just drag one of the related elements and drop it on the remove assignment area . Then confirm to save the change.

If you need a liberal role assignment, however, keep in mind that deleting a group-role relation will restrict not only the rights of all members of this group but also those of all members of its sub-groups.
See Role assignment using hierarchical groups.

Example

You cannot simply un-assign the "Controlling" group from the "Accountant" role as the role was assigned to the parent group.
If you remove the assignment between "Accounting" group and "Accountant" role, all members of both groups will be affected.

Results

The removal of the group-role relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin the group and you will see, that the attributes stemming from the old role assignment (i.e. all permissions assigned automatically) have also disappeared.

Create a Group-Permission assignment

A permission cannot be directly assigned to a group; thus, you will need to grant the permission via a role.

If you need to create a relation between a permission and a group, proceed as follows:

  1. Create a Role.
  2. Assign the Permission to the Role.
  3. Assign the Role to the Group.

If you need to provide a permission to all users of your tenant, assign the Role to the "All Users" group (decorated ).

If you need a restrictive permission assignment, however, keep in mind that a group assignment provides permission to all members of this group and all members of its sub-groups.

Delete a Group-Permission assignment

A permission cannot be directly assigned or un-assigned to a user; thus, if you have to restrict a user's permission you must first analyze whether it was inherited via a group or role.

See Delete a User-Permission assignment.

If you need a liberal permission assignment, however, keep in mind that by deleting a group-permission relation you will restrict not only the rights of all members of this group but also those of all members of its sub-groups.

Role assignment using hierarchical groups

We assume that the following users, hierarchical groups, and roles exist, an that they are all assigned to each other as shown in the figure.

These relations enable the users as follows:

User A

User A will have all permissions of Group 1 and thus all permissions of Role x

User B

User B will have all permissions of Group 1.1 and thus

  • all permissions of Role y and z
  • and all permissions inherited from the parent group, which would be all permissions of Group 1 and thus all permissions of Role x
User C

User C will have all permissions of Group 1.1.1 and thus and all permissions inherited from both parent groups.

Role Management View

The Administrator UI contains nine columns which correspond to one type of entity each. When using the UI with all columns enabled on a monitor with small resolution, there might raise some usability inconveniences, e.g. forcing you to collapse some of the columns to get more space for the other ones.

In order to address this problem the Administrator UI allows to define customized views, which hide some of the columns which are assumed to be not necessary for completing a simple task.

The Role Management view addresses:

The IM Role Manager role holds all permissions one would need to work in this view.

Role name IM Role Manager
Description Manages roles and permissions
Permissions 10
Technical name RoleManager
Permission name Description Technical name
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Modify 'role-permission' relations Add or remove relations between roles and permissions RELATION_ROLE_PERMISSION
Permissions - query Allows to query permissions READ_PERMISSION
Roles - create Allows to create roles CREATE_ROLE
Roles - delete Allows to delete roles DELETE_ROLE
Roles - erase Allows to erase roles ERASE_ROLE
Roles - query Allows to query roles READ_ROLE
Roles - update Allows to update roles UPDATE_ROLE
Tenants - query Allows to query tenants READ_TENANT

Example:

Role Management

Role
A role is a job function within the context of an organization. The associated semantic regards rights and duties (the authority and responsibility) conferred on the user to whom the role is assigned. Usually, a role encapsulates a range of permissions that are necessary to perform its function.

A role can be defined either by a tenant or by an application. While application roles are delivered as part of the application, tenant roles are created by an administrator user. In the Web user interface, the following icon is used for representing a tenant role . A role provided by an application is marked by the following icon  and cannot be modified in the Web user interface.

There are predefined roles that are generated during the service instantiation, namely  "ServiceAdministrator",  "ApplicationInstaller", "RoleManager","TenantAdministrator", "TenantManager" and "UserManager".

When managing a role, keep the following concepts and restrictions in mind:

  • Each role has exactly one tenant or one application instance responsible for its creation.
  • The tenant role's name must be unique per tenant.
  • The application role's name must be unique per application.
  • A role can group permissions, and the same permission can be assigned to multiple roles.
  • A tenant role can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries etc. (except for the "recycle bin" view).
  • Deleting a role does not delete the permissions themselves but the association of these permissions to users, groups, etc.

The Administrator UI will not enable you to create, update or delete application roles (marked with the icon ) as those entities are within the responsibility of the application itself.

Examples

Create Role

Preconditions

You will need to be logged in and have permission to create roles.

Procedure Description

  1. Click the "add role" icon .
  2. The Roles column will display a form for completing all the information required to create a role.
  3. You must complete at least all required fields in the dialog box (marked * )
  4. Confirm by clicking one of the buttons at the bottom of the dialog box:
    1. Save - will display a preview of the entries edited so far.
      From there you can continue with
      1. Edit - to amend your entries 
      2. Close - to store the new role.
    2. Save & Close - will store your entries and display all roles in the Roles column.
    3. Cancel - will ignore the entries and resume the creation dialog, displaying all roles in the Roles column.

Results

The new role is now available and will be displayed in alphabetical order in the Roles column.

Application Role

The Roles required within an Application cannot be created with this user interface but are part of the Application itself and are just imported within the service.
However, these Application Roles can be offered/related to groups and users the same way as assigning a tenant-generated role.
Read Role

Preconditions

You will need to be logged in and have permission to read roles.

Procedure Description

  1. The Roles column displays all roles in alphabetical order.
  2. For a quick-view of a role's details hover your mouse pointer over the role. A tooltip appears, displaying some of the role's details.
  3. Click the role's icon to read more details.
  4. For a quick-view of the relations to other elements, click the pin icon, which is revealed by moving the mouse pointer over the role cell.

    Click the pin icon again to clear the highlighting.
  5. Alternatively: Use the search field at the top of the Roles column to quickly find a role.

Results

The role's details are displayed like a tooltip.

Clicking the pin icon, which is revealed by moving the mouse pointer over the role cell, will highlight all users as well as all groups, permissions etc. that have been assigned. In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.

Filter roles list

Click the filter iconin the column header to show which units are supported for filtering roles. Drag the unit that should restrict the list and drop it onto the column header.

The Roles column can be filtered by ONE specific application.

If an application is applied as a filter, the following entries will be displayed:

  • the roles that are defined by this application and
  • the roles that include permissions from this application.
Read a role's details

Click the role's icon to open its details view.

Example:

Click Close to collapse the details view.

Update Role

Preconditions

You will need to be logged in and have reading and writing permission for roles.

Procedure Description

  1. Click the icon in the left area of the role's cell in the Roles column.
  2. The role's details will appear in read-only format as they were entered when the role was created.
  3. Click Edit to change the content of any of the fields. 
    Our example shows how to provide a German role description.

    Note: You will not be able to edit an application role (marked  ) as this element is part of the application itself.
  4. Resume the dialog by using the buttons at the bottom of the form (as explained for Create Role).

Results

The updated role attributes are now stored on the back end. Other administrative users will need to refresh their view to see your changes.

For information on updating the relation to other elements, please see the appropriate section:

Delete Role

Preconditions

You will need to be logged in and have permission to read and delete roles.

Procedure Description

  1. Drag the role you want to delete.
  2. Drop it on the recycle bin.
  3. A dialog box appears with the option of confirming or canceling the deletion.

  4. Click Delete to confirm deleting the role.

Note: You will not be able to delete an application role (marked ), as this element is part of the application itself.

Results

The role is marked as "deleted" in the back end and will disappear from the default view of the Web UI; it can now only be found in the recycle bin view . Other administrative users will need to refresh their view to see your changes.

Deleting a role will not automatically delete the permissions grouped within the role, but it will automatically delete the potentially existing relations with users, groups, or offerings.
If a user was automatically granted permissions via the role that has now been deleted, the new restriction will apply immediately (without notifying the user), at the latest when the user next makes a request requiring such a permission.

Restore Role

Preconditions

You will need to be logged in and have permission to read and update roles.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the role you want to restore.
  3. Drag and drop it on the "restore" area .
  4. A dialog box appears with the option of confirming or canceling the restore action.

  5. Click Restore to confirm.

Click the following icon to switch back to the default view.

Results

The role is restored in the back end and will now appear in the default view. Other administrative users will need to refresh their view to see your changes.

Delete Role permanently

Preconditions

You will need to be logged in and have permission to read and permanently delete roles.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the role you want to delete permanently.
  3. Drag and drop it on the "delete permanently" area .
  4. A dialog box appears with the option of confirming or canceling the permanent deletion.
  5. Click Delete permanently to confirm.

Click the following icon  to switch back to the default view.

Results

The role is permanently deleted from the back end with no option to restore. Other administrative users will need to refresh their view to see your changes.

Create a Role-User assignment
Delete a Role-User assignment

A description of this procedure is provided in the section Delete a User-Role assignment.

Create a Role-Group assignment
Delete a Role-Group assignment

A description of this procedure is provided in the section Delete a Group-Role assignment.

Create a Role-Permission assignment

Preconditions

You will need to be logged in and have permission to create role-permission relations.

The role and permission you want to relate to each other must both pre-exist.

Procedure Description

In our example, the self-generated "My new role" is allocated some query permissions (these permissions are exposed by the IM application itself).

  1. Use "query" as the search criterion in the Permissions column.
  2. Select all the results you want to have grouped within the role and drop them on the role.
  3. The assignment is not automatically sent to the back end because you might want to create various other relations first and only then synchronize with the back end, all at once.
    To resume the assignment, use the appropriate link provided in the upper part of the application, or go to your list of outstanding actions and decide whether to proceed or cancel.
  4. To complete the assignment click Save changes.

Results

The new role-permission relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin one of the related units:

  • Click the permission's pin icon. All roles granted this permission will be highlighted.
  • Click the role's pin icon. All assigned permissions will be highlighted.
  • In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.


Delete a Role-Permission assignment

Preconditions

You will need to be logged in and have permission to delete role-permission relations.

Procedure Description

The steps to delete the assignment between two elements are pretty much the same for all types of element.

Just drag one of the related elements and drop it on the "remove assignment" area . Then confirm to save the change.

Results

The removal of the role-permission relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin the role and you will see, that the attributes stemming from the old permission assignment (i.e. the relation to its domains and application) have also disappeared.

Create a Role-Offering assignment
Delete a Role-Offering assignment

Permission Management

Permission
A permission is a fine-grained concept for granting access to operations and/or data. Usually, a role encapsulates a set of permissions that are required for performing its tasks.

Within the Web user interface, the following icon is used to indicate a permission .

There is a set of predefined permissions to facilitate the management of the service instance (e.g., "CREATE_TENANT", "CREATE_USER", "DELETE_USER", etc.). These permissions are grouped already for the default roles e.g. "ServiceAdministrator",  "TenantAdministrator" etc.. The default tenant administrator, for example, needs all permissions to set up users, groups roles and to relate them. In order to delegate some duties to other users, the administrator can easily assign roles, such as the "RoleManager" role, to further administrator users.

Currently, the Administrator UI will not assist you in creating permissions. They are delivered as part of the applications.

When managing a permission, keep the following concepts and restrictions in mind:

  • Each permission has exactly one application instance responsible for its creation.
  • A permission's name must be unique per application.
  • The same permission can be assigned to multiple roles.
  • Deleting a role does not delete the permissions themselves but the association of these permissions to users, groups, etc.

The Administrator UI will not enable you to create, update or delete permissions, as those entities fall under the responsibility of the application itself.

Examples

Read Permission

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to read permissions.

Procedure Description

  1. Expand the Permissions column.
  2. The column displays all permissions (defined by the applications installed in your service instance) in alphabetical order.
    By default there should be ca. 60 permissions defined by IM itself. Their names should be self-explanatory.
  3. For a quick-view of a permission's details hover your mouse pointer over the permission. A tooltip appears, displaying some of the permission's details.
  4. Click the permission's icon to read more details.
  5. Click Close to return to the list of all permissions.

Alternatively: Use the search field at the top of the Permissions column to quickly find a permission.

Clicking the pin icon, which is revealed by moving the mouse pointer over the permission cell, will highlight the related elements (e.g. the application they belong to, roles assigned to the permission). In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.

Example

Filter permission list

Click the filter icon in the column header to show which units are supported for filtering permissions. Drag the unit that should restrict the list and drop it onto the column header.

The Permissions column can be filtered by a specific application. If an application is applied as a filter, the permissions that are defined by this application will be shown.

Create a Permission-User assignment

A permission cannot be directly assigned to a user; thus, you will need to grant the user a permission via a group or role.

See Create a User-Permission assignment.

Delete a Permission-User assignment

A permission cannot be directly assigned or un-assigned to a user; thus, if you need to restrict a user's permission you must first analyze whether it was inherited via group or role.

Example

According to the following figure, two users were granted the permission "Users - create":

  1. "Admin, Admin" was assigned the permission via the role "IM Administrator" (these are the default names that can be configured at installation).
  2. "Arnold, John", was assigned the permission via the group "Technical support team", which was assigned the role "User Admin".


Create a Permission-Role assignment

A description of this procedure is provided in the section Create a Role-Permission assignment.

The following figure shows an example of a self-generated role for reading basic IM elements:

Delete a Permission-Role assignment

A description of this procedure is provided in the section Delete a Role-Permission assignment.

Create a Permission-Offering assignment

A description of this procedure is provided in the section Create an Offering-Permission assignment.

Delete a Permission-Offering assignment

A description of this procedure is provided in the section Delete an Offering-Permission assignment.

Application Management

Application Instance
An application instance is a logical instance (e.g. one installation of a business application) that defines permissions and roles and uses the Bosch IoT Permissions authentication and authorization services.

Within the Web user interface, the following icon is used for an application .
Currently, the user interface will not support you with creating or updating an application instance.

There is a default application instance (assigned to the default domain and the default tenant) that is reserved for the Identity Management application itself.
(The default name is "IM", however, this initial name can be configured before the first Service installation. The default role to grant all permissions, which are necessary for an administrator user to be able to install an application instance, is "ApplicationInstaller".)

When managing an application instance, keep the following concepts and restrictions in mind:

  • An application instance's name must be unique per Permissions service and may not contain the pipe (|) nor the paragraph ($) character.
    Entities related to application instances (instance roles, permissions, offerings) also need to consider not using these characters.

  • The application instance's name should be named like the product or solution.
    In case of various installations, please use a talking prefix or ending (e.g. MySolution for the production installation and MySolution_Test for the test installation). It is therefore recommended to make the application instance name configurable. The configured value must then be used in permission or role checks. This enables the application to be registered multiple times at the same Permissions service with distinct names.
  • Deleting a domain will also delete all application instances, their roles, permissions, etc.

  • Deleting an application will also delete all application roles, permissions, etc.

  • The owner of an application instance is a tenant (i.e. the domain owner).

  • The application itself is responsible for defining the roles and permissions to properly restrict the execution of the application's operations.
    Bosch IoT Permissions only checks whether the user trying to perform a task has the required permissions (especially if the user's context covers more than the data of the tenant to which he belongs).

The Administrator UI will not enable you to update or delete the initial set of Bosch IoT Permissions entities (i.e. the IM application itself including its group, roles and permissions, the default domain, tenant, offering, tenant relation) as these are elementary parts of the application and are therefore protected for manipulation. It is also not possible to remove or to create new assignments between Bosch IoT Permissions entities. When trying to manipulate such entities or relations, an exception will be thrown by the service.
There are three entities which have some special rules:

  • The default user (Admin) can be updated, deleted and erased.
    However, in case of deleting this user, make sure another user has the same privileges.
  • The default tenant (DEFAULT) can be updated but not deleted.
  • The All Users group cannot be updated, deleted or erased.
    It is not possible to remove users from this group (all users are assigned) but it is possible to assign roles to this group.

Example when trying to delete the IM application.

Examples

Create Application

The user interface will not support you with creating or updating an application, application role, or application permission, but only in assigning these to other units (e.g. by grouping a permission set to a role and binding it to a group, user or offering).

Creating permissions and attaching permission checks on executing some application is the task of application development.

Detailed information about the Application Instance Resource can be found in our Developer Guide. There, we also provide an example of how to "Register a complete application instance using the Service API 1".

Read Application

All applications are listed in alphabetical order in the Applications column.

For a quick-view of the relations to other elements click the pin icon, which is revealed by moving the mouse pointer over the application's cell. While an element is pinned, all related elements will appear at the top of the column and are highlighted green. Additionally, the total number of elements assigned to the pinned one will be displayed at the foot of the column.

Read an application's details

Click the application's icon to open its details view.

Example:

Click Close to collapse the details view.

Update Application

The user interface will not support you with creating or updating an application, application role, or application permission, but only in assigning these to other units (e.g. by grouping a permission set to a role and binding it to a group, user or offering).

Creating permissions and attaching permission checks on executing some application is the task of application development.

Detailed information about the Application Instance Resource can be found in our Developer Guide. There, we also provide an example of how to "Register a complete application instance using the Service API 1".

Delete Application

Preconditions

You will need to be logged in and have permission to read and delete applications.

Procedure Description

  1. Drag the application you want to delete.
  2. Drop it on the recycle bin area .
  3. A dialog box appears with the option of confirming or canceling the deletion.
    There you get an overview of all applications which will be deleted.
  4. Click Delete to confirm deleting the application.
    This action deletes the application, roles, permissions, etc., along with all assignments these elements were involved in.

Results

The application is marked as "deleted" in the back end and will disappear from the default view of the Web UI; it can now only be found in the recycle bin view (). Other administrative users will need to refresh their view to see your changes.

Deleting an application will also delete all its subordinate units (e.g. application roles, permissions, offering types that were created while registering that application within the service) and all relations to other entities (e.g. tenant roles which grouped the permissions with permissions of other applications, offerings and tenant relations exposed toward other tenants).

If a user was automatically granted permissions via a role that has now been deleted, the new restriction will apply immediately (without notifying the user), at the latest when the user next makes a request requiring such a permission.

The Administrator UI will not enable you to update or delete the initial set of Bosch IoT Permissions entities (i.e. the IM application itself including its group, roles and permissions, the default domain, tenant, offering, tenant relation) as these are elementary parts of the application and are therefore protected for manipulation. It is also not possible to remove or to create new assignments between Bosch IoT Permissions entities. When trying to manipulate such entities or relations, an exception will be thrown by the service.
There are three entities which have some special rules:

  • The default user (Admin) can be updated, deleted and erased.
    However, in case of deleting this user, make sure another user has the same privileges.
  • The default tenant (DEFAULT) can be updated but not deleted.
  • The All Users group cannot be updated, deleted or erased.
    It is not possible to remove users from this group (all users are assigned) but it is possible to assign roles to this group.

Example when trying to delete the IM application.

Restore Application

Preconditions

You will need to be logged in and have permission to read and update applications.

Procedure Description

  1. Open the recycle bin view ().
  2. Drag the application you want to restore.
  3. Drop it on the "restore" area .
  4. A dialog box appears with the option of confirming or canceling the restore action.

  5. Click Restore to confirm.

Click the following icon  to switch back to the default view.

Results

The application is restored in the back end and will now appear in the default view. Other administrative users will need to refresh their view to see your changes.

Restoring the application will not implicitly restore its permissions, roles, etc.

Thus, if your application really needs to be restored (instead of being permanently deleted and re-registered via Service API 1) a good order would be restoring:

  1. The application itself
  2. The permissions
  3. The roles
  4. The offerings

After restoring all entities completely, the users, groups etc. which were formerly granted those permissions will be able to use them again.
Mind however, that if the time the application was deleted overlaps with a user's session it might happen that the user needs to explicitly refresh his context (by logout and re-login).

Delete Application permanently

Preconditions

You will need to be logged in and have permission to read and permanently delete applications.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the application you want to delete permanently.
  3. Drag and drop it on the "delete permanently" area .
  4. A dialog box appears with the option of confirming or canceling the permanent deletion.
  5. Click Delete permanently to confirm.

Click the following icon  to switch back to the default view.

Results

The application is permanently deleted from the back end with no option to restore. Other administrative users will need to refresh their view to see your changes.

Deleting an application will also delete all its subordinate units (e.g. application roles, permissions, offering types that were created while registering that application within the service) and all relations to other entities (e.g. tenant roles which grouped the permissions with permissions of other applications, offerings and tenant relations exposed toward other tenants).

Create an Application-Domain assignment

Currently, the Administrator UI will not assist you in assigning a domain to an application (or an application to a domain).

The domain where the application should be displayed must be specified while installing the application.

For more details see Developer GuideApplication Instance Resource.

Delete an Application-Domain assignment

The domain where the application should be displayed must be specified while installing the application.

For more details see Developer GuideApplication Instance Resource.

Domain Management

Domain
A domain is an infrastructure entity that defines a realm of administrative autonomy, authority, or control within the Bosch IoT Permissions service.

Within the Web user interface, the following icon is used for a domain .

There is a default domain assigned to the default tenant that is reserved for the IM instance itself.
(The default the name is "IAP".)

Usually, the main task of a domain is to group the application instances whose authorization is to be managed.

When managing a domain, keep the following concepts and restrictions in mind:

  • A domain's name must be unique per tenant.
  • A domain can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries, etc. (except for the "recycle bin" view).
  • Deleting a domain will also delete all application instances, their roles, permissions, etc.

Examples

Create Domain

Preconditions

You will need to be logged in and have permission to create domains.
The administrator of the DEFAULT tenant should already have assigned all permissions defined by the IM application.

Procedure Description

  1. Click the "add domain" icon .
  2. The Domains column will display a form for completing all the information required to create a domain.

  3. You must complete at least all the required fields in the dialog box (marked * )

  4. Confirm by clicking one of the buttons at the bottom of the dialog box:

    1. Save - will display a preview of the entries edited so far. 
      From there you can continue with:

      1. Edit - to amend your entries 
      2. Close - to store the new domain.
    2. Save & Close - will store your entries and display all domains in the Domains column.
    3. Cancel - will ignore the entries and resume the creation dialog, displaying all domains in the Domains column.

Results

The new domain is now created and will be displayed in alphabetical order in the Domains column.

Now the administrator can inform users that need to install an application (programmatically) of the appropriate domain.
If the same "Application A" is installed on two domains, the application roles and permissions will appear twice in the user interface. Supported by the feature of highlighting related elements the DEFAULT administrator can decide which domain to relate to the tenants he is administrating.

Read Domain

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to read domains.

Procedure Description

  1. The Domains column displays all domains in alphabetical order.
  2. For a quick-view of a domain's details hover your mouse pointer over the domain. A tooltip appears, displaying some of the domain's details.
  3. Click the domain's icon to read more details.
  4. For a quick-view of the relations to other units, click the pin icon, which is revealed by moving the mouse pointer over the domain.

Results

The domain's details are displayed like a tooltip.

To see all units that are related to the domain, just click its pin icon, and these units will be highlighted. In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column. Click the pin icon again to clear the highlighting.

Update Domain

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to update domains.

Procedure Description

  1. Click the icon in the left area of the domain's cell in the Domains column.
  2. The domain's details appear in read-only format as they were entered when the domain was created.
  3. Click Edit to change the content of any of the fields.
    Our example shows how to provide a German domain description.
  4. Resume the dialog using the buttons at the bottom of the form (as explained for Create Domain).

Results

The updated domain attributes are now stored on the back end. Other administrative users will need to refresh their view to see your changes.

For information on updating the relation to other elements, please see the appropriate section:

Delete Domain

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to read and delete domains.

Procedure Description

  1. Drag the domain you want to delete.
  2. Drop it on the recycle bin
  3. A dialog box appears with the option of confirming or canceling the deletion.
  4. Click Delete to confirm deleting the domain.

Results

The domain is marked as "deleted" in the back end and will disappear from the default view of the Web UI; it can now only be found in the recycle bin view (). Other administrative users will need to refresh their view to see your changes.

Deleting a domain will also delete all its subordinate units (e.g. applications incl. application roles, permissions) and all relations to other tenants (e.g. permissions exposed toward another tenant).
If a user was automatically granted permissions via the domain that has now been deleted, the new restriction will apply immediately (without notifying the user), at the latest when the user next makes a request requiring such a permission.

The Administrator UI will not enable you to update or delete the initial set of Bosch IoT Permissions entities (i.e. the IM application itself including its group, roles and permissions, the default domain, tenant, offering, tenant relation) as these are elementary parts of the application and are therefore protected for manipulation. It is also not possible to remove or to create new assignments between Bosch IoT Permissions entities. When trying to manipulate such entities or relations, an exception will be thrown by the service.
There are three entities which have some special rules:

  • The default user (Admin) can be updated, deleted and erased.
    However, in case of deleting this user, make sure another user has the same privileges.
  • The default tenant (DEFAULT) can be updated but not deleted.
  • The All Users group cannot be updated, deleted or erased.
    It is not possible to remove users from this group (all users are assigned) but it is possible to assign roles to this group.

Example when trying to delete the IM application.

Restore Domain

Preconditions

You will need to be logged in and have permission to read and update domains.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the domain you want to restore.
  3. Drag and drop it on the "restore" area .
  4. A dialog box appears with the option of confirming or canceling the restore action.
  5. Click Restore to confirm.

Click the following icon  to switch back to the default view.

Results

The domain is restored in the back end and will now appear in the default view. Other administrative users will need to refresh their view to see your changes.

Delete Domain permanently

Preconditions

You will need to be logged in and have permission to read and permanently delete domains.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the domain you want to delete permanently.
  3. Drag and drop it on the "delete permanently" area .
  4. A dialog box appears with the option of confirming or canceling the permanent deletion.
  5. Click Delete permanently to confirm.

Click the following icon  to switch back to the default view.

Results

The domain is permanently deleted from the back end with no option to restore. Other administrative users will need to refresh their view to see your changes.

Create a Domain-Application assignment

Currently, the Administrator UI will not assist you in assigning a domain to an application (or an application to a domain).

The domain where the application should be displayed must be specified while installing the application.

For more details see Developer GuideApplication Instance Resource.

Delete a Domain-Application assignment

Currently, the Administrator UI will not assist you in assigning a domain to an application (or an application to a domain).

The domain where the application should be displayed must be specified while installing the application.

For more details see Developer GuideApplication Instance Resource.

Tenant Management View

The Administrator UI contains nine columns which correspond to one type of entity each. When using the UI with all columns enabled on a monitor with small resolution, there might raise some usability inconveniences, e.g. forcing you to collapse some of the columns to get more space for the other ones.

In order to address this problem the Administrator UI allows to define customized views, which hide some of the columns which are assumed to be not necessary for completing a simple task.

Bosch IoT Permissions offers increased support for multi-tenancy. In addition to the strict data separation for multiple tenants hosted within the same database, our service also allows the definition of relationships between tenants.
This feature enables tenants to share data and permissions with each other in a controlled way. Thus, a "consumer" tenant so empowered by another one can act on behalf of that "provider" tenant, accomplishing contracts similar to agents.

The Tenant Management view addresses:

The IM Tenant Manager role holds all permissions one would need to work in this view.

Role name IM Tenant Manager
Description Manages tenant relations and offerings
Permissions 24
Technical name TenantManager
Permission name Description Technical name
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Modify 'offering type-permission' relations Add or remove relations between offering types and permissions RELATION_PERMISSION_OFFERING_TYPE
Modify 'offering type-role' relations Add or remove relations between offering types and roles RELATION_ROLE_OFFERING_TYPE
Modify 'role-permission' relations

Add or remove relations between roles and permissions

RELATION_ROLE_PERMISSION
Modify 'tenant relation-offering type' relations Add or remove relations between tenant relations and offering types RELATION_TENANT_RELATION_OFFERING_TYPE
Modify 'tenant relation-tenant' relations Add or remove relations between tenant relations and tenants RELATION_TENANT_RELATION_TENANT
Offering types - create Allows to create offering types CREATE_OFFERING_TYPE
Offering types - delete Allows to delete offering types DELETE_OFFERING_TYPE
Offering types - erase Allows to erase offering types ERASE_OFFERING_TYPE
Offering types - query Allows to query offering types READ_OFFERING_TYPE
Offering types - update Allows to update offering types UPDATE_OFFERING_TYPE
Permissions - query Allows to query permissions READ_PERMISSION
Roles - query Allows to query roles READ_ROLE
Tenant relations - create Allows to create tenant relations CREATE_TENANT_RELATION
Tenant relations - delete Allows to delete tenant relations DELETE_TENANT_RELATION
Tenant relations - erase Allows to erase tenant relations ERASE_TENANT_RELATION
Tenant relations - query Allows to query tenant relations READ_TENANT_RELATION
Tenant relations - update Allows to update tenant relations UPDATE_TENANT_RELATION
Tenants - create (incl. admin) Users with this permission are allowed to create additional tenants including the - create of an administrator role and user CREATE_TENANT
Tenants - delete Allows to delete tenants DELETE_TENANT
Tenants - erase Allows to erase tenants ERASE_TENANT
Tenants - query Allows to query tenants READ_TENANT
Tenants - update and restore Users with this permission are allowed to restore deleted tenants (incl. to create an administrator role and user) UPDATE_TENANT

Example:

Tenant Relation Concept

In addition to the strict data separation for multiple tenants hosted within the same database, Bosch IoT Permissions also allows the definition of relationships between tenants.

General structure of a tenant relation

Like all other entities, a tenant relation is owned by a tenant.

This tenant (the providing tenant) can use a tenant relation to offer roles and permissions to other tenants (consuming tenants).

In order to do so, he must assign at least one offering to the tenant relation.

The applicable scope of the assigned offering defines whether the consuming tenant is either:

  • provided with service access (protected by roles and permissions) that he can apply on his own/consumer data (scope is CONSUMER) or
  • provided with provider data access (scope is PROVIDER) including the necessary service access in order to do so.

Note

Scope provider does not include scope consumer, i.e. if a tenant has to manage its own data with a service and the data of another tenant with the same, he has to be provided with the service by the service-owning tenant (scope CONSUMER) and data access by the data-owning tenant (scope PROVIDER).

The following diagram shows the general structure of a tenant relation, including possible assignments to/between the entities offering, role, and permission.

Examples of tenant relations
Tenant allows another tenant to manage users for him (Principal-Agent Relationship)

This example shows the usage of a tenant relation to provide data access to another tenant.

  • This tenant relation would allow Tenant T_Y (i.e. the Agent) to administrate the users of Tenant T_X (i.e. the Principal).
  • The applicable scope for the offering is PROVIDER.

To put it another way: Tenant T_Y has the permissions to create, modify, and delete users in the data store of Tenant T_X.

Tenant extends a software service to another tenant (Service Provider-Consumer Relationship)

This example shows the usage of a tenant relation to provide extended service access to another tenant. The service in this example is IM itself and it shows that Bosch IoT Permissions uses the tenant relationships internally as any external application would do.

  • This tenant relation provides IM permissions from Tenant T_X (i.e. the Service Provider) to Tenant T_Y (i.e. the Service Consumer) to manage further child tenants in addition to the standard offering for user/group/role management.
  • The applicable scope for the offering is CONSUMER.

To put it another way: Tenant T_Y has the permissions to create, modify, and delete child tenants in its own data store.

Offering roles and / or permissions

An offering can contain either roles, permissions or a combination of roles and permissions.

With the help of the following table you should be able to find out what fits best for your scenario:

Offering contains Effect for the consuming tenant When to use
only permissions He is able to assign the permissions to his users via groups or roles (which he needs to create on his own).
  • Your application has no standard / useful roles that can be offered.
only roles He is able to assign the roles to his users, thus enabling them to use the role and the contained permissions.
He is not able to see or modify the contained permissions.
  • You want to be able to change contained permissions transparently.
  • Your application has no permissions (it provides only roles).
roles and permissions

He is able to assign the roles to his users, thus enabling them to use the role and the contained permissions.
He is able to assign the permissions to his users via groups or roles (which he needs to create on his own).

  • This is the most flexible approach but it might not be appropriate when the permissions which are contained in the offered roles are likely to change often.
Propagation of offered roles and permissions

When roles and permissions are offered to a consuming tenant, this tenant can use these on his own data (scope CONSUMER) or on the data of the providing tenant (scope PROVIDER).

But what happens if the consuming tenant has the permissions required to establish tenant relations and creates one which includes the offered roles or permissions, i.e. somehow forwards the permissions granted to him to third parties?

The following table shows the effects of an offering chain:

  • Tenant A (T_A) to Tenant B (T_B)
  • Tenant B (T_B) to Tenant C (T_C)
Scope of the Offering
from T_A -> T_B

Scope of the Offering
from T_B -> T_C

Effective Roles / Permissions available for T_C
PROVIDER CONSUMER / PROVIDER T_B is not allowed to use the roles / permissions on his own data and therefore is also not able to propagate them to T_C.
CONSUMER CONSUMER T_B is allowed to use the roles / permissions on his own data but he is not allowed to propagate them to T_C to use the roles/permissions on T_C's data.
CONSUMER PROVIDER T_B is allowed to use the roles / permissions on his own data.
T_B is also able to propagate the roles / permissions. As a consequence, T_C is enabled to use them on the data of T_B.

This means that a consuming tenant T_B, which has the permissions required to establish tenant relations, is able to propagate roles and permissions to another tenant T_C. But the latter is only able to use those roles and permissions if they were offered to T_B with scope CONSUMER and were propagated to T_C with scope PROVIDER.
All other combinations are not valid, and T_C will therefore not be able to see or use them.

For example:

  • The application IM is owned by T_A. 
  • T_A allows T_B to create, update, and delete its own users (scope CONSUMER) by an according relationship.
  • T_B can now give T_C the permission to read its own users (scope PROVIDER), i.e. T_C can read users of T_B.

When a providing tenant (T_A) removes a role / permission from an offering, all direct (T_B) and indirect (T_C) consuming tenants are no longer able to see or use it.

The same applies when the tenant relation associated with the offering is or becomes invalid (e.g. end date is reached) or is deleted / erased.

Offering Management

Offering
An offering is a set of roles and permissions that can be offered by one tenant to others. Thus, an application registered at our Bosch IoT Permissions service can spread its roles and permissions outside the boundaries of the owning tenant. Further, the offering can combine roles and permissions that come with IM, or an application instance registered at our Bosch IoT Permissions service, or self-generated roles (using the Web user interface).

Within the Web user interface, the following icon is used for representing an offering .

When managing an offering, keep the following concepts and restrictions in mind:

  • Each offering has exactly one owner (i.e. the providing tenant, who created the offering). The offering's name must be unique within this tenant.
  • The offering's permission is a union of all permissions granted:
    • directly
    • via a role.
  • The offering has exactly one applicable scope ( ApplicableScope), i.e. the definition of the context in which an offered permission or role is applicable.
    • Applicable scope PROVIDER: The permissions will affect the data of the providing tenant.
      Using this scope, the providing tenant can allow other tenants to act on his behalf.

    • Applicable scope CONSUMER: The permissions will affect the data of the consuming tenant.
      Using this scope, the providing tenant can allow other tenants to use his applications. The data resulting from using the application will be in the ownership of the consuming tenant.

  • An offering can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries, etc. (except for the "recycle bin" view).
  • Deleting an offering will delete all existing assignments to the permissions, roles, and the tenant relations.

In order to become active, a so called Tenant Relation must be created, to which the offering can then be added.

The Bosch IoT Permissions service itself already provides a default offering. Thus, a basic set of IM roles and permissions is automatically offered to all tenants who book our service. This offering includes almost all the IM permissions, which enables the tenant with full identity management features.


Examples

Create an Offering

Preconditions

You will need to be logged in and have permission to create tenant relations.
E.g. the administrator of the DEFAULT tenant should already have assigned all permissions defined by the IM application.

Procedure Description

  1. Click the "add offering" icon .
  2. The Offerings column will display a form for completing all the information required to create an offering.
  3. You must complete at least all required fields in the dialog box (marked * ).

    Note:
    The Technical name must NOT contain any blank spaces.

  4. Set the Applicable scope. For further information, hover your mouse pointer over Applicable scope to reveal the tooltip:

    1. Provider:
      The permissions will affect the data of the providing tenant. Using this scope, the providing tenant can allow other tenants to act on his behalf.

    2. Consumer:
      The permissions will affect the data of the consuming tenant. Using this scope, the providing tenant can allow other tenants to use his applications. The data resulting from using the application will be in the ownership of the consuming tenant.

  5. The option to assign the offering automatically to all tenants is disabled by default (No). However, when creating the offering programmatically and registering it in line with the application itself, the value can be set to Yes.

  6. Confirm by clicking one of the buttons at the bottom of the dialog box:

    1. Save - will display a preview of the entries edited so far.
      From there you can continue with

      1. Edit - to amend your entries

      2. Close - to store the new offering.

    2. Save & Close - will store your entries and display all offerings in the Offerings column.
    3. Cancel - will ignore the entries and resume the creation dialog, displaying all offerings in the Offerings column.

Results

The new offering is now available and will be displayed in alphabetical order in the Offerings column.

Self-generated roles, application roles, and permissions can now be assigned to the newly-created offering.

Read an Offering

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to read tenant relations.

Procedure Description

  1. The Offerings column displays all offerings in alphabetical order.
  2. For a quick-view of an offering's details hover your mouse pointer over an offering. A tooltip appears displaying some offering's details.
  3. Click the offering's icon to read more details.
  4. For a quick-view of the relations to other units click the pin icon, which is revealed by moving the mouse pointer over the offering cell.

    Click the pin icon again to clear the highlighting.
  5. Alternatively:
    1. Use the search field at the top of the Offerings column to quickly find an offering.
    2. If you don't know the exact spelling of an offering's name, click the pin icon of a role or permission that the offering groups, and the list of that role's offerings will be re-ordered automatically at the top of the Offerings column.

Results

The offering's details are displayed like a tooltip.

Clicking the pin icon, which is revealed by moving the mouse pointer over the offering cell, will highlight all roles and permissions assigned to the offering. In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.

Update an Offering

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to update offerings.

Procedure Description

  1. Click the icon in the left area of the offering's cell in the Offerings column.
  2. The offering's details appear in read-only format as they were entered when the offering was created.
  3. Click Edit to change the content of any of the fields.
    Our example shows how to change the applicable scope and how to provide a German offering description.
  4. Resume the dialog by using the buttons at the bottom of the form (as explained for Create an Offering).

Results

The updated offering attributes are now stored on the back end. Other administrative users will need to refresh their view to see your changes.

Changing the Applicable scope of an offering affects automatically and without further notice ALL tenants connected via tenant relation.

Delete an Offering

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to read and delete tenant relations.

Procedure Description

  1. Drag the offering you want to delete.
  2. Drop it on the recycle bin
  3. A dialog box appears with the option of confirming or canceling the deletion.
  4. Click Delete to confirm deleting the offering.

Results

The offering is marked as "deleted" in the back end and will disappear from the default view of the Web UI; it can now only be found in the recycle bin view (). Other administrative users will need to refresh their view to see your changes.

Deleting an offering will not automatically delete the roles and permissions grouped within that offering, but it will automatically delete the potentially existing relations with the roles/permissions and the tenants assigned to the offering.
If a user was automatically granted permissions via the offering that has now been deleted, the new restriction will apply immediately (without notifying the user), at the latest when the user next makes a request requiring such a permission.

The Administrator UI will not enable you to update or delete the initial set of Bosch IoT Permissions entities (i.e. the IM application itself including its group, roles and permissions, the default domain, tenant, offering, tenant relation) as these are elementary parts of the application and are therefore protected for manipulation. It is also not possible to remove or to create new assignments between Bosch IoT Permissions entities. When trying to manipulate such entities or relations, an exception will be thrown by the service.
There are three entities which have some special rules:

  • The default user (Admin) can be updated, deleted and erased.
    However, in case of deleting this user, make sure another user has the same privileges.
  • The default tenant (DEFAULT) can be updated but not deleted.
  • The All Users group cannot be updated, deleted or erased.
    It is not possible to remove users from this group (all users are assigned) but it is possible to assign roles to this group.

Example when trying to delete the IM application.

Restore an Offering

Preconditions

You will need to be logged in and have permission to read and update offerings.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the offering you want to restore.
  3. Drag and drop it on the "restore" area .
  4. A dialog box appears with the option of confirming or canceling the restore action.
  5. Click Restore to confirm.

Click the following icon  to switch back to the default view.

Results

The offering is restored in the back end and will now appear in the default view. Other administrative users will need to refresh their view to see your changes.

Delete an Offering permanently

Preconditions

You will need to be logged in and have permission to read and permanently delete offerings.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the offering you want to delete permanently.
  3. Drag and drop it on the "delete permanently" area .
  4. A dialog box appears with the option of confirming or canceling the permanent deletion.
  5. Click Delete permanently to confirm.

Click the following icon  to switch back to the default view.

Results

The offering is permanently deleted from the back end with no option to restore. Other administrative users will need to refresh their view to see your changes.

Create an Offering-Role assignment

Preconditions

You will need to be logged in and have permission to create offering-role relations.

The offering and role you want to relate must both pre-exist (otherwise see Create an Offering and Create Role).

Procedure Description

In our example we need to assign the "User Admin" role to the "User Management" offering.

  1. Select the role and drop it on the offering with which it should be related.
  2. The assignment is not automatically sent to the back end because you might want to create various other relations first and only then synchronize with the back end, all at once.
    To resume the assignment, use the appropriate link provided in the upper part of the application, or go to your list of outstanding actions and decide whether to proceed or cancel.
  3. To complete the assignment click Save changes.

Results

The new offering-role relation is now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin one of the related units:

  • Click the pin icon of the "User Admin" role. The newly-assigned offering is highlighted.
  • Click the pin icon of the "User Management" offering. The newly-assigned role is highlighted.
  • In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.
Delete an Offering-Role assignment

Preconditions

You will need to be logged in and have permission to delete offering-role relations.

The offering-role relation you want to delete must pre-exist (otherwise see Create an Offering-Role assignment)

Procedure Description

The steps to delete the assignment between two elements are pretty much the same for all types of element.

Just drag one of the related elements and drop it on the "remove assignment" area . Then confirm to save the change.

Results

The removal of the offering-role relation is now stored in the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin the offering and you will see that the role is no longer related to the offering.

Create an Offering-Permission assignment

Preconditions

You will need to be logged in and have permission to create offering-permission relations.

The offering and the permission(s) you want to connect must both pre-exist.

Procedure Description

In our example the self-generated "User Management" offering is given all permissions for managing users (revealed by the IM application itself). We are assuming there is no such role as "User Admin" that could already group together these permissions.

  1. Use "user" as the search criterion in the Permissions column.
  2. Select all results and drop them on the offering to which they should be related.
  3. The assignment is not automatically sent to the back end  because you might want to create various other relations first and only then synchronize with the back end, all at once.
    To resume the assignment, use the appropriate link provided in the upper part of the application, or go to your list of outstanding actions and decide whether to proceed or cancel.
  4. To complete the assignment click Save changes.

Results

The new offering-permission relations are now stored on the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin one of the related units:

  • Click the pin icon of the "User - create" permission. All offerings containing this permission are highlighted.
  • Click the pin icon of the "User Management" offering. All related permissions (directly or via a role) are highlighted.
  • In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.

Delete an Offering-Permission assignment

Preconditions

You will need to be logged in and have permission to delete offering-permission relations.

The offering-permission relation you want to delete must pre-exist (otherwise see Create an Offering-Permission assignment)

Procedure Description

The steps to delete the assignment between two elements are pretty much the same for all types of element.

Just drag one of the related elements and drop it on the "remove assignment" area . Then confirm to save the change.

Results

The removal of the offering-permission relation is now stored in the back end. Other administrative users for the same tenant will need to use the refresh button to see your changes.

To check your work, simply pin the offering and you will see that the permission is no longer related to the offering.

Create an Offering-Tenant Relation assignment

Preconditions

You will need to be logged in and have permission to create relations between offerings and tenant relation elements.

The offering and the tenant relation element you want to relate must both pre-exist (otherwise see Create an Offering and Create a Tenant Relation element).

Procedure Description

In our example we need to empower a tenant with the permissions grouped as the "User Management" offering.

  1. Drag and drop the offering on the tenant relation element to which it should be related.
     

  2. The assignment is not automatically sent to the back end because you might want to create various other relations first and only then synchronize with the back end, all at once.
    To resume the assignment, use the appropriate link provided in the upper part of the application, or go to your list of outstanding actions and decide whether to proceed or cancel.

  3. To complete the assignment click Save changes.

Result

The new relation between the offering and the tenant relation element is now stored on the back end. Other administrative users will need to use the refresh button to see your changes.

As the scope defined in our example is applicable to the "Data of consuming tenant" (see respective radio button in Create an Offering), all tenants that are assigned to that tenant relation will receive all permissions needed for their own user management.
To delegate your own users' management to another tenant that acts on behalf of your tenant, you will need to

To check your work, simply pin one of the related elements:

Delete an Offering-Tenant Relation assignment

Preconditions

You will need to be logged in and have permission to delete relations between offerings and tenant relation elements.

Procedure Description

The steps to delete the assignment between two elements are pretty much the same for all types of element.

Just drag one of the related elements and drop it on the "remove assignment" area . Then confirm to save the change.

Results

The removal of the assignment between the offering and the tenant relation element is stored in the back end. Other administrative users will need to refresh their view to see your changes.

To check your work, simply pin the tenant relation element and you will see that the offering is no longer highlighted.

Deleting an assignment between an offering and a tenant relation also deletes all implicit assignments of the roles and permissions grouped within the offering assignments to other tenants.
If a user was automatically granted permissions via the relation that has now been deleted, the new restriction will apply immediately (without notifying the user), at the latest when the user next makes a request requiring such a permission.

Tenant Relation Management

Bosch IoT Permissions allows the definition of relationships between tenants.

Within the Web user interface, the following icon is used for a tenant relation .

Table of contents

Further examples to enable workflows beyond a tenant's boundaries

Create a Tenant Relation element

Preconditions

You will need to be logged in and have permission to create tenant relations.

Procedure Description

  1. Click the "add tenant relation" icon .
  2. The Tenant Relations column will display a form for completing all the information required to create a tenant relation element.
  3. You must complete at least all required fields in the dialog box (marked * )


    Note: Although the date picker displays end dates later than 12/31/2037 11:59 PM for selection, no value that exceeds this limitation will be accepted. That is currently the maximum accepted value for TIMESTAMP columns of a MySQL database.
  4. Confirm by clicking one of the buttons at the bottom of the dialog box:
    1. Save - will display a preview of the entries edited so far.
      From there you can continue with
      1. Edit - to amend your entries 
      2. Close - to store the new tenant relation element.
    2. Save & Close - will store your entries and display all elements in the Tenant Relations column.
    3. Cancel - will ignore the entries and resume the creation dialog, displaying all elements in the Tenant Relations column.

Results

The new tenant relation element is now available and will be displayed in alphabetical order in the Tenant Relations column.

Read a Tenant Relation element

Preconditions

You will need to be logged in and have permission to read tenant relations.

Procedure Description

  1. The Tenant Relations column displays all elements in alphabetical order.
  2. For a quick-view of a tenant relation's details, hover your mouse pointer over the element. A tooltip appears, displaying some of the tenant relation's details.
  3. Click the tenant relation's icon to read more details.
  4. For a quick-view of the references to other units, click the pin icon, which is revealed by moving the mouse pointer over the tenant relation's cell.
    Click the pin icon again to clear the highlighting.
  5. Alternatively: Use the search field at the top of the Tenant Relations column to quickly find a tenant relation element.

Results

The tenant relation details are displayed like a tooltip.

Clicking the pin icon, which is revealed by moving the mouse pointer over the tenant relation cell, will highlight all offerings as well as all tenants assigned to the tenant relation in question. In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column. See examples in section Create a Tenant Relation-Tenant assignment.

Update a Tenant Relation element

Preconditions

You will need to be logged in and have reading and writing permission for tenant relations.

Procedure Description

  1. Click the icon in the left area of the tenant relation's cell in the Tenant Relations column.
  2. The tenant relation's details appear in read-only format as they were entered when the tenant relation was created.
  3. Click Edit to change the content of any of the fields.
    Our example shows how to provide a German description.

Results

The updated tenant relation attributes are now stored on the back end. Other administrative users will need to refresh their view to see your changes.

For information on updating the relation to other elements, please see the appropriate section:

Delete a Tenant Relation element

Preconditions

You will need to be logged in and have permission to read and delete tenant relations.

Procedure Description

  1. Drag the tenant relation element you want to delete.
  2. Drop it on the recycle bin
  3. A dialog box appears with the option of confirming or canceling the deletion.
  4. Click Delete to confirm deleting of the tenant relation.

Note: Deleting a tenant relation that was assigned to other tenants - and, thus, provided other tenants' users with roles and permissions (grouped as offerings) - will not delete the offering elements too, but it will delete the assignments between the users and permissions.

Results

The tenant relation is marked as "deleted" in the back end and will disappear from the default view of the Web UI; it can now only be found in the recycle bin view (). Other administrative users will need to refresh their view to see your changes.

Deleting a tenant relation also deletes all assignments to offerings and other tenants.
If a user was automatically granted permissions via the tenant relation that has now been deleted, the new restriction will apply immediately (without notifying the user), at the latest when the user next makes a request requiring such a permission.

The Administrator UI will not enable you to update or delete the initial set of Bosch IoT Permissions entities (i.e. the IM application itself including its group, roles and permissions, the default domain, tenant, offering, tenant relation) as these are elementary parts of the application and are therefore protected for manipulation. It is also not possible to remove or to create new assignments between Bosch IoT Permissions entities. When trying to manipulate such entities or relations, an exception will be thrown by the service.
There are three entities which have some special rules:

  • The default user (Admin) can be updated, deleted and erased.
    However, in case of deleting this user, make sure another user has the same privileges.
  • The default tenant (DEFAULT) can be updated but not deleted.
  • The All Users group cannot be updated, deleted or erased.
    It is not possible to remove users from this group (all users are assigned) but it is possible to assign roles to this group.

Example when trying to delete the IM application.

Restore a Tenant Relation element

Preconditions

You will need to be logged in and have permission to read and update tenant relations.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the tenant relation element you want to restore.
  3. Drag and drop it on the "restore" area .
  4. A dialog box appears with the option of confirming or canceling the restore action.
  5. Click Restore to confirm.

Note: Restoring a tenant relation will just make it visible again in the default view, preserving the start and end date as it was at the time of deleting the element, even if the validity period has expired.

Click the following icon to switch back to the default view.

Results

The tenant relation is restored in the back end and will now appear in the default view. Other administrative users will need to refresh their view to see your changes.

Delete a Tenant Relation element permanently

Preconditions

You will need to be logged in and have permission to read and permanently delete tenant relations.

Procedure Description

  1. Open the recycle bin view () .
  2. Click the tenant relation element you want to delete permanently.
  3. Drag and drop it on the "delete permanently" area .
  4. A dialog box appears with the option of confirming or canceling the permanent deletion.
  5. Click Delete permanently to confirm.

Click the following icon to switch back to the default view.

Results

The tenant relation is permanently deleted from the back end with no option to restore. Other administrative users will need to refresh their view to see your changes.

Create a Tenant Relation-Tenant assignment

Preconditions

You will need to be logged in and have permission to create relations between tenant relation elements and consuming tenants.

The tenant relation element and the other tenant you want to relate must both pre-exist (otherwise see Create a Tenant Relation element and Create Tenant).

Procedure Description

  1. Drag the tenant relation element that should be offered and drop it on the other tenant.
    In our example, the "Agency" tenant is empowered with the offerings grouped within the tenant relation element "Update my users".
  2. The assignment is not automatically sent to the back end because you might want to create various other relations first and only then synchronize with the back end, all at once.
  3. To resume the assignment, use the appropriate link provided in the upper part of the application, or go to your list of outstanding actions and decide whether to proceed or cancel.
  4. To complete the assignment click Save changes.

Please Note:

Results

The new relation between the tenant relation element and the other tenant is now stored on the back end. Other administrative users will need to refresh their view to see your changes.

To check your work, simply pin one of the related units:

  • Click the pin icon of the newly-assigned tenant relation element. The related tenants and offerings will be highlighted.

    Note: The tenant providing the tenant relation displays additionally the icon , identifying him as provider. However the "applicable scope" (i.e. on whose tenants data the permissions will apply) is defined within the offering (see Update an Offering).
  • Click the pin icon of the newly-assigned tenant. The tenant relation element now also displays the chain icon and is sorted at the top of the Tenant Relations column.

    Note: All tenants automatically receive the "IM Default Offering" (provided by the IM application itself) via "IM Tenant Creation Relation".
  • If the offering included roles and permissions, these are highlighted as well, as the newly-created relation grants them automatically to all members.

  • In addition, the related elements will move to the upper part of the corresponding column and the total number of elements assigned to the pinned one will be displayed at the foot of the column.

Further examples to enable workflows beyond a tenant's boundaries

Delete a Tenant Relation-Tenant assignment

Preconditions

You will need to be logged in and have permission to delete relations between tenant relation elements and other tenants.

Procedure Description

The steps to delete the assignment between two elements are pretty much the same for all types of element.

Just drag one of the related elements and drop it on the "remove assignment" area . Then confirm to save the change.

Results

The removal of the assignment between the tenant relation element and the other tenant is now stored in the back end. Other administrative users will need to refresh their view to see your changes.

To check your work, simply pin the tenant, and you will see that the tenant relation element is no longer highlighted.

Deleting an assignment between a tenant relation element and another tenant also deletes all implicit assignments of the roles and permissions (grouped within the offering) to other tenants.
If a user was automatically granted permissions via the relation that has now been deleted, the new restriction will apply immediately (without notifying the user), at latest when the user next makes a request requiring such a permission.

Create a Tenant Relation-Offering assignment

Further examples to enable workflows beyond a tenant's boundaries

Delete a Tenant Relation-Offering assignment

A description of this procedure is provided in the section Delete an Offering-Tenant Relation assignment.

Tenant Management

Tenant
A tenant is a legal organizational unit that is generally the representative of a company.

Within the Web user interface, the following icon is used for a tenant .

There is a default tenant, i.e. the tenant where the IM itself is installed.
(The name of this tenant is set as "DEFAULT", however it can be changed before the first installation of the IM.)

When managing a tenant, keep the following concepts and restrictions in mind:

  • A tenant's name must be unique within Bosch IoT Permissions and may consist only of upper-case letters, underscores, and digits.
  • A tenant is the "owner" of all entities created using that tenant (this is also true for any tenants that are created).
  • A tenant can be marked as "deleted", in which case the entity will not appear on the user interface, neither will it be considered in lists, queries etc. (except for the "recycle bin" view).
  • Deleting a tenant includes deleting its whole organizational structure (incl. groups, users, roles, and all other entities owned by this tenant), as well as all tenants created by this tenant, and all existing relations to other tenants, domains, etc.
  • Moreover, a deleted tenant can only be restored by a user who has update-tenant permission in the context of the tenant that created this tenant (owning tenant).
  • A user who has read-, update-, delete-, or erase-tenant permission for a tenant can perform these operations also on any tenants created by this tenant.
  • Depending on the permissions assigned, a tenant can be allowed to manipulate other tenant's data.

Examples

Create Tenant

Preconditions

You will need to be logged in and have permission to create tenants.
The administrator of the DEFAULT tenant should already have assigned all permissions defined by the IM application.

Procedure Description

  1. Click the "add tenant" icon .
  2. The Tenants column will display a form for completing all the information required to create a tenant.
  3. You must complete at least all required fields in the dialog box (marked * ).

    1. The Technical name must contain only upper-case alphabetic character, underscore and digits. It must be at least 2, and maximum 24 characters long.

    2. The requirements regarding the characters to be used or minimum length for the password etc. can be configured by the administrator and thus will differ per service instance.
      However the user interface will support you by providing the password rules defined for your instance.
      Please note that the administrator of the new tenant will be a privileged user, thus the password rules for privileged users will apply.
  4. Confirm by clicking one of the buttons at the bottom of the dialog box.
    1. Save - will display a preview of the entries edited so far.
      From there you can continue with
      1. Edit - to amend your entries 
      2. Close - to store the new tenant.
    2. Save & Close - will store your entries and display all tenants in the Tenants column.
    3. Cancel - will ignore the entries and resume the creation dialog, displaying all tenants in the Tenants column.
  5. The newly created administrator is created automatically and can now log in.
  6. Check your work
    1. Log out the default admin user.
    2. Log in with the newly created admin user's credentials
    3. The admin user should be displayed in the Users column.
    4. Click the admin user's pin icon to check that he was automatically assigned the role of IM Tenant Administrator.
       

There is no automatic announcement to other systems. Thus, you should inform the person who will act as the new tenant's administrator about the rights and duties assumed in your organization.

Results

The new tenant is now available and will be displayed in alphabetical order in the Tenants column.

Read Tenant

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to read tenants.

Procedure Description

  1. The Tenants column displays all tenants in alphabetical order.
  2. For a quick-view of a tenant's details, hover your mouse pointer over the tenant. A tooltip appears, displaying some of the tenant's details.
  3. Click the tenant's icon to read more details.
  4. Click Close to return to the list of all tenants.

Alternatively: Use the search field at the top of the Tenants column to quickly find a tenant.

Results

The tenant details are displayed like a tooltip.

To see all units that are in the ownership of a particular tenant, log in e.g. with the appropriate tenant's administrator credentials.

Update Tenant

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to update tenants.

Procedure Description

  1. Click the icon in the left area of the tenant's cell in the Tenants column.
  2. The tenant's details appear in read-only format as they were entered when the tenant was created (except the fields for creating the admin user).
  3. Click Edit to change the content of any of the fields.
    Our example shows how to provide a German tenant description.
  4. Resume the dialog using the buttons at the bottom of the form (as explained for Create Tenant).

Results

The updated tenant attributes are now stored on the back end. Other administrative users will need to refresh their view to see your changes.

Delete Tenant

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to read and delete tenants.

Procedure Description

  1. Drag the tenant you want to delete.
  2. Drop him on the recycle bin
  3. A dialog box appears with the option of confirming or canceling the deletion.
  4. Click Delete to confirm deleting the tenant.

Results

The tenant is marked as "deleted" in the back end and will disappear from the default view of the Web UI; it can now only be found in the recycle bin view (). Other administrative users will need to refresh their view to see your changes.

Deleting a tenant will delete all that tenant's elements (e.g. users, groups, roles etc., as shown in the notification) and their assignments to other entities, as well as any tenants created by this tenant.

The Administrator UI will not enable you to update or delete the initial set of Bosch IoT Permissions entities (i.e. the IM application itself including its group, roles and permissions, the default domain, tenant, offering, tenant relation) as these are elementary parts of the application and are therefore protected for manipulation. It is also not possible to remove or to create new assignments between Bosch IoT Permissions entities. When trying to manipulate such entities or relations, an exception will be thrown by the service.
There are three entities which have some special rules:

  • The default user (Admin) can be updated, deleted and erased.
    However, in case of deleting this user, make sure another user has the same privileges.
  • The default tenant (DEFAULT) can be updated but not deleted.
  • The All Users group cannot be updated, deleted or erased.
    It is not possible to remove users from this group (all users are assigned) but it is possible to assign roles to this group.

Example when trying to delete the IM application.

Restore Tenant

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to read and update tenants.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the tenant you want to restore.
  3. Drag and drop him on the "restore" area .
    .
  4. As already discussed in Create Tenant, you will always need an administrative user.
    Thus a dialog box will appear displaying the fields for creating a new user.
    1. The requirements regarding the characters to be used or minimum length for the password etc. can be configured by the administrator and thus will differ per service instance.
      However, the user interface will support you by providing the password rules defined for your instance.
      Please note that the Admin of the restored tenant will be a privileged user, thus the password rules for privileged users will apply.

  5. Click Restore to confirm.
  6. Click the following icon to switch back to the default view.
  7. Log in as the restored tenant's administrative user to check whether other administrative users exist. If so, the new one generated while restoring can be deleted or permanently deleted.

Results

The tenant is restored in the back end and will now appear in the default view. Other administrative users will need to refresh their view to see your changes.

Delete Tenant permanently

Preconditions

You will need to be logged in (e.g. as the DEFAULT Admin) and have permission to read and permanently delete tenants.

Procedure Description

  1. Open the recycle bin view ().
  2. Click the tenant you want to delete permanently.
  3. Drag and drop him on the "delete permanently" area.
  4. A dialog box appears with the option of confirming or canceling the permanent deletion.
  5. Click Delete permanently to confirm.

Click the following icon  to switch back to the default view.

Results

The tenant is permanently deleted from the back end with no option to restore. Other administrative users will need to refresh their view to see your changes.

Share your applications with other tenants

Preconditions

  • As the user interface does not support the registration of new applications into a service instance by simple users, let us assume that the "New Application" has already been installed.
  • Your task in this example is to enable other tenants to use the "New Application" for themselves.

Procedure description

  • Create an offering "Use Application" with applicable scope consumer.

  • Create an assignment between the "New Application" role and the offering.
  • Create a tenant relation "May use New Application".
  • Create an assignment between the "Use Application" offering and the tenant relation.
  • Assign the tenant relation to other tenants.

Results

The consuming tenants now have permission to use the "New Application", including all permissions.

The administrative user of the "Agency" tenant can now empower his users by assigning them the "New Application Role".

The simple permissions defined by the new application are not visible, as they were grouped within the role. 

The output data from using the "New Application" will be stored on the consumer's own data base, not on the provider's data base.

Further examples

Default Roles and Permissions

Bosch IoT Permissions provides very fine-grained permission to read, create, delete, permanently delete, etc. every type of Bosch IoT Permissions element. The user interface enables the administrative users to assign them to custom roles and those to users. At the time of writing, IM offers more than 60 permissions, and groups them into 6 default roles.

However, some of the permissions are only necessary for developers (e.g. "CREATE_INSTANCE_ROLE"), thus, you will find no corresponding actions using the graphical user interface.

Role name IM Application Installer
Description Install complete application instances
Permissions 4
Technical name ApplicationInstaller
Permission name Description Technical name
Application instances - install Users with this permission are allowed to install applications (incl. Roles and Permissions) INSTALL_APPLICATION
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Tenants - query Allows to query tenants READ_TENANT
Role name IM Role Manager
Description Manages roles and permissions
Permissions 10
Technical name RoleManager
Permission name Description Technical name
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Modify 'role-permission' relations Add or remove relations between roles and permissions RELATION_ROLE_PERMISSION
Permissions - query Allows to query permissions READ_PERMISSION
Roles - create Allows to create roles CREATE_ROLE
Roles - delete Allows to delete roles DELETE_ROLE
Roles - erase Allows to erase roles ERASE_ROLE
Roles - query Allows to query roles READ_ROLE
Roles - update Allows to update roles UPDATE_ROLE
Tenants - query Allows to query tenants READ_TENANT
Role name IM Service Administrator
Description Service Administrator with almost all permissions
Permissions Find a list of all IM permissions at "Permissions provided by IM".
Technical name ServiceAdministrator
Role name IM Tenant Administrator
Description

Administrator for a specific tenant

Permissions 27
Technical name TenantAdministrator
Permission name Description Technical name
API Key Administration Allows to manage own API Keys API_KEY_ADMINISTRATION
Activation code administration for the current tenant Allows to generate and read activation codes for
all users of the current tenant
ACTIVATION_CODE_ADMINISTRATION
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Email templates - create and modify Allows to create new and modify existing email
templates
EMAIL_TEMPLATE_ADMINISTRATION
Groups - create Allows to create groups CREATE_GROUP
Groups - delete Allows to delete groups DELETE_GROUP
Groups - erase Groups - erase ERASE_GROUP
Groups - query Allows to query groups READ_GROUP
Groups - update Allows to update groups UPDATE_GROUP
Modify 'group-role' relations Add or remove relations between groups and roles RELATION_GROUP_ROLE
Modify 'role-permission' relations Add or remove relations between roles and permissions RELATION_ROLE_PERMISSION
Modify 'user-group' relations Add or remove relations between users and groups RELATION_USER_GROUP
Modify 'user-role' relations Add or remove relations between users and roles RELATION_USER_ROLE
Permissions - query Allows to query permissions READ_PERMISSION
Roles - create Allows to create roles CREATE_ROLE
Roles - delete Allows to delete roles DELETE_ROLE
Roles - erase Allows to erase roles ERASE_ROLE
Roles - query Allows to query roles READ_ROLE
Roles - update Allows to update roles UPDATE_ROLE
Tenants - query Allows to query tenants READ_TENANT
Tenant-specific security settings Allows to create and modify tenant-specific security
settings
TENANT_SECURITY_ADMINISTRATION
Users - create Allows to create users CREATE_USER
Users - delete Allows to delete users DELETE_USER
Users - erase Allows to erase users ERASE_USER
Users - query Allows to query users READ_USER
Users - update Allows to update users UPDATE_USER
Role name IM Tenant Manager
Description Manages tenant relations and offerings
Permissions 24
Technical name TenantManager
Permission name Description Technical name
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Modify 'offering type-permission' relations Add or remove relations between offering types and permissions RELATION_PERMISSION_OFFERING_TYPE
Modify 'offering type-role' relations Add or remove relations between offering types and roles RELATION_ROLE_OFFERING_TYPE
Modify 'role-permission' relations

Add or remove relations between roles and permissions

RELATION_ROLE_PERMISSION
Modify 'tenant relation-offering type' relations Add or remove relations between tenant relations and offering types RELATION_TENANT_RELATION_OFFERING_TYPE
Modify 'tenant relation-tenant' relations Add or remove relations between tenant relations and tenants RELATION_TENANT_RELATION_TENANT
Offering types - create Allows to create offering types CREATE_OFFERING_TYPE
Offering types - delete Allows to delete offering types DELETE_OFFERING_TYPE
Offering types - erase Allows to erase offering types ERASE_OFFERING_TYPE
Offering types - query Allows to query offering types READ_OFFERING_TYPE
Offering types - update Allows to update offering types UPDATE_OFFERING_TYPE
Permissions - query Allows to query permissions READ_PERMISSION
Roles - query Allows to query roles READ_ROLE
Tenant relations - create Allows to create tenant relations CREATE_TENANT_RELATION
Tenant relations - delete Allows to delete tenant relations DELETE_TENANT_RELATION
Tenant relations - erase Allows to erase tenant relations ERASE_TENANT_RELATION
Tenant relations - query Allows to query tenant relations READ_TENANT_RELATION
Tenant relations - update Allows to update tenant relations UPDATE_TENANT_RELATION
Tenants - create (incl. admin) Users with this permission are allowed to create additional tenants including the - create of an administrator role and user CREATE_TENANT
Tenants - delete Allows to delete tenants DELETE_TENANT
Tenants - erase Allows to erase tenants ERASE_TENANT
Tenants - query Allows to query tenants READ_TENANT
Tenants - update and restore Users with this permission are allowed to restore deleted tenants (incl. to create an administrator role and user) UPDATE_TENANT
Role name IM User Manager
Description Manages users, groups and roles
Permissions 16
Technical name UserManager
Permission name Description Technical name
Application instances - query Allows to query instances READ_INSTANCE
Groups - create Allows to create groups CREATE_GROUP
Groups - delete Allows to delete groups DELETE_GROUP
Groups - erase Groups - erase ERASE_GROUP
Groups - query Allows to query groups READ_GROUP
Groups - update Allows to update groups UPDATE_GROUP
Modify 'group-role' relations Add or remove relations between groups and roles RELATION_GROUP_ROLE
Modify 'user-group' relations Add or remove relations between users and groups RELATION_USER_GROUP
Modify 'user-role' relations Add or remove relations between users and roles RELATION_USER_ROLE
Roles - query Allows to query roles READ_ROLE
Tenants - query Allows to query tenants READ_TENANT
Users - create Allows to create users CREATE_USER
Users - delete Allows to delete users DELETE_USER
Users - erase Allows to erase users ERASE_USER
Users - query Allows to query users READ_USER
Users - update Allows to update users UPDATE_USER
English German
API Key Administration API Key Verwaltung
Activation code administration for the current tenant Aktivierungscodes für den aktuellen Mandanten verwalten
Application instances - install Applikationen anlegen (inkl. Rollen u. Berechtigungen)
Application instance roles - create Applikations-Rollen anlegen
Application instance roles - delete Applikations-Rollen löschen
Application instance roles - erase Applikations-Rollen unwiderruflich löschen
Application instance roles - update Applikations-Rollen bearbeiten
Application instances - create Applikationen anlegen
Application instances - delete Applikationen löschen
Application instances - erase Applikationen unwiderruflich löschen
Application instances - install Applikation anlegen (inkl. Rollen u. Berechtigungen)
Application instances - query Applikationen abfragen
Application instances  - update Applikationen bearbeiten
Client access token administration for the current tenant Client Access Token Verwaltung
Domains - create Domäne anlegen
Domains - delete Domänen löschen
Domains - erase Domänen unwiderruflich löschen
Domains - query Domänen abfragen
Domains - update Domänen bearbeiten
Email templates - create and modify E-Mail-Vorlagen anlegen und bearbeiten
Groups - create Gruppen anlegen
Groups - erase Gruppen unwiderruflich löschen
Groups - delete Gruppen löschen
Groups - query Gruppen abfragen
Groups - update Gruppen bearbeiten
Modify 'group-role' relations Verknüpfungen zw. Gruppen und Rollen
Modify 'offering type-permission' relations Verknüpfungen zw. Angeboten und Berechtigungen
Modify 'offering type-role' relations Verknüpfungen zw. Angeboten und Rollen
Modify 'role-permission' relations Verknüpfungen zw. Berechtigungen und Rollen
Modify 'tenant relation-offering type' relations Verknüpfungen zw. Gruppen und Rollen
Modify 'tenant relation-tenant' relations Verknüpfungen zw. Mandantenbeziehungen und Angeboten
Modify 'user-group' relations Verknüpfungen zw. Benutzern und Gruppen
Modify 'user-role' relations Verknüpfungen zw. Benutzern und Rollen
Offering types - create Angebote anlegen
Offering types - delete Angebote löschen
Offering types - erase Angebote unwiderruflich löschen
Offering types - query Angebote abfragen
Offering types - update Angebote bearbeiten
Own user - delete Eigenen Benutzer löschen
Permissions - create Berechtigungen anlegen
Permissions - delete Berechtigungen löschen
Permissions - erase Berechtigungen unwiderruflich löschen
Permissions - query Berechtigungen abfragen
Permissions - update Berechtigungen bearbeiten
Roles - create Rollen anlegen
Roles - delete Rollen löschen
Roles - erase Rollen unwiderruflich löschen
Roles - query Rollen abfragen
Roles  - update Rollen bearbeiten
Tenant relations - create Mandantenbeziehungen anlegen
Tenant relations - delete Mandantenbeziehungen löschen
Tenant relations - erase Mandantenbeziehungen unwiderruflich löschen
Tenant relations - query Mandantenbeziehungen abfragen
Tenant relations - update Mandantenbeziehungen bearbeiten
Tenants - create (incl. admin) Mandanten anlegen (inkl. Admin)
Tenants - delete Mandanten löschen
Tenants - erase Mandanten unwiderruflich löschen
Tenants - query Mandanten abfragen
Tenants - update and restore Mandanten wiederherstellen und bearbeiten
Tenant-specific security settings

Mandanten-spezifische Sicherheitseinstellungen

Users - create Benutzer anlegen
Users - delete Benutzer löschen
Users - erase Benutzer unwiderruflich löschen
Users - query Benutzer abfragen
Users - update Benutzer bearbeiten

Default Offerings and Tenant Relations

Bosch IoT Permissions provides the possibility of registering application instances that define offerings which are automatically assigned to all tenants.
The IM application itself offers its permissions to all other tenants, grouping the permissions within the IM Default Offering and assigning them to all tenants using the IM Tenant Creation Relation

Default Offering

Example of the "IM Full Service Offering" that is attributed by default with the applicable scope "Data of consuming tenant"

Note: The icon  next to the "Example" tenant shows that the roles and permissions will be applicable to the Example tenant.

Default Tenant Relation

Example of the "IM Full Service Tenant Relation" that is assigned by default to ALL tenants:

The tenant relation is not limited in time, thus, the start date is the time of the IM installation and the end date is 2037 (see Bosch IoT Permissions - Service Specification).

Note: The icon  next to the "Default" tenant shows that he is the provider of that tenant relation.

Role assignment via tenant relations

This example assumes you want to delegate the task of managing user settings to an agency.

A setup similar to this scenario is shown in the section Create a Tenant Relation-Tenant assignment and would allow the "Agency" to act on behalf of the DEFAULT tenant, but restrict the permissions on users' management.

DEFAULT tenant activity

If you want to reproduce the scenario you should complete following steps:

  1. Log in as the "Admin" of the "DEFAULT" tenant.
  2. Create a role "User Admin".
    1. Assign all IM user-related permissions to that role.
    2. Assign the permissions to read groups and roles, if you want to enable the agency to relate such elements to a user.
  3. Create an offering "User Management" with applicable scope "Data of providing tenant".
  4. Assign the "User Admin" role to the offering.
  5. Create a tenant relation element "Update my users".
  6. Assign the offering to the tenant relation.
  7. Create an "Agency" tenant (and automatically its admin user).
  8. Assign the "Agency" tenant to the tenant relation.

Results of the Default admin's activity

  • "DEFAULT" is the provider  and "Agency" is the consumer of the tenant relation element "Update my users".
  • As the only offering involved in that relation is with applicable scope "Data of providing tenant" the users of the "DEFAULT" tenant (i.e. the providing tenant) can be managed.

Now you can log out the DEFAULT Admin user and change to the Agency's point of view.

Agency tenant activity
  1. Log in as the Agency admin user.
  2. Pin the admin user to find out which roles he has been assigned so far.
    As of now, you should have only the (default) "IM Tenant Administrator" role.
  3. Assign yourself the "User Manager" role (that was granted by the DEFAULT Admin user via "Update my users" tenant relation in the previous steps).
  4. Log out and log in again to get your new identity context (which now includes the new role as well as the permissions assigned to that role).

Results of the Agency admin's activity

  • The Agency's administrator is granted all the necessary permissions for administrating the entities of its own tenant.
  • Pinning the new role shows to which tenant's data the permissions are applicable. In our case, the Agency's admin is allowed to manage another tenant's users (i.e. act on behalf of another tenant). The DEFAULT tenant is highlighted and displays the "applicable" icon.
  • To actually apply the new role to the other tenant's data (namely DEFAULT), select this one from the drop-down list that appears on the upper part of the UI.
  • After the switch, you can apply the role that was assigned via tenant relations.
    See Act on behalf of another tenant.

Act on behalf of another tenant

Bosch IoT Permissions provides the possibility for users to act on behalf of another tenant. This means that if a tenant offers permissions (e.g. to manage its users) with applicable scope PROVIDER, it is possible to switch the identity context to the providing tenant. In that case, users of a consuming tenant (granted with those permissions) are able to see, manipulate, and create data on behalf of the providing tenant (i.e. transparently act as if the user's entity would belong to the other tenant).

Precondition

You will need to log in as a user who has been granted permissions to act on behalf of another tenant.

The corresponding setup is described in section Role assignment via tenant relations.

Procedure description

  1. Use the login dialog to authenticate (using the tenant's name to which your user belongs).
  2. If you are granted permissions that would apply to another tenant's data, the name of that tenant should appear on the upper part of the user interface.
  3. Select the tenant you need to work for
  4. The context changes immediately, thus, you will see only those entities of the other tenant for which you have permission (in our case all other columns except for the Users column are collapsed, as you have no permission for these entities).
  5. Here you can, for example, create a new user.

Results

To leave the context of the tenant you are active for, switch back to your own tenant.

Restrictions

Acting on behalf of another tenant cannot be used in nested form.
This means that if the tenant on whose behalf you are acting itself has a tenant relation granting permission to work for a third-party, these rights cannot be assigned.
Thus, all tenants that delegate permissions need a tenant relation with your tenant.

Glossary

Application /
Application Instance

An application is a logical instance (e.g. business application) that defines permissions and roles and uses the Bosch IoT Permissions authentication and authorization services.

Applicable scope The offering has exactly one applicable scope (ApplicableScope), i.e. the definition of the context in which an offered permission or role is applicable.
  • Applicable scope PROVIDER: The permissions will affect the data of the providing tenant.
    Using this scope, the providing tenant can allow other tenants to act on his behalf.

  • Applicable scope CONSUMER: The permissions will affect the data of the consuming tenant.
    Using this scope, the providing tenant can allow other tenants to use his applications. The data resulting from using the application will be in the ownership of the consuming tenant.

Authentication

A user is authenticated after a successful login, as the existence of the username and the corresponding valid password are found in the Bosch IoT Permissions database.

Authorization

A user is authorized for an operation if the appropriate permission is assigned to the user in the IM database.

Domain

A domain is an infrastructure element that defines a realm of administrative autonomy, authority, or control within Bosch IoT Permissions.

Element / Entity

An element is an entity of Bosch IoT Permissions that contains or receives information. In the case of Bosch IoT Permissions, the User, Group, Role, Tenant, Permission, etc. are regarded as elements/entities. Furthermore, the operations these elements can execute may also refer to entities of a custom application (e.g. application role).

Email template

An email template is the pattern for the content of a specific email.
Commonly the Bosch IoT Permissions related templates hold text, a hyperlink and placeholders.
Placeholders (e.g. the name of the user which will receive the email) can be used within the template, to easy personalizing the email at runtime, before sending the email.

Group

A group is regarded as an element within the organizational structure. As a group can have sub-groups, whenever the term group is mentioned in this guide all group hierarchies are referred to as well.

Instance

See Application.

Offering An offering is a set of roles and permissions offered by one tenant to another. Thus, the permissions can be spread outside the boundaries of a tenant.

Operation

An operation is an executable image of the program, which upon invocation executes some function for the user.

Permissions

A permission assigned to a user (by assigning a role) grants the approval for this user to perform an operation.

Privileged users A privileged user (e.g. administrator) is empowered to perform critical operations, which other users are not allowed.

Relation / Assignment

A relation is created when assigning elements to one another.

E.g. a user can be assigned to a group or a role, thus, becoming related to that element.

Role

A role is a job function within the context of an organization. The associated semantic regards rights and duties (the authority and responsibility) conferred upon the user (or group of users) assigned to that role.

Self-registered User A user (see User) which was created via the self-registration process (a user fills out a form to create a new user account).
Scope See Applicable scope.

Tenant

A tenant is a legal organizational element that is mostly representative of a company.
As only one tenant can be active at once, on user login the Bosch IoT Permissions service can assign different permission to the same user based on the tenant for which the user is active.

Tenant Relation A tenant relation is an element used to assign an offering to another tenant. 

User

A user is a human being, a machine, network etc. subscribing to use a part of an application.

User attributes /
User Profile

A generic map of attributes which are directly assigned to a user, like a telephone number or an address.

The Bosch IoT Permissions User Profile consists of several user attributes. The key-value pairs which are used in the User Profile are based on the vCard version 4 standard [RFC 6350].