Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This article describes the server side installation of the Smart ID Identity Manager (PRIME) software package.

See here for more information on installation requirements: Identity Manager requirements and interoperability.

Note

If you use Java 11 and the db_update script, read this article: Limitations for Identity Manager.


Expandall

Prerequisites

Expand
titlePrerequisites

The following prerequisites apply:

Install Identity Manager

Expand
titleInstall Java

To install Java on the Identity Manager server:

  1. Download and install Oracle Java JRE (or JDK) according to https://java.com/.
    For information on the supported Java versions, see Identity Manager requirements and interoperability.
    Keep the default installation path, since it is needed again for the Tomcat installation.

    Note

    If you get prompted to remove old Java installations, do not do that until you have installed Identity Manager with the latest Java update, and know that it works.


  2. To set the cryptographic policy of Java, edit the policy settings:

    1. Open the file <java-home>/lib/security/java.security for editing.

    2. Uncomment the following line, to allow use of the included policy files:

      Code Block
      titleExample: crypto.policy
      crypto.policy=unlimited


    3. Save and close the file.

      Note

      Identity Manager default settings require use of the unlimited policy files, to allow Identity Manager to use strong encryption algorithms and key sizes. Due to national regulations in some countries Java is shipped by default with a restricted setup. If the national regulations does not allow to use this policy, the encryption and signing settings in Identity Manager need to be changed.


      Note

      For older Java installations, previous to Java 8 Update 151, the policy files are not included in the default installation. In that case, you must download and install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction policy files, according to: http://www.oracle.com/technetwork/java/javase/downloads/index.html



Expand
titleInstall Tomcat

Install Apache Tomcat on the Identity Manager server:

  1. Download the installation program from Apache Tomcat: http://tomcat.apache.org/.
  2. Start the installation by executing the downloaded .exe file.
  3. Follow the install wizard:
    1. In Choose Components, select installation type Custom. Check Service Startup. Uncheck Start Menu Items, Documentation, Manager, Host Manager, and Examples. Click Next.
    2. In Configuration Options, enter port numbers (required) and a Windows Service Name.

      Note

      You might stick to the Tomcat default ports.

      Always take into consideration the customers infrastructure (for example firewall settings and conflicting third party systems using the same port).

      For guidelines on choosing ports, the IANA (The Internet Assigned Numbers Authority) is a good resource.

      Click Next.

    3. In Java Virtual Machine, browse for the folder where Java Runtime Environment (JRE) is located.

      Note

      The location of the JRE folder determines if Tomcat is started as a 32-bit or 64-bit application, and if the Identity Manager Server is started and operated in 32-bit or 64-bit mode.

      Click Next.

    4. Enter a Destination Folder, for example C:\Program Files\Nexus-PRIME-Tomcat8.
    5. Click Install. The installation is started. Follow the wizard to finish the installation.
Note
titleIBM Websphere

IBM Websphere installation is not described in this instruction. To install IBM Websphere, external integration expertise is needed.



Expand
titleConfigure Tomcat server

To configure the Tomcat server:

  1. Open the configuration file server.xml in the Tomcat folder, for example:
    C:\Program Files (x86)\Apache Software Foundation\Tomcat 8.0\conf\server.xml
  2. Add or update the values in bold:

    Panel
    titleExample: server.xml

    <Connector port="8080" protocol="HTTP/1.1"
    connectionTimeout="60000"
    redirectPort="8443"
    maxPostSize="-1" />


    Note

    The redirectPort="8443" parameter should be used for an SSL configuration, but has no significance for a non-SSL connection (as in this case).

    For more information, see Default ports in Identity Manager


Expand
titleCopy Identity Manager program files

To copy the Identity Manager program files:

  1. Go to applications and connectors in the Identity Manager download area, for example:
    <prime_version>\10_Software\20_Applications_and_Connectors

  2. Copy the following .war files into the webapps subfolder of the Tomcat installation directory:
    - prime_designer.war
    - prime_explorer.war
    - prime_tenant.war
    - ussp.war

  3. Go to tools in the Identity Manager download area, for example:
    <prime_version>\10_Software\20_Tools

  4. Unzip the file db_update.zip.

  5. Copy the following file to the db_update folder of the Identity Manager installation folder, for example:
    - On Windows: <prime_home>\db_update\create_db_with_default_records.bat
    - On Linux: <prime_home>\db_update\create_db_with_default_records.sh


Expand
titleStart up Tomcat

To configure memory settings and start up Tomcat:

  1. Open the Tomcat Properties either via the System Tray, by clicking Configure or via Configure Tomcat in the Apache Tomcat program group in the windows start menu.
  2. Go to the Java tab.
  3. In order to obtain the best possible performance from the Tomcat service, and therefore the Identity Manager applications, enter values for the following parameters. Consider the Notes on memory sizes below when choosing the values:

    ParameterExample valueCorresponding Java option
    Initial Memory pool512 MBXms
    Maximum Memory pool2048 MBXmx
    Thread stack size2048 KBXss


    Note
    titleNotes on memory sizes
    • The Initial Memory pool value can vary significantly depending on the requirements in the projects and the expected load on the Application server. Consider how many background processes are running and how many concurrent users are expected in the Identity Manager clients, as well as how many sub systems will be connected to Identity Manager.
    • The Maximum Memory pool value should be aligned to the available memory on the Server, reserving some memory for OS background processes.
    • Experiences in projects show that a good balance between Xms and Xmx is 1:4. This may also vary according specific project requirements.
    • If you use Java 32-Bit, keep in mind that the Xmx must be less than 1500 MB.
    • If the Tomcat service does not start up, there may not be enough free memory available. In this case, the values must be reduced. Details can also be found in the Tomcat log files.
    • Additional configuration settings are required for Tomcat for certain functions. These are, for example:


  4. Go to the General tab. Verify the information and set Startup type to Automatic. Click Start.
  5. The Tomcat server is started and unzips the .war files into the new folders:
    - prime_designer
    - prime_explorer
    - prime_tenant
    - ussp

    This process usually takes a few minutes.

  6. When the program files have been installed, stop Tomcat again to configure the database connection:
    In the General tab, click Stop.


Expand
titleInitialize database

Identity Manager uses a tool called Liquibase to initialize the database. This allows database changes to be made independently of the underlying database type, therefore making it easy to maintain the database schema for different databases with maximum flexibility.

Note

If you use Java 11 and the db_update script, read this article: Limitations for Identity Manager.


Note

If you use MS SQL as database together with Smart ID Identity Manager (PRIME), the database transaction isolation level must be set to READ_COMMITTED_SNAPSHOT. See Set transaction isolation level for MS SQL when used with Identity Manager


To initialize the database:

  1. Go to the db_update folder of the Identity Manager installation folder, for example:
    <prime_home>\db_update\

  2. Open the following file:
    - On Windows: create_db_with_default_records.bat
    - On Linux: create_db_with_default_records.sh

    Code Block
    languagetext
    titleExample: create_db_with_default_records.bat
    rem set DRIVER=org.postgresql.Driver 
    rem set DB_PREFIX=decode(' 
    rem set DB_POSTFIX=','hex') 
    
    
    rem set DRIVER=com.microsoft.sqlserver.jdbc.SQLServerDriver 
    rem set DB_PREFIX=0x 
    rem set DB_POSTFIX= 
    
    
    rem set DRIVER=oracle.jdbc.OracleDriver 
    rem set DB_PREFIX=hextoraw(' 
    rem set DB_POSTFIX=') 
    
    
    rem set DRIVER=com.ibm.db2.jcc.DB2Driver 
    rem set DB_PREFIX= 
    rem set DB_POSTFIX= 
    
    
    set DRIVER=org.h2.Driver 
    set DB_PREFIX=' 
    set DB_POSTFIX='


  3. Make updates in the file to reflect your database:
    1. Uncomment the three lines for your database type, by removing rem on each line.
    2. Comment out the database types that are not required, by adding rem on each line. For example, comment out the H2 database that is selected by default.

    3. Set the database connection parameters: the JDBC URL of the database server, a user with permissions for schema modifications, and password. For available parameters, see Database properties file.

      Code Block
      languagetext
      titleExample: database connection parameters
      set URL=jdbc:h2:"%~dp0../h2_app/prime";AUTO_SERVER=TRUE;DB_CLOSE_ON_EXIT=FALSE 
      set USER=sa 
      set PASSWORD=


      For more examples, see Examples: database.properties files.

    4. Save the file.

  4. Run the batch file (on Windows) or shell script (on Linux).

    Note

    Note that the computer on which these scripts are run requires access to the database server. If the script is run on the application server, this should not be a problem because the connection is also needed at runtime.


  5. After successful execution, the following message is displayed on the console:
    Liquibase Update Successful


Expand
titleConfigure database connection

Identity Manager supports several database types from different vendors. The standard Identity Manager installation includes an H2 database for demo and testing purposes. For a production system, it is recommended to use another database, since the H2 database is not suitable for productive operation.

The database connection is managed via JDBC. The available functionality includes the relevant JDBC database drivers for the databases that are supported by Identity Manager.

The database type and the connection data have to be configured in the file database.properties, The configuration must be done separately for each Identity Manager client.


Note

In a production environment, different databases are normally used for Identity Manager operator UI and Identity Manager Admin. That means that the different database.properties files contain different configurations.

To configure the database type and connection data:


  1. For Identity Manager Admin (PRIME Designer):
    1. Open this file in a text editor:
      <PathToTomcat>/webapps/prime_designer/WEB-INF/classes/database.properties
    2. Configure the parameters for your database for Identity Manager Admin.
      For more information on the available parameters and examples, see Database properties file.
  2. For Identity Manager operator UI (PRIME Explorer):

    1. Open this file in a text editor:
      <PathToTomcat>/webapps/prime_explorer/WEB-INF/classes/database.properties
    2. Configure the parameters for your database for Identity Manager operator UI.
      For more information on the available parameters and examples, see Database properties file.
  3. For Identity Manager Tenant:

    1. Open this file in a text editor:
      <PathToTomcat>/webapps/prime_tenant/WEB-INF/classes/database.properties
    2. Configure the parameters for your database for Identity Manager Tenant.
      For more information on the available parameters and examples, see Database properties file.
  4. Restart Tomcat to establish the database connection. 


Expand
titleCreate start commands to Identity Manager clients

To create start commands to the Identity Manager clients:

  1. To create a link to Identity Manager operator UI, Identity Manager Tenant, and Smart ID Self-Service, edit the host name and, if needed, the port number in the default URLs to match your environment. The resulting link can be called in a browser.

    The default URLs are the following. For Identity Manager operator UI and Identity Manager Tenant, a corresponding file index.html is part of each .WAR file:
    • Identity Manager operator UI:

      Code Block
      languagetext
      titleDefault URL to Identity Manager operator UI
      https://<PRIMEHOSTNAME>:8443/prime_explorer/


    • Identity Manager Admin:

      Code Block
      languagetext
      titleDefault URL to Identity Manager Admin
      https://<PRIMEHOSTNAME>:8443/prime_designer/


    • Identity Manager Tenant:

      Code Block
      languagetext
      titleDefault URL to Identity Manager Tenant
      https://<PRIMEHOSTNAME>:8443/prime_tenant/


    • Smart ID Self-Service:

      Code Block
      languagetext
      titleDefault URL to Smart ID Self-Service
      https://<PRIMEHOSTNAME>:8443/ussp/


      Note
      If you want to do chip encoding in Smart ID Self-Service, for example to renew certificates, ensure that the JRE is enabled in the Browser.


    where <PRIMEHOSTNAME> is the respective server name or the IP address of the server on which the Identity Manager application is installed.
  2. If no tenant selection dialog should be displayed, add the parameters tenantId and language in the application URLs:


    Code Block
    titleExample: tenantId and language
    https://<PRIMEHOSTNAME>:8443/prime_explorer/jsp.mainframe.risc?ccstyle=act3_risc&tenantId=<tenantId>&language=<language>

    where <tenantId> is replaced by for example 1, 2, or 3 and <language> is replaced by en, de, sv, fr, and so on.


Expand
titleInitial configuration

Go on to do Initial configuration of Identity Manager.

See also Identity Manager installation and upgrade for more configuration steps.


Anchor
databasePropertiesFile
databasePropertiesFile
Database properties file

Expand
titleDatabase properties


Parameter nameParameter value
dataSourceType

Type or manufacturer of database.
Permitted values:

  • H2 - File based H2 database for development and demo purposes. (not suitable for productive operation)
  • MS - Microsoft SQL Server 2008/2012/2014 Database
  • ORA - Oracle 10/11/12 Database
  • PG - PostgreSQL Database
  • DB2 - IBM DB2 Database
dataSourceType.jdbcURL

Complete JDBC URL for the respective database. This is different depending on the type of database and has the following basic structure:

  • For H2 database with multi-user access option:
    jdbc:h2:<Path_to_DB>/<DB_Name>;AUTO_SERVER=TRUE

  • For MS SQL server with standard instance:
    jdbc:sqlserver://<DBHostname_or_IP>:<DBServer_Port>;DatabaseName=<DB_Name>

  • For MS SQL server with named instance:
    jdbc:sqlserver://<DBHostame_or_IP>\<Instance_Name>;DatabaseName=<DB_Name>

  • For Oracle database:
    jdbc:oracle:thin:<DBHostname_or_IP>:<DBServer_Port>:<DB_Name>

  • For PostgreSQL database:
    jdbc:postgresql://<DBHostname_or_IP>:<DBServer_Port>/<DB_Name>

  • For DB2 database:
    jdbc:db2://<DBHostname_or_IP>:<DBServer_Port>/<DB_Name>


DB typeDescription

<Path_to_DB>

Relative or absolute folder path to the database (only with H2)


<DBHostname_or_IP>Name or IP address of database server

<Instance_Name>Instance name of database installation (only with MS SQL server)

<DBServer_Port>

Port number of database server. The port numbers are usually allocated automatically or manually during the installation of the respective database.

The standard port numbers of the respective databases are:

  • for sqlserver: 1433
  • for oracle: 1521
  • for postgresql: 5432
  • for db2: 50000

<DB_Name>Actual name of database
dataSourceType.userUser name for logging into database
dataSourceType.passwordPassword for logging into database
quartzDriverDelegateClassQuartz Scheduler needs his own DB connection. Select the JDBC-driver her for Quartz


Anchor
ExampleDatabasePropertiesFiles
ExampleDatabasePropertiesFiles
Examples: database.properties files

Expand
titleH2 example

This example describes the database named prime, stored in the folder h2_application in the Identity Manager installation folder.

Code Block
languagetext
titleH2 example
dataSourceType=H2 
dataSource.jdbcUrl=jdbc:h2:h2_application/prime;AUTO_SERVER=TRUE 
dataSource.user=sa 
dataSource.password= 

quartzDriverDelegateClass = org.quartz.impl.jdbcjobstore.StdJDBCDelegate



Expand
titleMS SQL server example: standard instance


Code Block
languagetext
titleMS SQL standard instance example
dataSourceType=MS 
dataSource.jdbcUrl=jdbc:sqlserver://NexusDBServer:1433;DatabaseName=PRIME 
dataSource.user=Nexus 
dataSource.password=Secret 

quartzDriverDelegateClass = org.quartz.impl.jdbcjobstore.MSSQLDelegate



Expand
titleMS SQL server example: named instance


Code Block
languagetext
titleMS SQL named instance example
dataSourceType=MS 
dataSource.jdbcUrl=jdbc:sqlserver//NexusDBServer\ACCESS;DatabaseName=PRIME 
dataSource.user=Nexus 
dataSource.password=Secret 


quartzDriverDelegateClass = org.quartz.impl.jdbcjobstore.MSSQLDelegate



Expand
titleOracle example


Code Block
languagetext
titleOracle example
dataSourceType=ORA 
dataSource.jdbcUrl=jdbc:oracle:thin:@//NexusDBServer:1521/PRIME 
dataSource.user=Nexus 
dataSource.password=Secret 


quartzDriverDelegateClass = org.quartz.impl.jdbcjobstore.oracle.OracleDelegate



Expand
titlePostgreSQL example


Code Block
languagetext
titlePostgreSQL example
dataSourceType=PG 
dataSource.jdbcUrl=jdbc:postgresql://NexusDBServer:5432/PRIME 
dataSource.user=Nexus 
dataSource.password=Secret 


quartzDriverDelegateClass = org.quartz.impl.jdbcjobstore.PostgreSQLDelegate



Expand
titleDB2 example


Code Block
languagetext
titleDB2 example
dataSourceType=DB2 
dataSource.jdbcUrl=jdbc:db2://NexusDBServer:50000/PRIME 
dataSource.user=Nexus 
dataSource.password=Secret 


quartzDriverDelegateClass = org.quartz.impl.jdbcjobstore.DB2v8Delegate