Single Sign-On using SAML

Here, you can find all there is to know about Single Sign-On within your Happeo intranet and how it is accomplished using SAML.

What is Single Sign-On?

Happeo only supports single-sign-on (SSO), an important cloud security technology that reduces all user application logins to one login. With SSO, users can already login with their workplace credentials. This offers greater protection from unauthorized users accessing sensitive company data while allowing full convenience to employees.

In more detail, with SSO authentication several different application login screens are combined into one. The advantage of SSO is that users only need to enter a one-time username and password to access all websites, software, or apps. There are 6 steps to understand:

1. The user arrives on the website (app or software) they want to use
2. The site sends the user to a central SSO login tool and the user needs to sign in with a username and password
3. The SSO domain authenticates username and password, validates the user, and creates an authentication token that remembers that the user is verified
4. The user is sent back to the original site and the token acts as proof that they’ve been authenticated
5. Any app the user accesses will check with the SSO service
6. This grants the user access to associated websites, apps, or software that share the central SSO domain

What is SAML authentication?

Happeo supports SAML (Security Assertion Markup Language), an open standard for exchanging authentication and authorization data between parties. SAML enables the use of Single Sign-On and makes users’ lives easier and safer because one set of credentials can be used to log in to many different websites.

In general...

Happeo uses SSO to ensure strong protection against unauthorized users and the way in which Happeo does this is through SAML. 

How to setup SSO with SAML

Custom domain

The single sign-on (SSO) with SAML needs to have a custom domain. To get a custom domain for your Happeo instance, please contact our customer success representatives.

SAML setup

Happeo uses SAML 2.0. Using SAML SSO terminologies, Happeo acts as a Service Provider (SP). The company user directory acts as an Identity Provider (IdP).

As explained in this PDF, Happeo uses Metadata Instance Caching for better performance. To update the SAML metadata file or replace it, please consider these options:

• Latest Certificate Retention: Keep only the latest certificate in your directory and store a backup of the old XML file locally or elsewhere until you confirm the new SAML XML metadata file is working correctly
• Renewed SAML Metadata URL with the Same URL: If you keep the same SAML metadata URL in Happeo, ensure the metadata XML file contains either the 'validUntil' or 'cacheDuration' attribute. These attributes signal to our system that a certificate has changed, and our automatic detection system will seamlessly switch to the new certificate. Without these attributes, our system may not notice the change until our cache refreshes every 4 hours
• Distinct SAML Metadata URL: Alternatively, use a different SAML metadata URL that points to the new certificate and ensure it is accessible

Following these guidelines will improve the efficiency and reliability of our service provider's interaction with SAML metadata files and ensure application uptime. Not having a working certificate could prevent users from logging in.

More information about SAML 2.0 can be found by clicking here.

Happeo Admin panel setup

In the Happeo admin panel, two inputs will need to be filled:

• The URL for the SAML 2.0 Metadata file of the IdP
• The SAML entityID property of that metadata

Company user directory setup

The Identity Provider will usually need two or more of the following:

• The entityID of the SP (this may be called Audience on some IdPs) - com:happeo:saml:sp
• The ACS URL - https://login.happeo.com/saml/SSO
• The SP metadata URL - https://login.happeo.com/saml/metadata
• The Sign-on URL - https://login.happeo.com/saml/login

In addition, the IdP needs to provide the user email address to the SP. This is done through attribute mappings, and the email should be mapped to the following property:

• urn:mace:dir:attribute-def:mail

Important!