Certificate Authentication Provider may be combined with the Satu-Hetu service. Using this configuration, UAS converts a citizen's electronic identity number (SATU, sähköinen asiointitunnus) to a Finnish Identity Number (HETU, henkilötunnus) using the VTJKysely web service. VTJKysely is a service provided by the Finnish Population Register Centre. Satu-Hetu Configuration is an optional configuration and required only when an application requires Finnish Identity Numbers.

Chapter Process Flow gives an overview of the system as a whole. Chapter Satu-hetu configuration how to setup and configure the Satu-Hetu conversion using the Ubisecure Server Management application.

Process Flow

The process flow is shown in Figure 1 and is described below:

1. A user attempts to access the resource /webapp/resource for the first time. The user has no valid existing session.
2. SAML SP creates a SAML AuthnRequest and redirects the user to UAS
3. UAS optionally presents the authentication selection method menu if more than one authentication method is permitted for this SP
4. UAS generates a SAML AuthnRequest and redirects the user to the Certificate Authentication Provider
5. Certificate Authentication Provider requests a Client Certificate from the browser using Two-Way SSL. Depending on the browser used and client software installed, the user may be prompted to select a certificate and enter a corresponding PIN. For Finnish Identity Cards, this software is provided by Väestörekisterikeskus.
6. If a certificate is received that matches the policy.xml defined, Certificate Revocation check is performed at this stage by HTTP or LDAP query to the CRL or OCSP defined in the Certificate Authentication Provider's policy.xml configuration file.
7. Upon success, Certificate Authentication Provider creates a SAML Response and redirects the user to UAS for further authentication and authorization. Attributes from the client certificate are sent according to the settings in the Certificate Authentication Provider's policy.xml configuration file.
8. The SAML Response is sent from Certificate Authentication Provider to UAS.
9. If the tag {vtj:ATTRIBUTE_NAME} is used in Method Attribute Mapping for the Certificate Authentication Provider method, the Satu is taken from the attribute ATTRIBUTE_NAME and converted to a Hetu according to steps 10, 11 and 12.
10. First, the SATU used is checked against the Satu-Hetu cache, if enabled. The Satu-Hetu cache is kept in an LDAP directory as defined in the Satu-Hetu configuration Cache URL (Ubisecure Management: Server->Satu-Hetu Configuration-> Satu-Hetu Cache). If the SATU is found from the cache, the corresponding HETU is returned by the {vtj:ATTRIBUTE_NAME} tag. This is logged as "Cache hit".
11. If the SATU is not found from the cache, the VTJKysely service of the Väestörekisterikeskus is used. This is logged as "Cache miss". A HTTPS connection is made to the VTJKysely service using two-way SSL. The client certificate used is specified in the SSL configuration file specified in the Satu-Hetu Service (Ubisecure Management: Server->Satu-Hetu Configuration->Satu-Hetu Service). The VTJKysely is performed using SOAP. If the Satu-Hetu cache is disabled or can not be reached, the VTJKysely is performed every time.
12. If the SATU is found from the VTJKysely, the corresponding HETU is returned by the {vtj:ATTRIBUTE_NAME} tag. If the Satu-Hetu cache is enabled, the new SATU and HETU pair are added to the Satu-Hetu cache. If the SATU is not found from the VTJKysely service, authorization fails and the error is logged.
13. UAS sends a SAML Response to the SAML SP, identifying the user and attributes according to the Authorization Policy selected for that specific SP.
14. SAML SP redirects the user to the desired resource /webapp/resource.

Note that there are two distinct two-way SSL connections made.

The first two-way SSL connection is between the Certificate Authentication Provider and the browser, where the client certificate is typically stored in the browser or presented via client software from a hardware token or smart card. The root certificate for the issuer of the client is found in the policy.xml configuration file. The server on which Certificate Authentication Provider resides, must have LDAP or HTTP network access to the certificate revocation list (CRL) provided by VRK.

The second two-way SSL connection is between the UAS and the VTJKysely service. The issuer of the client certificate used must be trusted by the VTJKysely service. The root certificate of VTJKysely service, the client certificate and corresponding password used with VTJKysely is defined in the SSL configuration file for the Satu Hetu service (see next chapter). The UAS server must have HTTPS network access to the VTJKysely service.

Satu-Hetu Configuration

Satu-Hetu configurations are listed in Services view (Home → Services).

New Satu-Hetu configurations can be created by clicking the New Satu-Hetu... button in this view.
Existing Satu-Hetu configurations can be examined and edited by clicking on the configuration title.

Satu-Hetu Configuration View

• General
  • Name
    Name of the Satu-Hetu configuration
  • Description
    Description of the Satu-Hetu configuration
• Satu-Hetu Cache
  • Type
    Satu-Hetu cache type. Supported cache types are Ubilogin and Katve. In addition, cache may be disabled by selecting Disabled.
  • Cache URL
    Satu-Hetu cache URL and root. Cache entries are stored as children of root. Directory must be defined with external directory integration.
• Satu-Hetu Service
  • URL
    Satu-Hetu service URL. This is provided by VRK. 
  • Username
    Username for Satu-Hetu service.
  • Password
    Password for Satu-Hetu service.
  • SoSoNimi
    This is a VRK specific parameter. The value will be provided by VRK.
  • Loppukäyttäjä
    This is a VRK specific parameter. The value will be provided by VRK.
  • Laskutustiedot
    This is a VRK specific parameter. The value will be provided by VRK.
  • Tunnistusportaali
    This is a VRK specific parameter. The value will be provided by VRK.
  • Vara1
    This is a VRK specific parameter. The value will be provided by VRK.
  • SSL
    configuration Reference to a SSL configuration used in Satu-Hetu query. If omitted, the default SSL configuration and truststores are used.
  • Update
    Update the modified configuration.
  • New…
    Create a new Satu-Hetu configuration.
  • Delete
    Delete the Satu-Hetu configuration.
  • Rename
    Rename the Satu-Hetu configuration.

• Methods view

  Figure 4. Satu-Hetu Configuration Methods view

• Satu-Hetu Configuration
  Methods view shows a list of available authentication methods. Selected methods are assigned with the current Satu-Hetu configuration. Each method may be assigned with at most one Satu-Hetu configuration at a time. Therefore, assigning a Satu-Hetu configuration to a method replaces the previous assignment.
• Update
  Assign the Satu-Hetu configuration with selected authentication methods
• SSL
  Configuration
• SSL with client certificates is required by Satu-Hetu service in production environment. A test service without requirement for client certificates is also provided. SSL parameters are configured in Ubilogin installation directory.

Add the relative location of SSL configuration to ubisecure\config.index

ssl.vrk = custom/ssl/vrk.properties
Example config.index entry
Copy the client certificate and the trusted root certificate of the Satu-Hetu service to the same directory with SSL configuration. Create the SSL configuration file defined in config.index. 

#client.localAddress = 0.0.0.0
client.cert = client.pfx
client.cert.password = pass 
ca.cert = vrksp.crt

Example SSL configuration file

client.localaddress
May be used to defines the local address to be used if the server has multiple IP addresses.

client.cert
The location of client certificate in PKCS12 format. If omitted, SSL client authentication is disabled. Please note that the SSL client authentication is required in production environment Satu-Hetu service.

• client.cert.password
  The password for client certificate.
• ca.cert
  The trusted root certificate of the Satu-Hetu service.

Method Attribute Mapping

Satu-Hetu query is activated by creating a method attribute mapping and assigning it to an authentication method. An example is provided in the following figure. Please refer to the chapter Attribute Mapping in SSO Management pages for details.