Identity Management Identity Management Administrator Guide Version 3.1.3 Bosch Software Innovations Americas: Bosch Software Innovations Corp. 161 N. Clark Street Suite 3550 Chicago, Illinois 60601/USA Tel. +1 312 368-2500 info@bosch-si.com www.bosch-si.com Asia: Bosch Software Innovations c/o Robert Bosch (SEA) Pte Ltd 11 Bishan Street 21 Singapore 573943 Tel. +65 6571 2220 info-sg@bosch-si.com www.bosch-si.sg Europe: Bosch Software Innovations GmbH Ziegelei 7 88090 Immenstaad GERMANY Tel. +49 7545 202-300 info-de@bosch-si.com www.bosch-si.de Bosch Software Innovations GmbH 1/25
Copyright Notice Bosch Software Innovations GmbH, 2010-2013. All rights reserved. Dissemination or reproduction of this document or any part of it for any purpose or in any form whatever is not permitted without the prior express written consent of Bosch Software Innovations GmbH. Information contained in this document may be subject to revision without advance notice. MLDS, Visual Rules and Work Frame Relations are registered trademarks of Bosch Software Innovations GmbH. BOSCH and the symbol are registered trademarks of Robert Bosch GmbH, Germany. Some of the product and company names used in this document are trademarks and/or registered trademarks. They are used explicitly for reference purposes and are, independent of marking, property of their respective owners. Bosch Software Innovations GmbH 2/25
Table of Contents Chapter 1 About this guide... 5 1.1 Identity Management (IM)... 5 1.2 Target audience... 5 1.3 Getting started... 5 Chapter 2 Get artifacts... 6 Chapter 3 Installation and first configuration... 7 3.1 Configuring IM server initialization parameters... 7 3.2 Configuring the data source... 9 3.2.1 DBMS support... 9 Sort order on DBMS... 9 How to support full Unicode... 10 3.3 Deploy the IM server... 10 3.3.1 JBoss Deployment... 10 Data Source configuration... 10 jboss-web.xml... 11 jboss-deployment-structure.xml... 11 3.4 Configuring the IM user interface Web application... 11 3.5 Deploy the IM user interface Web application... 12 3.5.1 Accessing the IM server using SSL... 12 3.6 Using the IM user interface... 13 Chapter 4 External User Management... 15 4.1 Configuring the connection to an external identity provider (LDAP Active Directory)... 15 4.1.1 External Identity Provider... 16 4.1.2 LDAP/AD Specific Configuration... 17 Attribute Mapping... 17 4.1.3 Example... 18 4.1.4 18 4.1.5 Tips and known pitfalls... 18 Chapter 5 Logging... 19 5.1 Server... 19 5.2 User interface Web application... 19 Chapter 6 Installing applications into IM... 20 6.1 Preconditions... 20 6.2 Permission to install an application... 20 6.3 Mandatory information provided by the application to be installed... 20 6.3.1 Auto Assignment of Offering Types... 21 6.4 Example Code: Using the Java-API to install a new application... 21 Bosch Software Innovations GmbH 3/25
Chapter 7 Appendix... 22 7.1 IM Specification... 22 7.2 Features... 22 7.3 System Requirements... 23 7.3.1 Minimum Hardware Requirements... 23 7.3.2 Supported Platforms... 23 7.4 Limitations... 24 Chapter 8 Contact us... 25 Bosch Software Innovations GmbH 4/25
Chapter 1 About this guide 1.1 Identity Management (IM) The Identity Management (IM) component provides interfaces which other systems can use to administrate their usage policy: user authentication and authorization. The main scope of IM in a customer application is to manage the permissions to read, write or execute operations (as parts of the customer application). The users can be organized in groups according to the current structure of a company. In order to support a flexible and scalable business organization, which can be restructured without the need of involving the ITspecialists, the user permissions are not derived from their membership of a group or client, but according to roles. The decisions to give a user access to certain functions, are based on the roles that individual users - as a part of an organization - have. It provides access security by describing complex access control policies. This can reduce the source of errors while administration and consequently the costs for a secure useradministration can be reduced. 1.2 Target audience This document is intended to help IM administrator users understand how to install and configure the Identity Management (IM). It describes common administrative and operative tasks to get the IM system running. Once the IM user interface is available please use the IM User Guide for further support. 1.3 Getting started An overview on all features, supported platforms, limits etc. is provided at Appendix > IM Specification. Bosch Software Innovations GmbH 5/25
Chapter 2 Get artifacts For customers of the Visual Rules Suite, IM offers an assembly that bundles the IM server as well as the IM user interface Web application in one zip file. IM assembly for Visual Rules Group ID: com.bosch.im Artifact ID: visualrules-im-assembly Packaging: zip Version: 3.1.3 Unzip the assembly and you will find: a Web archive containing the back-end: im-server a Web archive containing the user interface: im-ui-webapp a folder named identitymanagement containing configuration files for both applications: o im-backend.properties - for the IM server o im-webui.properties - for the user interface Bosch Software Innovations GmbH 6/25
Chapter 3 Installation and first configuration Precondition The setting of the Java system property user.home depends on your operating system and Java installation. The IM server as well as the IM user interface Web application will expect configuration files at user.home/identitymanagement. This will be as well the location where you will find the logfiles of both appications. Therefore, the system property user.home must be set to an arbitrary but existing directory. That means, it must not necessarily point to the operating system specific user home directory but the directory must exist. In order to install the IM server while your application server is running, please make sure to previously prepare following configuration steps. Configuring IM server initialization parameters Configuring the data source o DBMS support Deploy the IM server o JBoss Deployment Configuring the IM user interface Web application Deploy the IM user interface Web application Using the IM user interface 3.1 Configuring IM server initialization parameters The IM server needs you to specify some parameters that will apply automatically when IM performs its initialization. The parameter list includes among others the very first tenant, your administration user, your initial password etc. 1. The IM server expects a properties file named im-backend.properties at following path: [user.home]/identitymanagement/im-backend.properties The path on a Windows system would be for example: C:\Users\<user>\identitymanagement\imbackend.properties 2. Copy the identitymanagement folder of the visualrules-im-assembly to your user home directory 3. Open im-backend.properties (e.g. using a simple text editor) and adjust the properties' values to configure IM according to your company's needs. A table describing default values and their meaning is provided at the end of this section. Changing the values in the property file after the initialization of the IM server has no effect (unless the database is reinitialized). The only exception are the properties used for the session timeout configuration which will be applied when the IM server is restarted. Bosch Software Innovations GmbH 7/25
Attribute Configuration property Default value Description Tenant Name com.bosch.im.init.tenant.name DEFAULT The name of the default root tenant. Domain Name com.bosch.im.init.domain.name IM The name of the default domain assigned to the root tenant. Application Instance Name com.bosch.im.init.instance.name IM The name of the default instance assigned to the default domain. Admin User Name com.bosch.im.init.user.admin.name Admin The name of the default administration user for the root tenant and all entities assigned to this tenant. Admin User Password not configurable Admin The initial administrator's password; this is the same as the configured user name. For security reasons it is strongly recommended to change your password after your first login. However, the system will not force you to do so. Admin Role com.bosch.im.init.role.admin.name Administrator The name of the (main) administration role. The administration user has this role automatically. (This role provides all permission necessary to administrate the IM system.) Application Installer Role com.bosch.im.init.role.app.name ApplicationInstall er The name of the application installer role. The administration user has this role automatically. (This role provides all permission necessary to register and install new applications as well as their roles and permissions.) Max. server-side sessions com.bosch.im.init.session.max 10000 The maximum number of sessions on server side. As sessions are held in memory this value should only be raised if enough memory is available. Session timeout com.bosch.im.init.session.timeout 120 The session timeout in minutes. The session expires when a logged-in user is inactive for more than the configured amount of time. In this case he has to log-in again. Bosch Software Innovations GmbH 8/25
3.2 Configuring the data source Please have a look at the documentation of your runtime container for instructions on how to configure a data source. The IM server supports data sources as listed at Appendix > IM Specification. It expects that the runtime container provides a data source with the name jdbc/im-ds and the type javax.sql.datasource Example Following examples shows a snippet for an Oracle data source configuration for Tomcat (7.0.x) <Resource name="jdbc/im-ds" auth="container" type="javax.sql.datasource" maxactive="100" maxidle="30" maxwait="10000" username="admin" password="admin" driverclassname="oracle.jdbc.oracledriver" url="jdbc:oracle:thin:@//localhost:1521/orcl" /> Database Initialization Due to a very comfortable way of initialization and migration of the database schema, the given credentials for the data source needs permission to create, update and alter tables of this schema. At startup, IM checks the current schema status. In case of the first initialization it automatically creates the necessary tables. In case of a necessary migration it migrates to the latest database version. You can follow this on the console. Example of a console output during initialization INFO com.bosch.msf.common.jdbc.dbidentifierresolver - Resolved database product = [h2], version = [1.3.168 (2012-07-13)] INFO com.googlecode.flyway.core.metadatatable.metadatatableimpl - Creating Metadata table: "PUBLIC"."IDM00_SCHEMA_VERSION" INFO com.googlecode.flyway.core.init.dbinit - Schema initialized with version: 0 INFO com.googlecode.flyway.core.migration.dbmigrator - Current schema version: 0 INFO com.googlecode.flyway.core.migration.dbmigrator - Migrating to version 3.0.0.0 INFO com.googlecode.flyway.core.migration.dbmigrator - Migrating to version 3.0.0.1 INFO com.googlecode.flyway.core.migration.dbmigrator - Migrating to version 3.0.1.0 INFO com.googlecode.flyway.core.migration.dbmigrator - Migrating to version 3.0.3.0 INFO com.googlecode.flyway.core.migration.dbmigrator - Migrating to version 3.0.3.1 INFO com.googlecode.flyway.core.migration.dbmigrator - Successfully applied 5 migrations (execution time 00:07.158s). Example of no migration necessary INFO com.googlecode.flyway.core.migration.dbmigrator - Current schema version: 3.0.3.1 INFO com.googlecode.flyway.core.migration.dbmigrator - Schema is up to date. No migration necessary. 3.2.1 DBMS support Sort order on DBMS For sorting and paging IM relies on the functionality provided by DBMS. This leads to an increased performance as the data is already sorted and limited on the database before mapping it into Java and allows defining the sorting behavior in a very fine-grained manner. As a result, the ordering of entities might be different when comparing different DBMS especially if the default settings of the DBMS are used. For changing the sort order for the DBMS please refer to the manual of the database and adapt the settings accordingly. Bosch Software Innovations GmbH 9/25
Oracle 11g In Oracle you can check your NLS_SORT settings with the following SQL statement: SELECT SYS_CONTEXT ('USERENV', 'NLS_SORT') FROM DUAL; How to support full Unicode MySql 5.5 http://mathiasbynens.be/notes/mysql-utf8mb4 Oracle 11g Set System Property for Oracle JDBC driver oracle.jdbc.defaultnchar=true 3.3 Deploy the IM server The IM server is available as Web application ARchive (.war). Check your application server's documentation on how to deploy a Web application ARchive or simply copy the im-server into your application server. Also make sure that there is a home directory set for your user and that it is accessible via Java's system property user.home (it depends on your operating system how the Java system property gets resolved). The user's home directory is used for Configuration and Logging capabilities. If you need to import users from an external system, please additionally follow the configuration instructions at Configuring the connection to an external identity provider (LDAP Active Directory) before deploying the IM server, as changes on that configuration would need an IM server restart anyway. 3.3.1 JBoss Deployment In order to deploy IM on JBoss AS 7, the following things have to be considered. It is assumed that JBoss is started in standalone mode. Data Source configuration The IM data source has to be provided by JBoss. The data source is configured in JBOSS_HOME/standalone/configuration/standalone.xml. Example: <datasource jta="true" jndi-name="java:jboss/datasources/im-ds" pool-name="im-ds" enabled="true" use-java-context="false"> <connection-url>jdbc:oracle:thin:@//localhost:1521/orcl</connection-url> <driver>oracle</driver> <security> <user-name>username</user-name> <password>topsecret</password> </security> </datasource>... <drivers>... <driver name="oracle" module="com.oracle.ojdbc6"> <xa-datasource-class>oracle.jdbc.oracledriver</xa-datasource-class> </driver> </drivers> Please make sure that the driver is deployed as JBoss module. Bosch Software Innovations GmbH 10/25
jboss-web.xml You have to provide a jboss-web.xml file, which sets IM's context path and maps the JNDI datasource. <jboss-web> <context-root>im</context-root> <resource-ref> <res-ref-name>jdbc/im-ds</res-ref-name> <res-type>javax.sql.datasource</res-type> <res-auth>container</res-auth> <jndi-name>java:jboss/datasources/im-ds</jndi-name> </resource-ref> </jboss-web> jboss-deployment-structure.xml Currently, there is an integration issue with Spring AOP and JBoss' datasource module ironjacamar. As a workaround, the file jboss-deployment-structure.xml is needed. <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0"> <deployment> <dependencies> <module name="org.jboss.ironjacamar.jdbcadapters" /> </dependencies> </deployment> </jboss-deployment-structure> 3.4 Configuring the IM user interface Web application The IM user interface Web application comes with a file named im-webui.properties where some default values concerning the appearance are stored. You will need to configure at least the URL to the current location of the IM server. To do so, the properties file named im-webui.properties can be located at one of the following paths within your user home directory: 1. If you have only one IM user interface running user.home/identitymanagement/im-webui.properties The path on a Windows system would be for example: C:\Users\<user>\identitymanagement\im-webui.properties 2. If you have multiple IM user interfaces running user.home/identitymanagement/[context-path]/im-webui.properties Whereby [context-path] is the (possibly adjusted) path, the user interface is reachable at, from the application server's point-of-view. To identify which context path is used for your installation, start the deployed IM user interface Web application and have a look at the log file. Bosch Software Innovations GmbH 11/25
Within the properties file you can overwrite the default values of the properties described in the following: Configuration Property Default value Description imserverurl http://localhost:8181/im URL where the IM server is located batchoperationlimit 2000 Specifies the maximal number of entities, which could be involved in a drag&drop operation tablepagelength 16 This property specifies the height of the tables in the IM user interface. A value of "16" means that each table shows 16 entities without scrolling. tenantsvisible usersvisible true true The user interface displays all existing tenants, users, groups, roles, permissions, domains and applications it a table per type of entity. groupsvisible true Changing the default value to false will hide the according table. rolesvisible true permissionsvisible domainsvisible applicationsvisible true true true tenantscollapsed userscollapsed true false The user interface displays all existing tenants, users, groups, roles, permissions, domains and applications it a table per type of entity. groupscollapsed false After a successful login, a user can collapse or expand each of the tables visible. rolescollapsed false However, the value defined for these properties will influence the first appearance of the tables (collapsed or permissionscollapsed true expanded) at each login for all users. domainscollapsed applicationscollapsed true true You can adjust these configuration properties anytime, without the need to restart the IM user interface Web application. However from the UI user's point of view they are visible only after a new login. 3.5 Deploy the IM user interface Web application The IM user interface Web application is available as Web application ARchive (.war). Check your application server's documentation on how to deploy a Web application ARchive or simply copy the im-ui-webapp into your application server. Also make sure that there is a home directory set for your user and that it is accessible via Java's system property user.home (it depends on your operating system how the Java system property gets resolved). The user's home directory is used for IM user interface Web application Configuration and Logging capabilities. 3.5.1 Accessing the IM server using SSL If you want to secure the connection between IM user interface and IM server, be sure that the server's certificate is available in the Java trust store on the machine where the user interface is running on. This is especially important if you are using self-signed certificates. Bosch Software Innovations GmbH 12/25
By default, the system-wide trust store is used. If you want to specify a separate trust store for IM user interface Web application, you may use the system properties "javax.net.ssl.truststore" and "javax.net.ssl.truststorepassword" when starting the application server. Check your application server's documentation if additional possibilities are provided. 3.6 Using the IM user interface Open your browser at the URL of your application server (e.g. for Tomcat http://<your server URL>:<the port specified>/im-ui-webapp-<version>)and login with the administrator's credentials (as configured at Configuring IM server initialization parameters).the initial default credentials are DEFAULT / Admin / Admin. For security reasons, after your first login it is strongly recommended to change your password. However, the system will not force you to do so. Find details about changing user settings at Update User. After a successful login you should see the initial screen, similar to following figure Bosch Software Innovations GmbH 13/25
Detailed descriptions on how you can create all types of IM entities (tenant, user, groups etc.) and how to empower other users to administrate the entities can be found in our IM User Guide. Bosch Software Innovations GmbH 14/25
Chapter 4 External User Management Users managed within an external identity provider (e.g. LDAP, Active Directory) can be imported into IM in order to be assigned to groups, roles etc. Imported users are visualized by following icon. In order to synchronize them to the IM data store an external identity provider must be configured within IM. A basic configuration valid for all tenants must be present at the IM server. The basic configuration for the connection to the external LDAP/AD server is XML based and needs to be available in the locations described in detail at Configuring the connection to an external identity provider (LDAP Active Directory). In the IM user interface the setting per tenant can be adjusted. See IM User Guide o o Configuring an Identity Provider for a Tenant Synchronizing a Tenant's users with its External Identity Provider Imported users are updated with data of the external data source regularly, thus the IM user interface doesn t allow for updating or deleting an imported user. However, the user interface will support you in creating and deleting assignments to other IM units: Assign a User to a Group - Delete User-Group assignment Assign a User to a Role - Delete User-Role assignment Assign a Permission to a User - Delete User-Permission assignment 4.1 Configuring the connection to an external identity provider (LDAP Active Directory) The IM server can manage a mix of entities generated within the IM system and users managed by an LDAP Active Directory as external identity provider. The basic configuration for the connection to the external LDAP/AD server is XML based. IM tries to search for an according xml file in following locations and following order: 1. The user home directory user.home/identitymanagement/<filename> On a Windows system the path would be for example: C:\Users\<user>\identitymanagement\com.bosch.im.externalidentityproviders.xml 2. The classpath classpath://<filename> This could be for example <root path of your application server>/webapps/im-server/web- INF/classes/com.bosch.im.externalidentityproviders.xml The xml file must be valid within the elements described in following xsd schemas im_config1_0_0.xsd im_config_ldap1_0_0.xsd Bosch Software Innovations GmbH 15/25
4.1.1 External Identity Provider (See im_config1_0_0.xsd) Attribute Description Use Default value type The type of the external identity provider (e.g. ldap). The concrete provider implementation which corresponds to this type, also defines the syntax and semantic of the body of this tag. For now IM only supports type ldap. required name The (within IM) unique name used to identify this external identity provider. required tenant syncinterval The name of the tenant which owns/manages this required external storage provider. The tenant name has following restrictions: min 2, max 24 characters, validation pattern [A-Z_0-9]{2,24} This is commonly the default tenant created at initialization (see Configuring IM server initialization parameters). In case another tenant is the onwer please use the IM user interface (Create Tenant) or the IM RESTful API (Tenant Resource) to create the according tenant. The time interval to synchronize all tenants relying on this external identity provider. The time unit of the interval can be defined via attribute "synctimeunit". A value of "0" disables the automatic synchronization. required synctimeunit The time unit of the interval to synchronize (see "syncinterval"). optional MINUTES SECONDS MINUTES HOURS DAYS reftenant The name of the tenant for which this external identity provider should be used. If reftenant is not set, no tenant synchronization/authentication configuration will be stored. A fine grained configuration per tenant can be done later on supported by the user interface (see Configuring an Identity Provider for a Tenant and Synchronizing a Tenant's users with its External Identity Provider) optional no tenant Bosch Software Innovations GmbH 16/25
4.1.2 LDAP/AD Specific Configuration (See im_config_ldap1_0_0.xsd) Attribute Description Use Default value url The URL of the LDAP server connection. Restriction: ldap://.+ required managerdn managerpw usersearchbase Used only with "search" authentication method. It is the DN of the user who will bind to the LDAP server to perform the search Used only with "search" authentication method. It is the password of the user who will bind to the LDAP server to perform the search Context name to search in, relative to the base DN in the ldapurl required required required usersearchfilter A filter expression used to search for the user DN that required will be used in LDAP authentication. This is a LDAP search filter (as defined in 'RFC 2254') with optional arguments. In this case, the username is the only argument, denoted by '{0}'. Example: (uid={0}) - this would search for a username match on the uid attribute. usernameattributeid The ID of the attribute that gets mapped to IM username. Example: AD: samaccountname / LDAP: uid required subtreesearch Flag to enable deep search through the sub tree of the ldapurl + searchbase. optional true Attribute Mapping IM allows to fill IM attributes by synchronizing them from an LDAP/AD server. userattribute Attribute Description Use Default Value from The LDAP attribute which should be mapped required to The IM attribute the LDAP attribute should be mapped to FIRSTNAME LASTNAME EMAIL required Bosch Software Innovations GmbH 17/25
4.1.3 Example Following file com.bosch.im.externalidentityproviders.xml configures the connection to an LDAP server <?xml version="1.0" encoding="utf-8"?> <externalidentityproviders xmlns="http://www.bosch.com/iap/imexternalidentityproviderconfig1_0_0" xmlns:ldap="http://www.bosch.com/iap/imexternalidentityproviderldapconfig1_0_0"> <!-- General configuration for identity provider --> <externalidentityprovider type="ldap" name="my-ad" tenant="default" syncinterval="5" synctimeunit="minutes"> <!-- LDAP/AD Specific Configuration Part --> <ldap:ldap url="ldap://localhost:450" managerdn="admin" managerpw="admin" usersearchbase="dc=ad,dc=local" usersearchfilter="(objectclass=user)" subtreesearch="true" usernameattributeid="samaccountname"> <!-- Attribute Mapping Configuration For LDAP/AD --> <ldap:attributemapping> <ldap:userattributes> <ldap:userattribute to="firstname" from="firstname" /> <ldap:userattribute to="lastname" from="sn" /> </ldap:userattributes> </ldap:attributemapping> </ldap:ldap> </externalidentityprovider> </externalidentityproviders> 4.1.4 Tips and known pitfalls The internal scheduler which checks for updated/necessary configurations which have to be synchronized is configured with a 60 seconds delay. Synchronizations might be delayed triggered with a maximum delay of 60 seconds. A restart of IM does not cause a new synchronization. IM persists the timestamp of the last synchronization run and will synchronize a configuration only with the configured interval (see above). Synchronization Conflicts Scenario of conflicting users: 1. User max@mustermann has been created locally within IM. 2. IM synchronize an external LDAP server with a user named max@mustermann Result: IM will not synchronize this user, but will log that this user is conflicted instead. Bosch Software Innovations GmbH 18/25
Chapter 5 Logging IM is shipped with a default implementation of a logging mechanism (Logback). Both, logging in IM server and in IM user interface Web application, can be configured separately. 5.1 Server By default, the IM server is configured as follows: Log level: INFO Directory where the log file is stored: [user.home]/identitymanagement/logs/im-backend- <date>.log The [user.home] placeholder is resolved to the Java system property user.home which depends on your operating system and Java installation. In order to change the logging configuration (e.g. to log level DEBUG), please proceed as described in the following steps: 1. Navigate to the logging configuration file im-backend-logback-included.xml at your IM home directory: user.home/identitymanagement/im-backend-logback-included.xml The path on a Windows system would be for example: C:\Users\<user>\identitymanagement\im-backend-logback-included.xmlAs the logging configuration file is optional you may have to create a new file in order to be able to change the logging configuration. 2. Open the file (e.g. using a simple text editor) and overwrite the default configuration according to your needs Tip: See the official Logback manual at http://logback.qos.ch/manual/index.html Example <included> <!-- increase log level to DEBUG --> <logger name="com.bosch.im" level="debug" /> </included> 3. Changes to the log configuration are applied automatically, without the need to restart the server. 5.2 User interface Web application By default, the IM user interface Web application is configured as follows: Log level: INFO Directory where the log file is stored: [user.home]/identitymanagement/logs/im-webui- <date>.log The [user.home] placeholder is resolved to the Java system property user.home which depends on your operating system and Java installation. In order to change the logging configuration (e.g. to log level DEBUG), please proceed as described in the following steps: 1. Navigate to the logging configuration file im-webui-logback-included.xml at your IM home directory: user.home/identitymanagement/im-webui-logback-included.xml The path on a Windows system would be for example: C:\Users\<user>\identitymanagement\im-webui-logback-included.xml As the logging configuration file is optional you may have to create a new file in order to be able to change the logging configuration. 2. Open the file (e.g. using a simple text editor) and overwrite the default configuration according to your needs Tip: See the official Logback manual at http://logback.qos.ch/manual/index.html Example <included> <!-- increase log level to DEBUG --> <logger name="com.bosch.im" level="debug" /> </included> 3. Changes to the log configuration are applied automatically, without the need to restart the server. Bosch Software Innovations GmbH 19/25
Chapter 6 Installing applications into IM Applications install themselves into IM via the provided API and are not added manually (e.g. over an administration UI) For further details please consult the Javadoc for package com.bosch.im.command - Instance Registration Command Builder. Preconditions Permission to install an application Mandatory information provided by the application to be installed o Auto Assignment of Offering Types Example Code: Using the Java-API to install a new application 6.1 Preconditions Before an application can be installed in IM, the IM system itself must have been initialized (see Installation and first configuration) and must be running. 6.2 Permission to install an application IM provides by default the role ApplicationInstaller which has the corresponding permission INSTALL_APPLICATION which allows to perform all steps that are necessary to install a new application. 6.3 Mandatory information provided by the application to be installed There is a clear cut between the responsibilities of IM and the responsibilities of the application to be installed within an IM domain. The following table shows which information is configured within IM and which information MUST be delivered by the application itself: IM Responsibilities Tenant Domain User Group Role Application Responsibilities Application (integrity, functionality, annotations to require permission for executing an operation etc.) Role (application related, i.e. self defined roles) Permission (application related, i.e. self defined permission) Optional: Add Offering Types including Permissions and Roles (see below for details) Bosch Software Innovations GmbH 20/25
6.3.1 Auto Assignment of Offering Types It is possible to assign Offering Types automatically to all tenants (existing and new ones) by enabling autoassignment. See com.bosch.im.command - enableautoassignment As a result, those tenants are able to use the contained permissions and roles (e.g. assign them to their users or groups). After installing an application the permissions required in order to log in and use the application must be granted. This has to be done by assigning roles or permissions via the IM administration user interface. 6.4 Example Code: Using the Java-API to install a new application try { // login with user who has the rights to install an application final IIdentityContext identitycontext = getauthenticationmanager().getidentitycontext( new Credentials( ADMIN_NAME, ADMIN_PW, TENANT_NAME ) ); // sets the context for IM IdentityContextHolder.setContext( identitycontext ); } catch( final AuthenticationDeniedException e ) { // handle authentication denied exception } // the known or selected domain id the application should be installed to final EntityId<IDomain> applicationdomainid = retrievedomainid(); // the known tenant id from the context which the user has been logged in final EntityId<ITenant> applicationtenantid = IdentityContextHolder.getContext().getCurrentTenant().getId(); // the application's name final String applicationname = "MyApplication"; // persist the application instance in IM final IInstance instance = getentitybuilderfactory().instance().name( applicationname ).domainid( applicationdomainid ).tenantid( applicationtenantid ).get(); // get the instance registration command builder final IInstanceRegistrationCommandBuilder instanceregbuilder = getcommandfactory().instanceregistrationbuilder( instance ); // add permission to the instance with its translation instanceregbuilder.addpermission( "MyAppAdminPermission" ).addtranslation( "Admin Permission", I18NAttributeIdentifier.NAME, Locale.ENGLISH ).addtranslation( "Admin Berechtigung", I18NAttributeIdentifier.NAME, Locale.GERMAN ); // add a instance role to the instance with its translations and add the role directly the // before created "MyAppAdminPermission" and the in IM defined READ_USER permission instanceregbuilder.addrole( "AdminRole" ).addtranslation( "Admin Rolle", I18NAttributeIdentifier.NAME, Locale.GERMAN ).assignownpermission( "MyAppAdminPermission" ).assignimpermission( Permission.READ_USER ); // gets the command to execute final ICommand<IInstanceRegistration> registerinstancecommand = instanceregbuilder.get(); // registers the instance and all its defined permissions and roles with their translations final IInstanceRegistration instanceregistration = getcommandexecutor().execute( registerinstancecommand ); Bosch Software Innovations GmbH 21/25
Chapter 7 Appendix 7.1 IM Specification Features System Requirements o Minimum Hardware Requirements o Supported Platforms Limitations 7.2 Features Central and multi-tenancy-aware user & authority management with Web based user interface and authentication service. IM features at a glance Powerful model for o o o User management: Users organized in (hierarchical) Groups Roles assigned to Users/Groups Application management: Applications organized in Domains Applications defining Permissions and Roles Permissions exposed for assignment to Roles Tenant Management: Intuitive user interface Logical separation of data between Tenants Empowerment for Tenant administrators to manage the tenant's own entities Well-defined data sharing between Tenants: Authentication service for Users Remote RESTful API (beta) Offerings of Permissions/Roles to be used by other Tenants Managing Relationships between Tenants (applying Offerings) Preparing standardized templates for such Relationships Internationalization (I18N) of names and descriptions for all IM entities Integration of external identity provider (LDAP) for authentication and user synchronization Safekeeping through mechanism to mark entities as deleted / data privacy protection through mechanism to permanently delete entities Bosch Software Innovations GmbH 22/25
7.3 System Requirements 7.3.1 Minimum Hardware Requirements IM back end server o 2 GB RAM IM user interface server o 2 GB RAM 7.3.2 Supported Platforms Operating Systems: o Microsoft Windows 7 o Java: Databases: Linux o Oracle Java SE 7 o Oracle 11g Release 2 Enterprise Edition o Microsoft SQL Server 2008 o MySQL 5.5 o H2 1.3 (not for production purposes) Web Application Server: o Tomcat 7 o JBoss 7.1 External Authentication Providers: o o Microsoft Active Directory LDAP Web Browser (for the IM User Interface): o o Firefox 17 (Microsoft Windows, Linux) Internet Explorer 9 (Microsoft Windows) Validity period will endure at the most as long as the version of infrastructure software of third party manufacturers defined in this document (Operating Systems, Java, etc.) is publicly and officially supported. Bosch Software Innovations GmbH 23/25
7.4 Limitations There are some limitations regarding the setup and usage of IM. These limits have to be considered when integrating and working with IM. The currently identified limits are documented here but are subject to change in upcoming versions without notice. Using IM without complying to or exceeding these defined limits may be possible but is not recommended and is not supported. Not all limits are explicitly checked by the product but must be adhered to by other means. Category Topic Limit Description Deployment Clustering Not supported It is not supported to run multiple IM backend instances in a cluster due session handling within the IM backend server Quantity Structure Max. number of tenants 1 000 Max. number of domains/applications 100 Max. number of users (over all tenants) 200 000 Max. number of groups/roles/permissions over all tenants/applications 10 000 Max. number of groups/roles/permissions per tenant/application 1 000 Max. hierarchical depth of tenants and groups 50 Regarding the User Interface: nested groups are not manageable very well in the User Interface when depth exceeds 10 levels User Interface Max. number of objects used for multi selection operations 2 000 Multi selection operations (e.g. assigning many users to a group) in the User Interface are supported only up to an amount of 2 000 involved objects. Theoretically more objects can be used in a multi selection, but the duration these operations take then can get very long and the UI cannot guarantee an good user experience. Bosch Software Innovations GmbH 24/25
Chapter 8 Contact us Your feedback helps us to continuously improve the Internet Application Platform and its components. Please send any questions, comments or suggestions for improvement to <iap@bosch-si.com>. Bosch Software Innovations GmbH 25/25