Follow the steps in order. Issue all commands in Windows command prompt using the Administrator user account.

Perform on CustomerID server (or relating to it):

1. Back up Ubisecure Directory. See instructions from Backup And Restore - Ubisecure Directory.
2. Unpack the distribution package. See instructions from CustomerID Distribution Package Unpacking In Windows.
3. Check Java. See instructions from CustomerID Java Check In Windows.
4. Install WildFly. See instructions from CustomerID WildFly Installation In Windows.
5. Extract the deployment template. See instructions from CustomerID Deployment Template Extraction In Windows.
6. Edit the setup template and run setup. See instructions from CustomerID Setup Template In Windows.

Configuring WildFly

This chapter will configure WildFly to use HTTP and HTTPS ports defined in win32.config.

Creating the Certificate Key Store for SSL

If you have a production-ready SSL certificate, it is easiest to store it in a keystore.pfx file that is saved in %WILDFLY_HOME%\standalone\configuration\keystore.pfx. If you don't have a production ready server certificate, then you can either create a temporary self-signed one using cert.cmd, to get you started with testing, or buy a production certificate from, for example: https://www.globalsign.com/en/ssl/.
The script cert.cmd will generate a self-signed certificate and deposit it in a key store file called keystore.pfx. This file is saved in %WILDFLY_HOME%\standalone\configuration\keystore.pfx. 

cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools"
cert.cmd

Successful execution will return Creating localhost keystore %WILDFLY_HOME%\standalone\configuration\keystore.pfx

If you are using self-signed certificates (like the one provided by default in the installation of Ubisecure SSO) also with Ubisecure SSO you need to import the public key into the Java certificate store (%JRE_HOME%\lib\security\cacerts file).

Modifying WildFly Service

To change the WildFly service starting type to automatic from the default setting manual run config-wildfly-service.cmd. 

cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools"
config-wildfly-service.cmd

Succesful execution will show [SC] ChangeServiceConfig SUCCESS

Configure WildFly File Permissions

Add LOCAL SERVICE account to WildFly home folder. Modify file permissions for the folder %PROGRAMFILES%\wildfly-x.x.x.Final. Give full control to the LOCAL SERVICE account.

This can be done via the command line

icacls %PROGRAMFILES%\wildfly-x.x.x.Final /grant "LOCAL SERVICE:(OI)(CI)(F)"

Successful execution will show Successfully processed 1 files; Failed processing 0 files

And verified in the GUI

Applying WildFly Configuration Changes

The command config-wildfly.cmd will relocate HTTP and HTTPS ports according to configuration that was specified in win32.config and set up the references to the key store containing the server certificate. It will also set host aliases. Make sure that all phases finish with a success status.

cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools"
config-wildfly.cmd

Successful execution will return many output lines with each set of lines containing the response "outcome" => "success".

Verifying WildFly SSL Configuration

Open a browser to the server's HTTPS port and verify that the connection is over HTTPS and check that the certificate information is what you would expect under the circumstances. At this point in the installation, no applications have been deployed, however a 404 Page not found error message should be delivered over a TLS connection (HTTPS).

Try accessing the URL: https://<eidm.url>/eidm2/xxx

eidm.url can be found from: %PROGRAMFILES%\Ubisecure\customerid\application\win32.config

If you are using a CA-issued SSL server certificate no browser trust warnings should be displayed. If you are using a self-signed certificate will show browser warnings unless explicitly trusted.

In production systems, a proxy must be used between the CustomerID application server and the user. SSL certificate configuration at the proxy is done according to the proxy vendor product instructions.

Additional SSL Considerations

Ubisecure CustomerID can be configured to make calls to third-party software during the user registration workflows. Typically data entered by the user is verified against a CRM or other backend service to determine which access rights a user should be automatically given based on an existing service agreement.

If you plan to use back channel connections from Ubisecure CustomerID over SSL encrypted connections, you will have to add each server's public key to the Server JRE's cacerts file: %JRE_HOME%\lib\security\cacerts. Once you have downloaded the server's public key, you can add it to the key store with the following commands:

cd /D "%JRE_HOME%\lib\security\"
%JAVA_HOME%\bin\keytool -importcert -trustcacerts -alias "<descriptive alias here>" -keystore cacerts -storepass changeit -file C:\path\to\certificate.cer

This command can also be run at a later stage when third-party backend services are added to user registration workflows.

Setting Up customerid.home System Property for WildFly

WildFly requires the customerid.home system property in order to locate relevant configuration files. To update this system property, run register-customerid-home.cmd from tools folder. 

cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools"
register-customerid-home.cmd

The command has run successfully if the output shows {"outcome" => "success"}.

Setting Up Audit and Diagnostic logging

Starting from Ubisecure CustomerID 5.0.x, logging is managed centrally via the WildFly Java EE container. The script setup-logging.cmd contacts WildFly management port and then sets up logging configuration to redirect Ubisecure CustomerID specific log entries to separate files. To set up logging, run the following commands in a command prompt: 

cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools"
setup-logging.cmd

The command has run successfully if the output shows {"outcome" => "success"} many times.

Setting Up a Mail Session

The mail session is set up by executing the script create-mail-session.cmd

cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools"
create-mail-session.cmd

The command has run successfully if the output shows {"outcome" => "success"} and "reload required" many times.

Preparing a Database for Ubisecure CustomerID

This chapter will describe how to install a very basic PostgreSQL Server RDBMS installation with a basic database for Ubisecure CustomerID. Many details will vary on a per customer basis, so further tuning is left to the integrator. One significant detail is to manage the collation rules on a per-column basis, therefore it is most probably necessary to make changes to the provided Database Definition Language (DDL) files before they are used to create the database tables for Ubisecure CustomerID. Collations define how text is compared and sorted and whether searches should behave in a case sensitive or insensitive manner.
Following commands are just examples how install a basic PostgreSQL database. You might want to use your own commands. Don't copy and paste the commands in this chapter. Write them by hand to the command prompt to avoid involuntary character replacement.

Obtaining and Installing PostgreSQL

Ubisecure CustomerID requires a PostgreSQL database which is not included in the distribution.

PostgreSQL binaries and instructions on how to use platform specific package managers to download and install PostgreSQL, can be found at the following URL:
https://www.postgresql.org/download/
Having obtained PostgreSQL binaries, run the wizard or relevant binaries to install. The installation process is documented and maintained by your PostgreSQL provider, so please follow their instructions to ensure the best possible configuration. We have tested Ubisecure CustomerID with PostgreSQL 9.4.x.

Creating a Database User

Use the following command to create a new user in the PostgreSQL database.

cd /d C:\Program Files\PostgreSQL\9.4\bin  (your PostgreSQL installation directory)
psql --username=postgres -c "CREATE USER customerid_user WITH PASSWORD 'replace with your database.password from win32.config'"

When prompted, enter the password given in the installer wizard window during the PostgreSQL installation process.

Creating the Database

psql --username=postgres -c "CREATE DATABASE customeriddb WITH OWNER = customerid_user ENCODING = 'UTF8' TABLESPACE = pg_default LC_COLLATE = 'Finnish_Finland.1252' LC_CTYPE = 'Finnish_Finland.1252' CONNECTION LIMIT = -1;" 
psql --username=postgres -c "GRANT CONNECT, TEMPORARY ON DATABASE customeriddb TO public;" 
psql --username=postgres -c "GRANT ALL ON DATABASE customeriddb TO customerid_user;"

Modifying the DDL

The main modifications to the DDL involves setting collations to specific columns. There could be some information that should be interpreted as identical regardless of letter case but on the other hand there could also be some attributes where letter case is significant in uniqueness. In order to make it easier to set collations to columns it is convenient to create named collations that can be referenced by name instead. 

psql --username=postgres --dbname=customeriddb -c "CREATE COLLATION custom_collation (locale = 'Finnish_Finland');"

Now that there's a named collation, it can be attached to column definitions by modifying DDL like in example below:
Original: 

CREATE TABLE CIDTUSERS (
CIDCUSERID CHAR(36) NOT NULL CONSTRAINT CIDPK_CIDTUSERS PRIMARY KEY,
CIDCREPOUSER VARCHAR(1024),
CIDCORGANIZATIONID CHAR(36) CONSTRAINT CIDFK_CIDTUSERS_CIDCORGANIZATIONID REFERENCES CIDTORGANIZATIONS (CIDCORGANIZATIONID),
CIDCSTATUS INTEGER NOT NULL DEFAULT 4,
CIDCCN VARCHAR(1024),
CIDCEMAIL VARCHAR(1024),
CIDCMOBILE VARCHAR(1024),
CIDCLOCALE CHAR(5),
CIDCFIRSTNAME VARCHAR(1024),
CIDCSURNAME VARCHAR(1024),
CIDCLOGIN VARCHAR(1024),
CIDCSSN VARCHAR(1024),
CIDCCREATED TIMESTAMP NOT NULL,
CIDCLASTMODIFIED TIMESTAMP NOT NULL);

Modified: 

CREATE TABLE CIDTUSERS (
CIDCUSERID CHAR(36) NOT NULL CONSTRAINT CIDPK_CIDTUSERS PRIMARY KEY,
CIDCREPOUSER VARCHAR(1024),
CIDCORGANIZATIONID CHAR(36) CONSTRAINT CIDFK_CIDTUSERS_CIDCORGANIZATIONID REFERENCES CIDTORGANIZATIONS (CIDCORGANIZATIONID),
CIDCSTATUS INTEGER NOT NULL DEFAULT 4,
CIDCCN VARCHAR(1024) COLLATE custom_collation,
CIDCEMAIL VARCHAR(1024) COLLATE custom_collation,
CIDCMOBILE VARCHAR(1024),
CIDCLOCALE CHAR(5) COLLATE custom_collation,
CIDCFIRSTNAME VARCHAR(1024) COLLATE custom_collation,
CIDCSURNAME VARCHAR(1024) COLLATE custom_collation,
CIDCLOGIN VARCHAR(1024) COLLATE custom_collation,
CIDCSSN VARCHAR(1024),
CIDCCREATED TIMESTAMP NOT NULL,
CIDCLASTMODIFIED TIMESTAMP NOT NULL);

Applying the CustomerID DDL to PostgreSQL

psql --dbname=customeriddb --username=customerid_user -f "%PROGRAMFILES%\Ubisecure\customerid\sql\cid_create.sql"

When prompted, enter the password from the database.password value of the win32.config file.

If you notice something wrong with the database at this point, it is possible to drop the tables using the script cid-drop.sql. After this, the DDL can be modified and imported again. Note that all inserted data in the database will be lost when the tables are dropped.

Creating the JDBC Data Source to WildFly

Ubisecure CustomerID uses a JDBC data source to access the database, thus one needs to be created to WildFly before the Ubisecure CustomerID application can be deployed. There is a script in the distribution package's tools folder for this purpose: create-datasource.cmd. Note that the win32.config file must have been configured and setup.cmd must have been run successfully and WildFly must be running before the create-datasource.cmd script can be run successfully. 

cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools"
create-datasource.cmd

Successful execution will output the following text: The batch executed successfully.

Directory Service for Ubisecure CustomerID Internal Database

You need to define a directory service in Ubisecure SSO Management that is used for accessing the Ubisecure CustomerID's SQL database. To create the service open Ubisecure SSO Management.

Start Ubisecure SSO

net start UbiloginServer

1. Access the URL UAS_URL/ubilogin in a browser
2. Create a new Service in Services tab (Select Home → Services → New Service...)
   
   • Title:  CustomerID SQL
   • Directory type:  SQL
     
     
3. Click OK
4. Edit following information:
   
   • Service URL: 
     jdbc:postgresql://host:port/customeriddb  – replacing hostname and port number as needed using database.host and database.port settings from customerid\application\win32.config
   • Username:
     Use database.user value from customerid\application\win32.config. This value is usually customerid_user

   • Credentials:
     Use database.password value from customerid\application\win32.config

     NOTE: If there are escape characters ("\") in the database.password value, remove them before copying the value to the Credentials field.

   • Configuration: 
     Enter the following text in the Configuration String text area: 
     validationQuery=SELECT 1

     This defines the PostgreSQL specific query called when determining if a JDBC connection is open and operating.
     

     Figure 2, SQL Configuration

5. Click Update

6. Restart Ubisecure SSO 
   

   net stop UbiloginServer
   net start UbiloginServer

Creating Web Agents for Ubisecure CustomerID

Ubisecure CustomerID needs two web agents. The first one is used to provide login functionality to the Ubisecure CustomerID user interfaces and it also provides the LDAP user account that Ubisecure CustomerID uses when accessing Ubisecure Directory. The second web agent is used when performing verifications during registrations. Ubisecure CustomerID installation package contains LDIF import files that need to be imported to Ubisecure Directory using the import functionality of Ubisecure SSO.

• Importing the web agent:

Import the LDIF files that create the web agent by issuing the following commands: 

cd /D "%PROGRAMFILES%\Ubisecure\customerid\application\ldap"
import.cmd customerid.ldif
import.cmd customerid-secrets.ldif
import.cmd customerid-adlds.ldif

Ubisecure CustomerID Directory Service Configuration

Ubisecure CustomerID needs an access to the main user LDAP directory and a directory service is needed to establish this connection. To create the service open Ubisecure SSO Management.

1. Access the URL UAS_URL/ubilogin in a browser
2. Create a new Service in Services tab (Select Home → Services → New Service...)
   
   • Title: 
     CustomerID Directory
   • Directory type: 
     Ubilogin Directory  or  Active Directory
     Select  Active Directory  only when external AD is used for CustomerID user storage. Typically Ubilogin Directory is used.
     
3. Click OK

4. Append one of the following two configurations to the existing text in the "Configuration String" field, depending if UbiloginDirectory or Active Directory is used for CustomerID user data storage: Typically Ubilogin Directory is used.
   Ubilogin Directory: 

   policy.password.encoding={SSHA}
   directory=ldap:///{LDAP root}
   policy.password.protocol=UbiloginDirectory
   password-name=password.2

   Active Directory: 

   java.naming.ldap.attributes.binary=objectGUID
   policy.password.protocol=ActiveDirectoryDs
   password-name=password.2

   For detailed instructions concerning these settings see Ubisecure SSO Installation and Upgrade document. You can check the value of {LDAP root} for example from the jndi.properties file situated in the %PROGRAMFILES%\Ubisecure\customerid\application\custom folder. The value is the LDAP root part of the java.naming.provider.url property. Example: 

   java.naming.provider.url = ldap://localhost:389/cn=Ubilogin,dc=test

   

5. For clustered Ubisecure SSO you will need the following following settings in the CustomerID Directory settings in the Ubisecure SSO Home → Services tab → CustomerID Directory → Configuration String

   com.ubisecure.util.ldap.server.list=<ldap://server1:port/> <ldap://server2:port/>
   com.ubisecure.util.ldap.failover.type=single-master (default is multi-master)
   com.sun.jndi.ldap.connect.timeout=15000 (in milliseconds)
   com.sun.jndi.ldap.read.timeout=15000 (in milliseconds)
   com.ubisecure.util.ldap.maxage=120000 (in milliseconds)
   com.ubisecure.util.ldap.auth.pool.max=8

6. Click Update

7. Restart Ubisecure SSO from command line
   

   net stop UbiloginServer
   net start UbiloginServer

Ubisecure CustomerID SSO Adapter Installation

See CustomerID SSO Adapter Installation In Windows

Authentication Method Configuration

The authentication method configuration is done using Ubisecure SSO Management or the LDIF import files provided by Ubisecure SSO installation.

Create the Authentication Methods

Any required authentication methods used by users must now be created according to the general guidelines concerning creating authentication methods into Ubisecure SSO.

Typical methods include username and password, SMS OTP, One TIme Password Printout and third-party banking services (TUPAS). Add only the methods that will be used in the current installation:

• Password method
  • Set title:
    CustomerID Password
  • Name:
    password.2
  • Select method type:
    SPI Password
  • Set directory to:
    CustomerID Directory
    
    
  • By default user logs in using the login attribute (which is uid in Ubisecure Directory and sAMAccountName in Active Directory). If you want the user to login using email address, you must add directory.account.login=mail to the configuration string. You must also add general.login.attribute=mail to eidm2.properties. Create eidm2.properties text file under %PROGRAMFILES%\Ubisecure\customerid\application\custom


  • Set the optional policy.password.expiring configuration string to show a warning to users during login of a pending password expiry. The value is number of minutes. 10080 is one week. This number should be increased accordingly if users rarely use the system.
    
  • Select Enabled
  • Press Update
• SMS method
  • Set title. Title will be shown in the user interface during login.
    SMS
  • Name:
    ubikey.sms.1
  • Select method type:
    SPI Mobile Phone

  • Set directory to:
    CustomerID Directory
    
    
    

    Figure 4. SMS method

• • By default user logs in using the login attribute (which is uid in Ubisecure Directory and sAMAccountName in Active Directory). If you want user to login using email address, you must add directory.account.login=mail to the configuration string. You must also add general.login.attribute=mail to eidm2.properties. Create eidm2.properties text file under %PROGRAMFILES%\Ubisecure\customerid\application\custom
  • You need to define the password-name configuration string. It should contain the name of the used password method (usually password.2).

  • You need to define the smsUrl configuration string. It should contain the URL of the SMS server.

    Figure 5, SMS URL

  • If Active Directory is used as the main user repository for Ubisecure CustomerID then you need to define the methodUserGroupDN configuration string. It points to the AD group which defines those users that are allowed to use SMS authentication. The relative name of the correct group is ActiveSMSUser. The whole DN is installation specific. Typically Active Directory is not used as the main user repository for Ubisecure CustomerID.
  • Select Enabled
  • Press Update

• OTP Printout method
  • Set title: Title will be shown in the user interface during login.
    One Time Password
  • Set name:
    ubikey.otp.1
  • Select method type:
    SPI Ubikey OTP Printout
  • Set directory to:
    CustomerID Directory
    
    
  • By default users log in using the login attribute (which is uid in Ubisecure Directory and sAMAccountName in Active Directory). If you want users to login using their email addresses, you must add directory.account.login=mail to the configuration string. You must also add general.login.attribute=mail to eidm2.properties. Create eidm2.properties text file under %PROGRAMFILES%\Ubisecure\customerid\application\custom
  • You need to define the password-name configuration string. It should contain the name of the used password method (usually password.2).

  • If Active Directory is used as the main user repository then you need to define the userCredentialsTableDN configuration string. It defines the name of the OTP table object in Ubisecure Directory. OTP Printout authentication method information is stored in Ubisecure Directory for all Active Directory users who use the OTP Printout method and that information will be stored under the OTP table. Typically Active Directory is not used as the main user repository for Ubisecure CustomerID.

    Figure 6, OTP Printout Method, configuration string parameters will be shown after next part

• • Press Update
  • Select the SPI Ubikey Printout tab
    • You need to define the otpWindow configuration string if you want to define how many one-time passwords from the password list are checked against the given one-time password during one-time password validation.
    • You need to define the otpDefaultLength configuration string if you want to define the length of the one-time passwords.
    • You need to define the otpDefaultListLength configuration string if you want to define the amount of one-time passwords in a generated password list.

    • For sending the OTP list from within the Ubisecure SSO Management application the mailSessionJNDIName configuration string must be set. In most cases, this field can be left blank as it is not required for self-service list management using Ubisecure CustomerID.

      Figure 7, OTP Printout Configuration Strings

    • Select Enabled
    • Press Update

• TUPAS methods
  
  • This is only required when using Finnish Bank Authentication Services
  • When creating the TUPAS methods follow the separate TUPAS methods related documentation.
  • Automatic creation for TUPAS test methods can be done with %PROGRAMFILES%\Ubisecure\ubilogin-sso\ubilogin\ldap\adam\import.cmd ..\methods\methods-tupas.ldif command

Remember to enable all of the created authentication methods. This can be done by selecting the X at the top of the checkbox column to tick all boxes, and then press Update.
For more information concerning authentication method configuration check the Ubisecure SSO authentication method documentation.

Create a Site-Specific Configuration for Ubisecure CustomerID

The next step in Ubisecure CustomerID installation is to create a site specific configuration for Ubisecure CustomerID. This can be done by editing the custom/eidm2.properties and other Ubisecure CustomerID configuration files. For more information about the configuration options, refer to CustomerID Configuration. If you will be using Active Directory as the main user repository for Ubisecure CustomerID then you can find AD specific configuration guidance from CustomerID AD Integration Configuration. After you have finished creating a site specific setup, return to this document and go through the rest of the chapters. 

Examples of the types of configurations required at the step include:

• defining user registration workflows
• defining organization types and roles
• defining what strong authentication methods are available
• defining policies for login names

Generally it is recommended to use a very basic eidm2.properties configuration first, ensure the system is fully configured and running and then modify the settings again later to match the use case requirements.

Execute the following commands to create and edit the eidm2.properties file:

cd /d %PROGRAMFILES%\Ubisecure\customerid\application\custom
notepad eidm2.properties

Typical entries include:

# use email address as the username when logging in
# this requires that directory.account.login=mail is added to password.2 authentication method settings
# without this setting, the default uid is used as the username when logging in
general.login.attribute = mail

# where to redirect the user when an error occurs or user presses exit - generally home page of the target service
general.default.returnUrl = https://www.example.com

# where to redirect the user after logout has been performed
general.default.logoutReturnUrl = https://www.example.com

Deploying Ubisecure CustomerID

Ubisecure CustomerID uses WildFly as a J2EE Container. This chapter describes how to download Identity Provider metadata from Ubisecure SSO, generate Service Provider metadata, and deploy the cid-ear-x.x.x.ear and cid-worker-ear-x.x.x.ear enterprise archives (EARs).

To download Identity Provider metadata and generate Service Provider metadata:

1. Download IDP metadata by running the following commands:

   cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools\"
   get-metadata.cmd

   This command will show download statistics if successful.

2. Initialize Ubisecure CustomerID SPs by running the following commands: 

   cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools\"
   init-eidm-sp.cmd

   This command will not display any output if successful.

3. Initialize authentication provider by running the following commands: 

   cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools\"
   init-eidm-ap.cmd

   This command will not display any output if successful.

Deploy the Ubisecure CustomerID applications to WildFly using the deploy-ear.cmd script. When invoking the script, you must supply the path to the ear file, like in the example below: 

cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools\"
deploy-ear.cmd %USERPROFILE%\Desktop\customerid\cid-ear-x.x.x.ear
deploy-ear.cmd %USERPROFILE%\Desktop\customerid\cid-worker-ear-x.x.x.ear

Ubisecure CustomerID Initialization

To initialize Ubisecure CustomerID with initialization scripts:

1. Initialize Ubisecure CustomerID internal database and repository (i.e., the part of Ubisecure Directory needed by Ubisecure CustomerID) by running the following commands

   cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools\"
   init-customerid-data-storages.cmd

   Successful execution will show: <init><initializeDatabase/></init>

2. Download SP metadata for authentication provider by running the following commands: 

   cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools\"
   get-metadata-for-ap.cmd

   This command will show download statistics if successful.

Restarting Ubisecure Software

Ubisecure SSO & CustomerID restart is required to take into use all the new features initialized in the previous chapter.

To restart Ubisecure SSO:

1. Restart Ubisecure SSO by running the following commands: 

   net stop UbiloginServer
   net start UbiloginServer

2. Restart Ubisecure CustomerID by running the following commands: 

   net stop wildfly
   net start wildfly

   NOTE: Stopping the Ubisecure CustomerID service using the mentioned command may not succeed in Windows if your firewall settings block access to WildFly management.

Go to CustomerID Example User Data Import In Windows to import the example admin user.

You can now login using URL: https://<eidm.url>/eidm2/wf/admin

eidm.url value can be found from the file %PROGRAMFILES%\Ubisecure\customerid\application\win32.config