...

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

Perform on Ubisecure CustomerID server (or relating to it):

1. Back up Ubisecure Directory. See instructions from from Backup And Restore and restore - Ubisecure Directory.
2. Unpack the distribution package. See instructions from CustomerID Distribution Package Unpacking In Windows Distribution package unpacking on Windows - CustomerID.
3. Check Java. See instructions from CustomerID Java Check In check on Windows - CustomerID.
4. Install WildFly. See instructions from CustomerID WildFly Installation In installation on Windows - CustomerID.
5. Extract the deployment template. See instructions from CustomerID Deployment Template Extraction In Windows Deployment template extraction on Windows - CustomerID.
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
Image Removed

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);

...

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.

...

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

...

• Title:  CustomerID SQL
• Directory type:  SQL
  Image Removed
  

...

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

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

...

...

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

...

• 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.
  Image Removed

...

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

Image Removed

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

...

Restart Ubisecure SSO from command line

net stop UbiloginServer
net start UbiloginServer

Ubisecure CustomerID SSO Adapter Installation

See CustomerID SSO Adapter Installation In Windows

...

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:

...

• Set title:
  CustomerID Password
• Name:
  password.2
• Select method type:
  SPI Password
• Set directory to:
  CustomerID Directory
  Image Removed
  
• 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
Image Removed

• 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.
  Image Removed
• Select Enabled
• Press Update

...

...

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

...

...

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

...

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.

...

...

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

...

...

Figure 8, All authentication methods are ticked as enabled

...

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:

   Code Block
   language text theme RDark
   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: 

   Code Block
   language text theme RDark
   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: 

   Code Block
   language text theme RDark
   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

...

To initialize Ubisecure CustomerID with initialization scripts:

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>

...

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:

Restart Ubisecure SSO by running the following commands: 

net stop UbiloginServer
net start UbiloginServer

Restart Ubisecure CustomerID by running the following commands: 

net stop wildfly
net start wildfly

...

1. template on Windows - CustomerID.
2. Configure WildFly. See instructions from WildFly configuration on Windows - CustomerID.
3. Prepare PostgreSQL. See instructions from PostgreSQL preparation on Windows - CustomerID.
4. Create JDBC data source to WildFly. See instructions from JDBC data source creation on Windows - CustomerID.
5. Create a directory service for Ubisecure CustomerID SQL in Ubisecure SSO Management. See instructions from SQL directory service creation on Windows - CustomerID.
6. Create web agents for Ubisecure CustomerID. See instructions from Web agents creation on Windows - CustomerID.
7. Create a directory service for Ubisecure CustomerID LDAP in Ubisecure SSO Management. See instructions from LDAP directory service creation on Windows - CustomerID.

Perform on each Ubisecure SSO node:

1. Install PostgreSQL JDBC driver to SSO node(s). See instructions from PostgreSQL JDBC driver installation to SSO on Windows - CustomerID.
2. Install Ubisecure CustomerID SSO Adapter to SSO node(s). See instructions from SSO Adapter installation on Windows - CustomerID.

Perform on Ubisecure CustomerID server (or relating to it):

1. Add authentication method configurations in Ubisecure SSO Management. See instructions from Authentication method configuration on Windows - CustomerID.
2. Create a site specific configuration for Ubisecure CustomerID. See instructions from Site specific configuration on Windows - CustomerID.

3. Configure authentication protocol. See instructions from Application identity generation and IDP metadata download on Windows - CustomerID.

4. Deploy Ubisecure CustomerID to WildFly. See instructions from Deployment to WildFly on Windows - CustomerID.
5. Initialize data storages. See instructions from Data storages initialization on Windows - CustomerID.

Perform on each Ubisecure SSO node:

1. Restart Ubisecure SSO. See instructions from Installation related SSO restart on Windows - CustomerID.

Perform on Ubisecure CustomerID server (or relating to it):

1. Restart Ubisecure CustomerID. See instructions from Restart on Windows - CustomerID.
2. Import example admin user. See instructions from Example user data import on Windows - CustomerID.

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