Skip to Content

login.helsinki.fi

Last modified by Jukka Karvonen on 2025/04/23 10:59

login.helsinki.fi is the centralized login service of the University of Helsinki for Web applications. With login.helsinki.fi service, University of Helsinki users can authenticate to over 150 internal services, and hundreds more in Haka and eduGAIN federations.

Services can implement centralized login using login.helsinki.fi with SAML2 or OpenID Connect protocols. During the login process, information about the user can be transmitted, which can be used for rights management.

Adding your service to login.helsinki.fi

Registrations for login.helsinki.fi and service changes are made directly in the Service Provider Registry (SP Registry). If you already have a service in the University of Helsinki's Shibboleth but do not have access to it through the SP Registry, please contact the authentication services.

Required Information

If you want to enable SAML2 or OIDC login for your service, you will need the following information:

  • Service name (e.g., "University of Helsinki Moodle").
    • This is shown to users during the login and should be provided with all languages of the service (fi/en/sv), max 50 characters.
  • A short description of the application (e.g., "University of Helsinki Moodle online learning environment", max 140 characters).
    • This is shown to users during the login and should be provided with all languages of the service (fi/en/sv), max 140 characters.
  • Contact details of the service owner/responsible person, technical contacts, and possible IT Center contact person (name and email).
  • Is the service located on the University of Helsinki network?
    • Who maintains it?
    • What is the https address of the service?
  • Do you want the service to work only for University of Helsinki users, or do you need to allow login by users from the Finnish or international higher education institutions? (see Federated authentication)
  • Attributes required by the service (e.g., name, email address, uid).
  • A link to the application's privacy statement or a similar document compliant with the GDPR, informing users about the use of their data in the system. For
  • When adding a service external to the University of Helsinki, a data processing agreement (DPA) must be made with the provider before implementing centralized login.
  • Service must be registered to University of Helsinki Application portfolio, and link to service information in the Application portfolio must be provided. https://workgroups.helsinki.fi/display/sovellussalkku (requires authentication).

If you need help to configure SP, please provide also the following information.

  • What service platform does the service use? Assistance is best obtained for a standard case of Red Hat Enterprise Linux 8+ / Apache httpd / Shibboleth SP
  • What type of protected application is it? E.g., what programming language/framework is used, what application server, etc.

For University of Helsinki SSO, details are recorded directly in the SP registry. For federated authentication, Haka resource registry is used to register a service.

Technical specifications

Ensure that the service has an NTP service in use

Login will not succeed if the service is out of sync with the login server. The usual threshold is about 5 seconds, but this can vary.

Attributes

During login, various attributes can be passed to the application. Attributes are used to manage, among other things, service access rights, i.e., who has access to different parts of the system.

The best way to use attributes often comes from understanding the users and usage patterns of the University of Helsinki, combined with understanding the technical capabilities of the systems. For example:

  • From a usability perspective, it may be beneficial that certain student groups see different views.
  • Some of the restrictions made by attributes may be mandatory, such as confidential information that should only be visible to certain users.

A list of possible attributes can be found on the User attributes page.

The attributes distributed via login.helsinki.fi are personal data, and their use must be justified. More information about the handling of personal data can be found from Flamma (requires authentication).

Note: The program must handle situations where not all requested attributes are received and provide a clear error message if necessary. For example, staff often do not have a student number, but they may still try to log into systems intended for students. Not all users have email attribute.

User identifiers

There are many options for identifying a user.

  • Most common method is using eduPersonPrincipalName (EPPN) attribute.
    • Format in the University of Helsinki is formatted as "<username>@helsinki.fi".
    • Similarly, uid is just the username, but its use can cause problems if service usage is later expanded, for example, to Haka.
    • EPPN and uid are locked to a user at the University of Helsinki, meaning it is never reused for another user. The same user can have multiple accounts, thus multiple EPPNs. This is the practice at the University of Helsinki and Haka, but it may vary with other identity providers. Often EPPN is locked only for a certain time, like two years, to the same user.
  • SAML Subject-ID
    • Subject-id is identical to eduPersonPrincipalName at the University of Helsinki, but it may be different for other organizations.
    • Pairwise-id is service specified attribute that is different for each IdP-SP-user relationship and as such, may not be used to identify user in any other service.
      • This is useful if you only need to identify returning user but do not care for the identity behind the identifier.
      • Alone, this doesn't count as personal information, as it cannot be used to found who the user actually is.
  • hyPersonStudentId, employeeNumber, nationalIdentificationNumber and funetEduPersonLearnerId are unique personal attributes but they should not be used for identifying a user, as not everyone has them defined. Their benefit is mainly in integration with other systems.

eduPersonAffiliation provides the user's role in the organization. Options include faculty, staff, employee, student, member, affiliate, library-walk-in, and there can be multiple values. eduPersonPrimaryAffiliation provides the primary role, respectively. Detailed specifications for these can be found at https://wiki.eduuni.fi/display/CSCHAKA/funetEduPersonSchema2dot5#funetEduPersonSchema2dot5-eduPersonAffiliation

Multi Factor Authentication

When logging into the service, it is possible to require multi-factor authentication (MFA). In this case, during the login phase, the user is directed to AD authentication (same as O365) to perform the authentication.

Note: Unlike O365 login, in Shibboleth, MFA is remembered for a maximum of three hours, after which it is required again when logging into the service.

There are two ways to implement this:

Require MFA in the Login Request

The service adds an AuthnContextClassRef specification to the login request sent to the IdP, which corresponds to multi-factor authentication. We use the value according to the REFEDS MFA profile, i.e., "https://refeds.org/profile/mfa".

<samlp:RequestedAuthnContext>
  <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
    https://refeds.org/profile/mfa
  </saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>

This allows requiring MFA, for example, only when logging into the administration interface, where a new authentication is requested from the IdP with the desired context.

Set MFA Requirement in the SP Registry

In the SP registry, under the "Technical Details" section, you can turn on the "Require MFA Authentication" option, which requires multi-factor authentication from all users.

Note: In this case, the service must not require any specific AuthnContextClassRef value (see above) or the login will end in error.

Limitations

Multi-factor authentication only works with accounts that are synchronized to cloud-AD (Azure) and are individual accounts. It is not possible to use shared accounts because the authentication methods are personal.

Authentication works at least for HY staff and degree students. It is also largely possible for other personal accounts, excluding limited user accounts. Not all special accounts have been synchronized to cloud-AD (Azure), so please check the situation separately for these accounts if necessary.

Identity Provider metadata

SAML metadata and OIDC configuration for both production and test IdPs can be found from the page IdP metadata.

SAML specific

Service's SAML implementation

Install the SAML2 product in use and ensure that its security updates are installed automatically.

Instructions for installing Shibboleth SP on RHEL/Ubuntu servers can be found in the example guides below.

Installation instructions for other products can be found on their respective pages.

Service Identifier, Entity ID

A unique identifier is assigned to the service, which is usually formed from the service's URL and usually the suffix relating to SAML of implementation used, e.g., "https://service.helsinki.fi/sp".

Certificates

Services linked to SSO must operate over the HTTPS protocol.

In the Shibboleth/SAML integration, it is advisable to use a certificate separate from the service's public SSL certificate. In SAML, the certificate is used only for signing and encrypting messages between the SP and IdP. Using separate certificates eases maintenance, as certificates do not need to be changed at the same time. Additionally, security risks are somewhat different.

Since the certificate is manually specified both in IdP and SP, a self-signed certificate can be used here. The recommended practice is a 4096-bit RSA certificate with a 10-year validity. The certificate should be replaced sooner if it is suspected to have been compromised.

For example, on a Linux server, you can create a certificate and key as follows:
openssl req -new -x509 -nodes -newkey rsa:4096 -keyout sp1-test-shib-key.pem -days 3650 -subj '/CN=sp1.test.helsinki.fi' -out sp1-test-shib-cert.pem
chmod 640 sp1-test-shib-key.pem
chown root:shibd sp1-test-shib-key.pem (Huom. Ubuntussa ryhmä on _shibd)
Certificate rotation

Replacing an existing service’s certificate is done through the SP registry. The replacement has 5 steps to prevent users from experiencing outages. The replacement should start at least 2 weeks before the certificate expires.

  1. A new certificate is added alongside the old one, so that the service signs its messages with the old key but can decrypt messages encrypted with the new one. Instructions for this can be found in Haka’s wiki.
  2. The new certificate is added to the service in the SP registry.
  3. Wait until the new certificate is in use by the IdP and then switch the order of the certificates in the service, so that messages are signed with the new certificate.
  4. Remove the old certificate from the SP registry.
  5. Wait until the certificate removal is implemented in production and then also remove the old certificate from the service.

If you need a faster schedule, contact IdP administration via email. Note that the IdP itself does not mind the outdated certificate and will continue to operate with it. Also, Shibboleth SP does not care, but some SAML SP implementations may stop functioning with an expired certificate.

Logout

Logging out from a single sign-on system is a challenging concept. If the service supports SAML SLO (Single Logout), logging out can be directed to the Logout address used in the SAML implementation. For example, in Shibboleth SP, this is usually "/Shibboleth.sso/Logout". In this case, it must be ensured that the application behind the SAML SP application is also logged out.

If the service does not support SAML2 SLO, the service should log itself out and then direct the user to the IdP's SLO link at https://login.helsinki.fi/idp/profile/Logout, where they will also be logged out from the IdP and given the opportunity to log out from other services.

For example, Shibboleth SP can inform the program about the logout. Instructions for this can be found at https://wiki.shibboleth.net/confluence/display/SHIB2/SLOWebappAdaptation

Example configurations for SAML Services

There are several different SAML implementations available. The most commonly used is Shibboleth SP, which supports Apache and IIS server software, but other implementations that meet the SAML2 specification can also be used.

Below are instructions for implementing a SAML connection with Shibboleth SP. Other applications have their own configuration methods, but the necessary information and principles are generally the same.

Additionally, the Finnish Identity Federation HAKA has general technical guidelines for implementing SAML2 authentication. The same practices also apply when connecting to the University of Helsinki’s Single Sign-On.

OIDC specific

login.helsinki.fi also supports OIDC protocol for login. From the user's perspective, the login process is similar to using SAML, but OIDC does not support single logout (SLO). Information about logging out is not transmitted to the services, and these services are not included in the service listing shown by the login service upon logout.

We recommend using products or libraries certified by the OpenID Foundation for implementing the service.

For basic information on how OIDC operates, see the article at https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1 (part 1 of a 3-part series).

OIDC registration

Dynamic registration is not available and services are registered through the SP Registry.

The SP registry defines general information about the service, the technologies used, and the data that the service is allowed to request.

OIDC attribute requisitions

Some attributes may be requested with scope. Check user attributes page for the list.

Other user attributes must request them as claims. Claims are requested with the claims parameter in the Authorization Request. Requested claims may differ for userinfo endpoint and ID token.

Format for claims value is: { "userinfo": { "uid": null, }, "id_token": { "given_name": null, "family_name": null, } }

Read more from: https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter

OIDC configuration

Most common use case is a web services using authorization code flow and client secret. In this case, authorization is done first, and user information is requested from the token- or userinfo-endpoints. Required SP-registry technical attributes for such use case are:

  • Grant types: authorization_code
  • Response types: code
  • Application type: web
  • Subject identifier: public or pairwise
  • Token endpoint authentication method: client_secret_basic

You can find more information about the required technical attributes in the SP Registry documentation: https://wiki.helsinki.fi/xwiki/bin/view/SO/User%20management/SP%20Registry/#HOIDC

Example configurations for OIDC Services