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

1. Log into Ubisecure Management.
2. Go to Home → Global Method Settings and click the New Method... button.
3. 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.
4. 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

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

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

1. Log into Ubisecure Management as an administrator.
2. Select Global Method Settings.

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