Identity Management Administrator Guide

(1)

Common Environment - Identity Management component

Identity Management – Administrator Guide

Version 3.2.2

Bosch Software Innovations

Americas:

Bosch Software Innovations Corp. 161 N. Clark Street

Suite 3550

Chicago, Illinois 60601/USA Tel. +1 312 368-2500

Asia:

Bosch Software Innovations c/o Robert Bosch (SEA) Pte Ltd 11 Bishan Street 21

Singapore 573943 Tel. +65 6571 2220

Europe:

Bosch Software Innovations GmbH Schöneberger Ufer 89-91

10785 Berlin / GERMANY Tel. +49 30 726112-0 Fax +49 30 726112-100

(2)

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.

(3)

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 IT-specialists. 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 user-administration 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

(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:

3.2.2

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

(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.homewhich 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.

(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 Apache Tomcat Deployment o JBoss Deployment

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

Admin User Name com.bosch.im.init.user.admin.name Admin The name of the default administration user for the default 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.)

(9)

Attribute Configuration property Default value Description Application

Installer Role 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.) 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.

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 im-backend.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

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

(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 = [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.

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

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

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

4.3.1 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: http://host:port/IM/.

For example, if Tomcat is running on your local machine and is using its default port configuration then the URL is: http://localhost:8080/IM/

( In case you are using the M2M SDK Tomcat is configured on port 8088, thus you could for example check the availability at http://localhost:8088/IM/)

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

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

<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

(13)

deployment of IM. This can be configured in JBOSS_HOME/standalone/configuration/standalone.xml. The following example increases the timeout to 120 seconds.

...

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

(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 http://<websphere-host>:<port>/<websphere-im-name>/1/rest. 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.

(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-3.2.0 will result in a file path im-ui-webapp-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 http://localhost:8088/IM 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,

users, groups, roles, permissions, domains, applications, offerings and tenant relations as a table per type of entity.

Changing the default value to false will hide the according table. usersVisible true groupsVisible true rolesVisible true permissionsVisible true domainsVisible true applicationsVisible true offeringsVisible true tenantRelationsVisible true

tenantsCollapsed true The user interface displays all existing tenants,

users, groups, roles, permissions, domains, applications, offerings and tenant relations as a table per type of entity.

After a successful login, a user can collapse or expand each of the tables visible.

However, the value defined for these properties will influence the first appearance of the tables

(collapsed or expanded) at each login for all users.

usersCollapsed false groupsCollapsed false rolesCollapsed false permissionsCollapsed true domainsCollapsed true applicationsCollapsed true 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.

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

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

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

(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 Configuring an Identity Provider for a Tenant

o 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

(18)

5.2 External Identity Provider

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

required

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

• SECONDS

• MINUTES

• HOURS

• DAYS

optional MINUTES

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

optional no tenant

5.3 LDAP/AD Specific Configuration

Attribute Description Use Default _value

url The URL of the LDAP server connection.

Restriction: ldap://.+ required

managerDN Used only with "search" authentication method. It is the DN of the

user who will bind to the LDAP server to perform the search required managerPW Used only with "search" authentication method. It is the password

of the user who will bind to the LDAP server to perform the search required 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

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.

required

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 +

(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

EMAIL 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="http://www.bosch.com/IAP/imExternalIdentityProviderConfig1_0_0" xmlns:ldap="http://www.bosch.com/IAP/imExternalIdentityProviderLdapConfig1_0_0">

<ldap:ldap url="ldap://localhost:450" managerDN="admin" managerPW="admin" userSearchBase="DC=ad,DC=local" userSearchFilter="(objectClass=user)"

subtreeSearch="true" usernameAttributeId="sAMAccountName">  <ldap:attributemapping>

<ldap:userattributes>

<ldap:userattribute to="FIRSTNAME" from="firstName" /> <ldap:userattribute to="LASTNAME" from="sn" />

<ldap:userattribute to="EMAIL" 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.

(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 Server: im-backend-<date>.log

o 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 http://logback.qos.ch/manual/index.html

Example 1

Example 2

<root level="DEBUG">

<appender-ref ref="FILE" /> </root>

</included>

(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 im-backend.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.

(This might be different than the user's tenant in case of acting on behalf of another tenant.)

max. 36 characters

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

authenticate) max. 36 characters

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

the action max. 36 characters

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

Actions) max. 255 characters 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-hand-side (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)

(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

property belongs, set by IM automatically. max. 36 characters

PROPERTY_NAME The name of the property. max. 255 characters

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

max. 36 characters

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

(23)

Name Description Restrictions PROPERTY_LARGE_VALUE The value of the property. This field can be empty, and is

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

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

(24)

Chapter 8 – IM Glossary

Application /

Application Instance An application is a logical instance (e.g. business application) that defines permissions and roles and uses the IM authentication and authorization services. Applicable scope 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).

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

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 unit that defines a realm of administrative autonomy, authority, or control within IM.

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

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

Instance See Application

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

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.

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

Scope see Applicable scope

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

Tenant Relation Entity 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

(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 <www.bosch-si.com> 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).

Identity Management Administrator Guide

Common Environment - Identity Management component