Identity Management Administrator Guide

Transcription

1 IMS Developer Guide Common Environment - Identity Management component Identity Management Administrator Guide Version Bosch Software Innovations Americas: Bosch Software Innovations Corp. 161 N. Clark Street Suite 3550 Chicago, Illinois 60601/USA Tel info@bosch-si.com Asia: Bosch Software Innovations c/o Robert Bosch (SEA) Pte Ltd 11 Bishan Street 21 Singapore Tel info-sg@bosch-si.com Europe: Bosch Software Innovations GmbH Schöneberger Ufer Berlin / GERMANY Tel Fax info-de@bosch-si.com Bosch Software Innovations GmbH 1/25

2 Copyright Notice Bosch Software Innovations GmbH, 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

3 Table of Contents Chapter 1 About this guide Identity Management Target audience Getting started Schematic view of an Identity Management installation... 5 Chapter 2 Get artifacts... 6 Chapter 3 Configuring IM_HOME... 7 Default IM_HOME directory... 7 Explicit configuration of IM_HOME... 7 Chapter 4 Installation and first configuration Configuring IM server initialization parameters Configuring the data source DBMS support Sort order on DBMS How to support full Unicode Deploy the IM server Apache Tomcat Deployment JBoss Deployment Data Source configuration jboss-web.xml jboss-deployment-structure.xml Timeout for deployment WebSphere Deployment Configuring the WebSphere Application Server Preparing the Environment Deploying the IM Server Known pitfalls Configuring the IM user interface Web application Deploy the IM user interface Web application Accessing the IM server using SSL Using the IM user interface Chapter 5 External User Management (Visual Rules version) Configuring the connection to an external identity provider (LDAP Active Directory) External Identity Provider LDAP/AD Specific Configuration Attribute Mapping Example Further Notes Bosch Software Innovations GmbH 3/25

4 Chapter 6 Logging Logging configuration Example: Adjusting the logging configuration for IM Server Chapter 7 Audit Logging Configuration Audit Entries Actions Audit Properties Chapter 8 IM Glossary Chapter 9 Contact us Bosch Software Innovations GmbH 4/25

5 Chapter 1 About this guide 1.1 Identity Management The Bosch Software Innovations Identity Management (IM) component provides services to other systems which they can use to administrate their usage policy: user authentication and authorization. The main scope of IM integration 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, that can be restructured without the need of involving the ITspecialists. The user permissions are not derived from their membership of a group or tenant, 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 reduces the source of errors while administration on one side and consequently the costs for a secure useradministration on the other. 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 IM Specification. 1.4 Schematic view of an Identity Management installation Following figure depicts how an Identity Management installation could look like. Bosch Software Innovations GmbH 5/25

6 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: 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 o im-backend.properties - for the IM server im-webui.properties - for the user interface Bosch Software Innovations GmbH 6/25

7 Chapter 3 Configuring IM_HOME IM uses the IM_HOME directory for several purposes: Configuring IM server initialization Configuring the connection to an external identity provider Logging Default IM_HOME directory By default - i.e. if you don't explicitly specify another directory - the following directory is used as IM_HOME directory: [user.home]/identitymanagement The [user.home] placeholder is resolved to the Java system property user.home which depends on your operating system and Java installation. On a Windows system the path would be for example: C:\Users\<user>\identitymanagement Explicit configuration of IM_HOME The IM_HOME directory can be explicitly configured by means of Java system property IM_HOME. Most installations will not configure IM_HOME explicitly. Configuring IM_HOME is necessary when IM is run by a user who does not have a user home directory. For example, while using Tomcat as a Windows Service, the service user does not have a user home directory. After changing the IM_HOME directory, both the IM server and the IM user interface Web application have to be restarted. Bosch Software Innovations GmbH 7/25

8 Chapter 4 Installation and first configuration 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 o o Apache Tomcat Deployment JBoss Deployment WebSphere Deployment Configuring the IM user interface Web application Deploy the IM user interface Web application Using the IM user interface 4.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. Following table describes the default values and their meaning. Attribute Configuration property Default value Description Tenant Name com.bosch.im.init.tenant.name DEFAULT The name of the default tenant. Domain Name com.bosch.im.init.domain.name IAP The name of the default domain assigned to the default tenant. Application Instance Name com.bosch.im.init.instance.name IM The name of the default instance assigned to the default domain. The name of the default administration user for the default tenant and all entities assigned to this tenant. 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 User Name com.bosch.im.init.user.admin.name Admin Admin User Password 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.) Bosch Software Innovations GmbH 8/25

9 Attribute Configuration property Default value Description Application Installer Role Max. server-side sessions com.bosch.im.init.role.app.name ApplicationInstaller 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.) com.bosch.im.init.session.max 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. Audit Logging com.bosch.im.audit.active true Audit logging activation See section Audit Logging for details. In order to change these initialization parameters, the IM server expects a properties file named imbackend.properties at following path: [IM_HOME]/im-backend.properties See Configuring IM_HOME for details on how the [IM_HOME] placeholder is resolved. Changing the values in the property file after the initialization of the IM server has no effect (unless the database is reinitialized). The only exceptions are the properties used for the session timeout configuration which will be applied when the IM server is restarted. If you started with the Visual Rules assembly 1. Copy the identitymanagement folder of the visualrules-im-assembly to your IM Home directory 2. 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. There we customized for example the default domain name. Deviating from the default setting shown in the table before, Visual Rules customers would have for example "IM" as their default domain name. 4.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 IM Specification. It expects that the runtime container provides a data source with the name jdbc/im-ds and the type javax.sql.datasource Bosch Software Innovations GmbH 9/25

10 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 = [ ( )] 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 INFO com.googlecode.flyway.core.migration.dbmigrator - Migrating to version INFO com.googlecode.flyway.core.migration.dbmigrator - Migrating to version INFO com.googlecode.flyway.core.migration.dbmigrator - Migrating to version INFO com.googlecode.flyway.core.migration.dbmigrator - Migrating to version 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: INFO com.googlecode.flyway.core.migration.dbmigrator - Schema is up to date. No migration necessary 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. 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 Oracle 11g Set System Property for Oracle JDBC driver oracle.jdbc.defaultnchar=true Bosch Software Innovations GmbH 10/25

11 4.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 (see Configuring IM_HOME). 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 Apache Tomcat Deployment At the time of writing there are no issues known on integrating the IM server with the Apache Tomcat application server. 1. Optionally, you can rename the.war file (e.g. rename im-server-<version>.war into IM.war) to simplify the URL where the IM server will be available. 2. Simply copy the IM.war file in the <TOMCAT_INSTALL>\webapps\ folder. The placeholder <TOMCAT_INSTALL> stands for the fully qualified path where Tomcat was installed. Tomcat is now ready to deploy the IM server. 3. Start Tomcat (if not already started). The application server will automatically unpack the archive and start the IM server. 4. The URL for the running IM server is constructed as follows: For example, if Tomcat is running on your local machine and is using its default port configuration then the URL is: ( In case you are using the M2M SDK Tomcat is configured on port 8088, thus you could for example check the availability at 5. However, please keep in mind to adjust accordingly the value of the imserverurl property, to assure the binding between IM server and IM user interface Web application. (See <userhome>/identitymanagement/im-webui.properties and description at Configuring the IM user interface Web application.) When running Tomcat as a Windows service, the service user does not have a user.home. Therefore, you need to configure IM_HOME explicitly. To see if the setting is used by the IM server, watch the stdout of Tomcat, it will print out the absolute filename of the logback configuration files: e.g.2013-mm-dd 18:33:54 Commons Daemon procrun stdout initialized D:\Products\identitymanagement\im-backend-logback-included.xml D:\Products\identitymanagement\im-webui-logback-included.xml Bosch Software Innovations GmbH 11/25

12 4.3.2 JBoss Deployment In order to deploy IM on JBoss AS 7, the following things have to be considered. Data Source configuration jboss-web.xml jboss-deployment-structure.xml Timeout for deployment 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"> <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. 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> Timeout for deployment JBoss has a default timeout of 60 seconds for the deployment of applications. Depending on your hardware, connection to your database, number of database migration steps etc. this timeout needs to be increased for the Bosch Software Innovations GmbH 12/25

13 deployment of IM. This can be configured in JBOSS_HOME/standalone/configuration/standalone.xml. The following example increases the timeout to 120 seconds.... <subsystem xmlns="urn:jboss:domain:deployment-scanner:1.0"> <deployment-scanner scan-interval="5000" relative-to="jboss.server.base.dir" path="deployments" deployment-timeout="120" /> </subsystem>... To determine if the timeout of your JBoss installation is to low you can have a look at the log files. The following error message appears in the log file when a deployment exceeds the deployment. JBAS015052: Did not receive a response to the deployment operation within the allowed timeout period [60 seconds]. Check the server configuration file and the server logs to find more about the status of the deployment. Bosch Software Innovations GmbH 13/25

14 4.3.3 WebSphere Deployment IM server can be deployed on a WebSphere Application Server 8.5. The following description assumes, the application sever was stared already. Configuring the WebSphere Application Server Preparing the Environment Deploying the IM Server Known pitfalls Configuring the WebSphere Application Server The WebSphere server has to be configured to run with Java 7 since this is the currently supported version for IM. Information on how to achieve this can be found in the IBM Infocenter for WebSphere Application Server 8.5. Find your current configuration in the admin console by navigating to Servers > Server Types > WebSphere application servers. In the list of servers click the one you want to configure and find the link to "Java SDKs". Preparing the Environment For the IM Server a username/password, a JDBC driver and data source have to be provided. Follow these steps to get your environment ready: 1. Add a new user/password set for the data source: a. Open Security > Global security. b. In the "Authentication" group box click the "Java Authentication and Authorization Service" link. c. A list opens which reveals "J2C authentication data". Follow this link and add new credentials for your data source. 2. Add a new driver in the WebSphere Admin Console a. Open Resources > JDBC > JDBC Providers. b. Add a new appropriate driver for your data source. 3. Configure the data source: a. Open Resources > JDBC > Data sources. b. Add the connection info for your new data source. Deploying the IM Server Open the WebSphere Admin Console to deploy the IM Server: 1. Open Applications > New Application > New Enterprise Application. 2. Select the IM server war file to be installed 3. Complete the deployment procedure. 4. Restart the WebSphere Application Server Known pitfalls IM Server REST API: To request the IM Root Resource (Index) don't add a trailing slash ('/') in the URI as WebSphere does not support this and will return an Error 404: Not Found. For a valid request use something like: GET The result should be a list of links to the root services of the IM API This does not apply for requests on all other IM REST resources. HTTPRequest Parameter with no value: WebSphere treats getrequestparameter(string name) differently if using a value-less GET parameter, i.e. it returns null, while other app servers return an empty string. Bosch Software Innovations GmbH 14/25

15 4.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 IM_HOME directory: 1. If you have only one IM user interface running [IM_HOME]/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 [IM_HOME]/[context-path]/im-webui.properties Whereby [context-path] is derived from the path, the user interface is reachable at, from the application server's point-of-view. All characters other than letters, numbers, - or _ are removed from the actual path. Example: The web application context-path im-ui-webapp will result in a file path im-uiwebapp-320 to be used for resolving the configuration file. To identify the actual file path used in your installation, start the deployed IM user interface Web application and have a look at the beginning of the log file. Within the properties file you can overwrite the default values of the properties described in the following: Configuration Property Default value Description imserverurl URL where you have deployed the IM server. Double check this property setting, as connecting to the IM server is essential. 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 true The user interface displays all existing tenants, usersvisible true users, groups, roles, permissions, domains, applications, offerings and tenant relations as a groupsvisible true table per type of entity. rolesvisible true Changing the default value to false will hide the permissionsvisible true according table. domainsvisible true applicationsvisible true offeringsvisible true tenantrelationsvisible true tenantscollapsed true The user interface displays all existing tenants, userscollapsed false users, groups, roles, permissions, domains, applications, offerings and tenant relations as a groupscollapsed false table per type of entity. rolescollapsed false After a successful login, a user can collapse or permissionscollapsed true expand each of the tables visible. domainscollapsed true However, the value defined for these properties will influence the first appearance of the tables applicationscollapsed true (collapsed or expanded) at each login for all users. offeringscollapsed true tenantrelationscollapsed 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. Bosch Software Innovations GmbH 15/25

16 4.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.war into your application server. Also make sure that there is a home directory set (see Configuring IM_HOME). For the case you need to deploy and configure multiple UIs, at this point you must define a context path for each Web application inside the application server. As mentioned in the section before, the properties file for one of the Web applications is to be stored in the according folder [context-path] as well 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. 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. 4.6 Using the IM user interface Open your browser at the URL of your application server (e.g. for Tomcat 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 Admin / Admin / DEFAULT. 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 your own password our IM User Guide at Change your own password, and for changing another user's settings at Update User. After a successful login you should see the initial screen, similar to following figure 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 16/25

17 Chapter 5 External User Management (Visual Rules version) 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 in the section beneath. 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 5.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 location specified by IM_HOME: ${IM_HOME}/<filename> If IM_HOME is not explicitly configured, this would be on a windows system: 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 17/25

18 5.2 External Identity Provider Attribute type name tenant syncinterval synctimeunit reftenant Description Use Default value 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. The (within IM) unique name used to identify this external identity provider. The name of the tenant which owns/manages this 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 owner please use the IM user interface or the IM RESTful API 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. The time unit of the interval to synchronize (see "syncinterval"). SECONDS MINUTES HOURS DAYS 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 required required required required optional optional MINUTES no tenant 5.3 LDAP/AD Specific Configuration Attribute Description Use Default value url The URL of the LDAP server connection. required Restriction: ldap://.+ managerdn Used only with "search" authentication method. It is the DN of the required user who will bind to the LDAP server to perform the search managerpw Used only with "search" authentication method. It is the password required of the user who will bind to the LDAP server to perform the search usersearchbase Context name to search in, relative to the base DN in the ldapurl required usersearchfilter A filter expression used to search for the user DN that will be used required 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. required Example: AD: samaccountname / LDAP: uid subtreesearch Flag to enable deep search through the sub tree of the ldapurl + searchbase. optional true Bosch Software Innovations GmbH 18/25

19 5.3.1 Attribute Mapping IM allows to fill IM attributes by synchronizing them from an LDAP/AD server. IM attributes can be mapped to arbitrary LDAP attributes. The following tables shows the available IM attributes and for each an example for a mapped LDAP attribute. IM attribute Use Example for LDAP attribute FIRSTNAME optional firstname LASTNAME optional sn optional mail 5.4 Example Following file com.bosch.im.externalidentityproviders.xml configures the connection to an LDAP server <?xml version="1.0" encoding="utf-8"?> <externalidentityproviders xmlns=" xmlns:ldap=" <!-- 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:userattribute to=" " from="mail" /> </ldap:userattributes> </ldap:attributemapping> </ldap:ldap> </externalidentityprovider> </externalidentityproviders> 5.5 Further Notes 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 19/25

20 Chapter 6 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. 6.1 Logging configuration The logging configuration files are located at the IM home directory: Server: [IM_HOME]/im-backend-logback-included.xml User interface Web application: [IM_HOME]/im-webui-logback-included.xml By default, logging is configured as follows: Log level: INFO Directory where the log files are stored: [IM_HOME]/logs Log file names: o o Server: im-backend-<date>.log User interface Web application: im-webui-<date>.log See Configuring IM_HOME for details on how the [IM_HOME] placeholder is resolved. 6.2 Example: Adjusting the logging configuration for IM Server 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: [IM_HOME]/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 Example 1 <included> <!-- increase log level to DEBUG --> <logger name="com.bosch.im" level="debug" /> </included> Example 2 <included> <!-- increase log level of root logger to DEBUG --> <root level="debug"> <appender-ref ref="file" /> </root> </included> 3. Changes to the log configuration are applied automatically, without the need to restart the server. Bosch Software Innovations GmbH 20/25

21 Chapter 7 Audit Logging Starting with IM version 3.2, the functionality for audit logging was introduced. The functionality logs predefined actions into the IM database, more precisely in a new table called "IDM90_AUDIT_ENTRY". These log entries enable administrative users to persistently store all main occurrences on the IM system (i.e. all actions performed by registered users e.g. via the user interface, and by authenticated technical users e.g. via REST requests) Thus your company gets a reliable record on IM activities. Configuration Audit Entries Actions Audit Properties 7.1 Configuration Audit logging is by default enabled. However, while setting up the system you can configure whether audit logging should be active (true) or not (false). An according configuration property com.bosch.im.audit.active will appear within the imbackend.properties file /see section Get artifacts for the Visual Rules assembly) Changing one of the values within this configuration file requires a system restart in order to be applied. 7.2 Audit Entries The audit entry table contains the following records: Name Description Restrictions AUDIT_ENTRY_ID Primary key for this table, set by IM automatically. max. 36 characters AFFECTED_TENANT_ID Technical ID of the tenant the record refers to. max. 36 characters (This might be different than the user's tenant in case of acting on behalf of another tenant.) TIME_STAMP Server time, when the record was generated yyyy-mm-dd hh:mm:ss.sss USER_ID Technical ID of the authenticated user (or user trying to max. 36 characters authenticate) USER_TENANT_ID Technical ID of the acting user's tenant max. 36 characters INSTANCE_ID Technical ID of the application instance used to perform max. 36 characters the action INSTANCE_TYPE Name of the affected application (e.g. "IM") max. 255 characters OPERATION Name of the operation executed (See details in the list of max. 255 characters Actions) ENTITY_ID Technical ID of the entity affected (e.g. ID of the newly created entity). In case of relations between two entities the left-handside (i.e. the entity to which we are assigning) will be used here. The ID of the right-hand-side entity (i.e. the entity that is being assigned) will be logged in the properties table. (See details in the list of Audit Properties) max. 36 characters Bosch Software Innovations GmbH 21/25

22 Name Description Restrictions ENTITY_TYPE Type of the entity affected (e.g. User, Tenant, Domain, etc.). In case of assignments, the type of the left-hand-side entity (i.e. the entity to which we are assigning) will be used. The type of the right-hand-side entity (i.e. the entity that is being assigned) will be logged in the properties table. (See details in the list of Audit Properties) max. 255 characters Example A common audit entry log looks like following: 7.3 Actions Currently IM audit logs the following events: create entity update entity delete entity restore entity erase entity assign relation (i.e. create assignment) remove relation (i.e. remove assignment) create user attribute update user attribute delete user attribute user login success user login failure api key login success api key login failure 7.4 Audit Properties The audit properties table contains the following records: Name Description Restrictions AUDIT_PROPERTY_ID Primary key for this table, set by IM automatically. max. 36 characters AUDIT_ENTRY_ID Primary key of the audit entry record to which this audit max. 36 characters property belongs, set by IM automatically. PROPERTY_NAME The name of the property. max. 255 characters PROPERTY_ID PROPERTY_VALUE The value of the property. This field can be empty, and is used only in cases when the value is the ID of another entity, e.g., the ID of the right-hand-side entity in a relation. When PROPERTY_ID is set, PROPERTY_VALUE and PROPERTY_LARGE_VALUE will be empty. The value of the property. This field can be empty, and is used in most common scenarios. When PROPERTY_VALUE is set, PROPERTY_ID and PROPERTY_LARGE_VALUE will be empty. max. 36 characters max. 255 characters Bosch Software Innovations GmbH 22/25

23 Name Description Restrictions PROPERTY_LARGE_VALUE The value of the property. This field can be empty, and is CLOB used only in scenarios when the value is too large for PROPERTY_VALUE field (e.g., BaseConfiguration values). When PROPERTY_LARGE_VALUE is set, PROPERTY_ID and PROPERTY_VALUE will be empty. Example The following example assumes a log for a user creation. In that case The audit entry table would log an entry recording the action itself While the additional user specific records would be stored separately in the audit properties table Bosch Software Innovations GmbH 23/25

24 Chapter 8 IM Glossary Application / Application Instance Applicable scope Authentication Authorization Domain Entity Group Instance Offering Operation Permissions An application is a logical instance (e.g. business application) that defines permissions and roles and uses the IM authentication and authorization services. Depending on the applicable scope of an offering, the consuming tenant is allowed to use these on his data (scope is CONSUMER) or on the data of the offering tenant (scope is PROVIDER). A user is authenticated after a successful login, as the existence of the username and the corresponding valid password are found in the IM database. A user is authorized for an operation if the appropriate permission is assigned to the user in the IM database. A domain is an infrastructure unit that defines a realm of administrative autonomy, authority, or control within IM. A unit that contains or receives information. In case of IM the User, Group, Role, Tenant, Permission etc. are regarded as entities/units. Furthermore the operations these units can execute may refer as well to entities of the custom application. A group is regarded as a unit 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. See Application An offering is a set of roles and permissions offered by one tenant to another one. Thus the permissions can be spread outside the boundaries of a tenant. An operation is an executable image of the program, which upon invocation executes some function for the user. A permission assigned to a user (by assigning a role) grants the approval for this user to perform an operation. Relation / Assignment A relation is created when assigning units to one another. E.g. a user can be assigned to a group or a role, thus getting related to that unit. Role Scope Tenant Tenant Relation User 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 (or group of users) assigned to that role. see Applicable scope A tenant is a legal organizational unit which is mostly representative of a company. (Previous IM versions used the term Client instead.) As only one tenant can be active at once, on user login the Identity Management can assign different permission to the same user based on the tenant the user has been logged in. Entity used to assign an offering to another tenant. A user is a human being, a machine, network etc. subscribing to use a part of an application. Bosch Software Innovations GmbH 24/25

25 Chapter 9 Contact us Your feedback helps us to continuously improve our products and components. Find further information about M2M Device Management online at < and don t hesitate to send us your questions, comments or suggestions for improvement. About Bosch Software Innovations Bosch Software Innovations GmbH, the Bosch Group s software and systems house, designs, develops, and operates innovative software and system solutions that help our customers around the world both in the traditional enterprise environment and in the Internet of Things and Services. We place particular focus in this field on the topics of mobility, energy and building, manufacturing, and financial services. Whether in its special, targeted BPM+ and IoTS editions or as flexible standalone products, our software suite is the perfect foundation not only for projects relating to the Internet of Things and Services but also for projects in the fields of Business Process Management (BPM) and Business Rules Management (BRM). With some 550 associates worldwide, Bosch Software Innovations has locations in Germany (Immenstaad, Waiblingen, and Berlin), Singapore, China (Shanghai), Australia (Melbourne), and the United States (Chicago, Palo Alto, and Vienna). More information can be found at < Bosch Software Innovations GmbH 25/25