The objective of this article is to explain the HEFLO solution and the integration of authentication with identity providers using the SAML protocol (SAML 2.0). This article reviews the SAML integration architecture overview, explains in detail how to configure the service provider (HEFLO) for SAML, and shows an identity provider (ADFS) configuration example.
Integration architecture
** After the SAML response, HEFLO creates the local user data if it is the first authentication procedure or authenticates, if it is an existing user based on users information, and assigns the appropriate OAuth permissions.
Service Provider Configuration (HEFLO)
To configure HEFLO as a service provider for SSO integration, you need to fill in the SSO addresses at: https://app.heflo.com/Auth/Manage.
Click on “Configure SSO” and fill in the “Address” field with the SAML information:
Identity provider configuration
Once the Service Provider Configuration on HEFLO is completed, we must also configure the identity providers.
This article introduces the service provider URL and the fields that our integration should receive as claims on the SAML integration, and then shows examples of configuring those claims in some identity providers.
Region | URL |
Ireland | https://eu-west-1-prod-auth.heflo.com/Saml2 |
São Paulo | https://sa-east-1-prod-auth.heflo.com/Saml2 |
Table 1: List of SAML HEFLO URLs by service region
The service URL is used in the identity provider configuration, the URL above provides the SAML2 metadata to configure the integration.
To perform the integration, you must at least return the email field that will be requested and the user id.
Domain name | Mandatory | Several | Claim ARN |
Name identifier | Yes | No | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier |
First name | No * | No | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name |
Last name | No * | No | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname |
Role | No | Yesi | http://schemas.microsoft.com/ws/2008/06/identity/claims/role |
Yesi | No | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
Table 2: List of fields used on SSO integration. ( * at least one of the names fields is required)
Active Directory Federation Services (ADFS)
Active Directory Federation Services (ADFS) is an easy-to-integrate form of Active Directory LDAP implementation, providing Web SSO integration using SAML 2.0.
This article does not explain how to configure Active Directory or even how to install the ADFS service. This article explains how to configure permissions and adding relying party trust for HEFLO (as a service provider).
Firstly, on the ADFS control panel, navigate to the Relying Party Trusts screen:
On the Relying Party Trusts click on “Add Relying Party Trust…” and select the option “Claims aware”:
In the next step, provide the federation metadata address (with the appropriate HEFLO address shown in Table 1) to automatically import the service provider configuration:
After confirming the data source, enter a display name for the connection in the next step and proceed to the next step. In the next step, it is possible to configure the access control policy for this integration. This article will discuss only two simple configurations, the first where the integration allows everyone to use and therefore connect to the service provider, and the second where only a specific group is allowed.
To allow everyone to use this integration, simply select the first option “Permit everyone” and proceed to the next step.
In order to restrict access to a specific group, scroll down the access control policy control, select the “Permit specific group” option, then select the group from the “Policy” screen:
The next step is simply to validate the parameters. Then you have to confirm the configuration of the integration:
After this step, the claim mapping needs to be configured, where the minimum configuration for the mandatory “Name Identifier” claim will be demonstrated.
First, we add a transform claim rule for the Identifier “Name identifier”:
We need to configure incoming type as email address and outgoing claim type as name id. The claim format must be Email.
Important: The user must have a registered email to be able to login to the tool.
To map claims such as email address, it is possible to use simple claim mapping “Send LDAP attributes as claims” with the following configuration :
After validating all the data, the configuration is complete and single sign-on can be performed via the URL previously configured on HEFLO, in this example: https://mycompany.heflo.com.