Before Installation

System Requirements

Ubisecure SSO Server
Installation according to the Installation - SSO Guide.

Required files

ldap\methods.ldif
Configuration file from Ubisecure Server Installation directory.

Requirements for production use

Agreement(s) with chosen bank(s) that support TUPAS authentication
TUPAS 2 configuration parameters from bank(s)

Ubisecure Server installation pack contains TUPAS2 configuration parameters for testing.

Installation and Configuration

Installing the TUPAS 2 Authentication Method

From Ubisecure SSO 6.1 on, there are two ways to add TUPAS 2 authentication method to the Ubisecure Directory: via the Ubisecure Management user interface, or by creating tupas.ldif file manually. In older Ubisecure SSO versions, only the latter method is available.

To install TUPAS 2 authentication method with Ubisecure Management

Log into Ubisecure Management.
Go to Home → Global Method Settings and click the New Method... button.
Add New Method window opens
Give the method title and name. Ensure that these reflect which bank this method is for.
From Method Type drop-down menu, select Tupas 2.
Click OK.
Repeat steps 2-3 for each bank whose Tupas 2 method you wish to add.

To install TUPAS 2 authentication method by creating `tupas.ldif` file manually

Add a TUPAS authentication object to your Ubisecure Directory with the import script from Ubisecure Server Installation.
You will either need the file methods.ldif (this file existed until Ubisecure SSO Server version 6.0.0), or methods-tupas.ldif (from Ubisecure SSO Server version 6.0.1 on). After installing Ubisecure SSO Server as instructed in the Ubisecure Server Installation Guide, this file will be in directory c:\Program Files\ubilogin-sso\ubisecure\ldap (Windows environment) or /usr/local/ubisecure/ldap (Linux environment).
If you have the methods-tupas.ldif file, you can use it as the base file as it is. It contains fully functional test configuration for TUPAS 2 use. A sample methods-tupas.ldif file is also included in page Configuration Settings.
If you have the methods.ldif file, copy the parts that contain "Tupas 2" in their labels to a new file named tupas.ldif. For example, if you are going to use all different banks for TUPAS authentication, copy the entries labelled as "Tupas 2, Nordea", "Tupas 2, OKO" and so forth for all available TUPAS 2 authentication parameters. See Listing 1 for an example of how TUPAS 2 entry for Nordea bank in the tupas.ldif file looks like.
Listing 1. Example of tupas.ldif TUPAS 2 entry (Nordea only)
```
# Tupas 2, Nordea
dn: cn=tupas.nordea.1,cn=Server,ou=System,cn=Ubilogin,dc=localhost
changetype: add
cn: tupas.nordea.1
objectClass: top
objectClass: ubiloginAuthMethod
ubiloginAuthMethodType: Tupas 2
ubiloginClassname: com.ubisecure.auth.login.Tupas2LoginModule
ubiloginConfString: alg 03
ubiloginConfString: idtype 02
ubiloginConfString: keyvers 0001
ubiloginConfString: langcode FI
ubiloginConfString: macKey1 LEHTI
ubiloginConfString: rcvid 87654321
ubiloginConfString: url https://tupas.nordea.fi/cgi-bin/SOLO3011
ubiloginConfString: vers 0002
ubiloginEnabled: FALSE
ubiloginTitle: Nordea
```
Choose the import script according to your platform. Execute the following commands to create the TUPAS object in the Ubisecure Directory.
Listing 2. Initializing Ubisecure Directory and TUPAS in Linux
```
cd /usr/local/ubisecure/ubilogin-ss/ubilogin/ldap
sh openldap/linux/import.sh tupas.ldif
```
Listing 3. Initializing Ubisecure Directory and TUPAS in Windows
```
cd /d "c:\Program Files\Ubisecure\ubilogin-sso\ubilogin\ldap"
adam\import.cmd methods\methods-tupas.ldif
```

Configuring the TUPAS 2 Authentication Method

Start a session with Ubisecure Management, log in as an administrator and go straight from the top level to page "Global Method Settings". There you should now see an entry "TUPAS" for every bank you added with Ubisecure Management or by creating the .ldif file. Using information provided by your bank, set the necessary parameters in the following screens. The default parameters enable using test accounts that each bank provides.

To configure TUPAS 2 authentication method:

Log into Ubisecure Management as an administrator.
Select Global Method Settings.
Select a TUPAS authentication method from the Server Authentication Methods list.
The view that opens is presented in Figure 1. (The images in this page use Nordea bank TUPAS configuration as an example.) The fields of the screen are explained below the image under the expand link.
Click here to expand...
Figure 1. Configuring TUPAS authentication in Ubisecure Server Management (Screen 1)
- Title
  Title for the authentication method, will be visible for end users, for example in the authentication method selection menus.
- Name
  Name for the authentication method, will be visible for system administrators and used in logging. Can not be modified.
- Declaration Reference
  SAML reference to this authentication method for Authentication Context purposes. This field shows the authentication method name in the same form as it is displayed in SAML messages. SP can use this name to call a certain method. IdP uses this name to tell SP with which method the user was authenticated. Can not be modified.
- Class Reference
  Used to specify the SAML Authentication Contect Class Reference for interoperability purposes. For SAML use it is possible to group authentication methods, e.g., by strength. By using the SAML API an application can request an authentication method from a specified class. Typically this setting is not required and can be left blank.
- Enabled
  Tick to enable this method for use.
- Hidden
  Tick to hide this method from selection menus. It is still possible to use this method, if selected directly by other means.
- Limit Method Visibility
  Enter a netmask range of those IP addresses to which this method will be visible. IP addresses outside this range will not see this method in menu selections. If this field is left blank, method visibility is not limited.
More options are available under Tupas 2 tab:
Click here to expand...
Figure 2. Configuring TUPAS authentication in Ubisecure Server Management (Screen 2)
- url
  TUPAS service address.
- version
  TUPAS version number.
- langcode
  Indicates the default language to use, if the current language of the user is not Finnish or Swedish. "FI" is the code for Finnish, "SV" for Swedish. Please note that not all banks offer other languages. Typically this value is "EN" (English) by default.
- idtype
  Indicates what type of identification is requested from the bank. The value is usually 01 (hashed basic identifier) or 02 (plain basic identifier). idtype 02 (plain basic identifier) is the only supported method for interactive login where user is directed to the TUPAS provider. Use of other idtypes will prevent the listing of the bank in the authentication method list during login. For use of other idtypes, please contact Ubisecure support.
  
  TIP: The idtype always consists of two numbers (XY).
  The first character (X) specifies the contents of the requested identifier: 0Y = basic identifier, 1Y = personal identity code, 2Y = business identification code, 3Y = personal ID code or business ID code, 4Y = personal ID and business ID code.
  The second character specifies the form of the requested identifier: X1 = encrypted identifier, X2 = plaintext identifier, X3 = truncated identifier.
  Code 43 is not in use
- alg
  Encryption algorithm used to create MAC (message authentication code, used to encrypt the requests). Up until TUPAS 2.2 version, possible values were 01 (MD5 algorithm, creates 32-character MAC) and 02 (SHA-1 algorithm, creates 40-character MAC). From TUPAS version 2.3 on, the only allowed value is 03 (SHA-256 algorithm, creates 64-character MAC).
- rcvid
  Service provider identifier.
- keyvers
  Version number for the key used to generate MAC. This is usually 01; ensure this from the bank if needed.
- macKey1
  macKey1 is the service password. It is stored as an encrypted value and is not shown on the screen.
- Mackey1ValidTo
  Validity date range of macKey1. This is the date and time when the old macKey will be replaced automatically by the configured macKey2. Use the format shown on the screen (yyyy-MM-dd HH:mm:ss). Please see chapter After Installation below for more details.
- macKey2
  macKey2 will become active when macKey1 expires. Please see chapter After Installation below for more details.
- custtypes
  In this field, the customer types you wish to accept in the received response may be listed as comma-separated numeric values.
  Example: custtypes: 01,03
  If this field is left blank, all customer types are accepted. The default setting is to accept all customer types.
  
  TIP: The custtype data is coded using two characters, XY.
  The first character (X) indicates whether the requested customer information was found in the bank's database: 0Y = the requested information was found, 1Y = the requested information was not found.
  The second character (Y) indicates the type of information. The code combinations for found information are: 00 = identifier is unknown, 01 = personal number (henkilötunnus), 02 = extension of personal number (henkilötunnuksen tarkenne), 03 = business ID (Y-tunnus), 04 = electronic communication identifier (sähköinen asiointitunnus), 05 = encrypted personal number (salattu henkilötunnus), 06 = encrypted business ID (salattu Y-tunnus), 07 = encrypted electronic communication identifier (salattu sähköinen asiointitunnus), 08 = other identifier, 09 = encrypted other identifier.
- Append String Not required. This function has been replaced by Authorization Policy settings and is included for backwards compatibility. The append string will only be added to a ticket response if no Authorization Policy is used.
After completing these settings, Ubisecure SSO Server is configured to use this particular TUPAS method as an authentication method. Repeat steps 2-4 for all additional TUPAS methods you wish to use.

After Installation

Configuring User and Application to Use the TUPAS Authentication Method

After installing and configuring TUPAS authentication method for the Ubisecure Server, use Ubisecure Management to configure authentication method in use for a user and an application.
The method must be enabled at three places:

at the system level (Home → Global Method Settings)
at the site level (Home → Site → Site Methods)
and for each application (shown as ticked in the Application's Allowed Method tab)

For more instructions on authentication method configuration, please refer to Management user interface - SSO Guide.

Logging in for the first time with the TUPAS authentication method

The default parameters enable use of the test accounts that each bank provides. Please refer to the TUPAS documentation of each bank for what IDs and passwords are used for testing. By default, the usernames are mapped to social security code attributes provided by TUPAS.

At the time of writing, the test accounts were as follows:

BANK	USERID	PASSWORD	SECURITY CODE
Aktia/SP/POP	11111111	123456	123456
Handelsbanken	<not required>	<not required>	<not required>
Nordea (Company)	55555555	5555	<not required>
Nordea (Personal)	123456	1234	<not required>
OKO Osuuspankki	123456	7890	<any 4 digits>
Danske	Currently not provided	Currently not provided	Currently not provided
S-Pankki	12345678	1234	<any 4 digits>
Tapiola	12345678	123TAP	9999
Ålandsbanken	12345678	9999	<not required>

Browser not supported