Single sign-on is an authentication process that allows for the same pair of credentials (i.e., username - password) to be used across multiple systems. Single Sign-on can also be used for allowing users to sign in to a network of "connected" systems through a single log-in.
eFront provides many options for implementing both scenarios:
- By using SAML 2.0
- By using LDAP (or Active Directory)
- By using the REST API
- By using a cookie
- By using a plugin
Note: In case you are setting up SAML only for a specific branch, then this branch needs to have its own branch URL (see also this article). If instead, you want branches to inherit the main branch SAML settings, this happens by default. In this last case, and if the branches have their own sub-domain, then make sure each branch URL is included in the URLs allowed by your SAML provider.
A. SAML 2.0
eFront supports Single Sign-On (SSO), a process that allows users to authenticate themselves against an external Identity Provider (IdP) rather than obtaining and using a separate username and password handled by eFront.
To let you provide single-sign-on (SSO) services for your domain, eFront works as a Service Provider (SP) through the SAML (Secure Assertion Markup Language) standard.
What you need is a SAML Identity Provider (IdP) to handle the sign-in process and provide your users' authentication credentials to eFront. When eFront users authenticate themselves through your SAML IdP, their account details are handled by the IdP. Any changes made to those details (i.e., first name, last name, email) are synced back to eFront.
To set up SAML SSO on your eFront domain, go to the SAML tab on the System Settings > Integrations > Single Sign On page and fill in the following values:
Identity provider (IdP): Your Identity Provider's (IdP) URL.
Certificate fingerprint: The SHA-1 SAML certificate fingerprint provided by your IdP.
Remote sign-in URL: The remote sign-in URL of your IdP where eFront redirects users to sign in.
Remote sign-out URL: The remote sign-out URL of your IdP where eFront redirects users to sign out.
TargetedID: The variable that holds the user's username (log-in).
First name: The variable that holds the user's first name.
Last name: The variable that holds the user's last name.
Email: The variable that holds the user's email.
- First, go to Home > Extend profile and create new columns for Users (for a step-by-step guide, see this article).
- For each new column, type the corresponding SAML variable in the Name field.
- Finally, go to the SAML settings page, and type the column names as a comma-separated list in the Custom fields field.
The image below illustrates an example of a SAML setup where simplesaml is used as an IdP server.
In the following example, we assume that our ADFS IdP uses the domain name “adfs2.efrontlearning.com” and our eFront installation uses the domain name “saml.pro.efrontlearning.com”.
Step 1: Configure ADFS 3.0
Click to Start the Server Manager. From the tools option, choose AD FS Management to launch the AD FS management console.
Right-click Service and, from the context menu, click Edit Federation Service Properties…
The General tab contains the Federation Service Identifier which is necessary for the SSO setup. In our example, it's http://adfs2.efrontlearning.com/adfs/services/trust.
eFront requires a PEM format certificate, so you have to convert your certificate from DER to PEM format. To do that, you can use any available tool or an online application like sslshopper.
Step 2: ADFS 3.0 Relying Party Trust Configuration
Now you have to define the eFront endpoints in your ADFS, either manually or by importing the metadata XML provided by eFront. We recommend using the XML file because it's easier.
To get the metadata XML file, sign in to eFront and go to the SAML tab on the Home > System settings > Single Sign On page. In the SP Metadata XML section, there's a URL that looks like this: http://saml.pro.efrontlearning.com/saml/module.php/saml/sp/metadata.php/efront-sp. Copy the URL and paste it into your browser to download the "eFront-sp" file that contains the following XML code:
<?xml version="1.0"?> <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="saml.pro.efrontlearning.com"> <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol"> <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://saml.pro.efrontlearning.com/saml/module.php/saml/sp/saml2-logout.php/efront-sp"/> <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://saml.pro.efrontlearning.com/saml/module.php/saml/sp/saml2-logout.php/efront-sp"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://saml.pro.efrontlearning.com/saml/module.php/saml/sp/saml2-acs.php/efront-sp" index="0"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="http://saml.pro.efrontlearning.com/saml/module.php/saml/sp/saml1-acs.php/efront-sp" index="1"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="http://saml.pro.efrontlearning.com/saml/module.php/saml/sp/saml2-acs.php/efront-sp" index="2"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" Location="http://saml.pro.efrontlearning.com/saml/module.php/saml/sp/saml1-acs.php/efront-sp/artifact" index="3"/> </md:SPSSODescriptor> <md:ContactPerson contactType="technical"> <md:GivenName>Periklis</md:GivenName> <md:SurName>Venakis</md:SurName> <md:EmailAddress>firstname.lastname@example.org</md:EmailAddress> </md:ContactPerson> </md:EntityDescriptor>
Then, return to the AD FS management console, right-click Trust Relationships > Relying Party Trusts and, from the context menu, choose Add Relying Party Trust…
C. SAML 2.0 with OneLogin as IdP
Sign in to your OneLogin account and go to Apps > Find Applications. In the search field, type SAML Test Connector (IdP w/attr) and press Enter. From the search results, select SAML Test Connector (IdP w/attr) and click Add.
Go to the SSO tab to get the necessary values for your integration with eFront, as illustrated in the following screenshot. To get the Certificate fingerprint, click View Details, right below the X.509 Certificate field.
Go to the Configuration tab and, assuming that your valid eFront URL is "pro.localhost", fill in the following values:
- Audience: pro.localhost
- Recipient: https://pro.localhost/saml/module.php/saml/sp/saml2-acs.php/efront-sp
- ACS (Consumer) URL Validator: ^https:\/\/pro\.localhost\/saml\/module\.php\/saml\/sp\/saml2-acs.php\/efront-sp$
- ACS (Consumer) URL: https://pro.localhost/saml/module.php/saml/sp/saml2-acs.php/efront-sp
After configuring your OneLogin account, sign in to eFront, go to the SAML tab on the Home > System settings > Single Sign On page and configure your IdP settings exactly as illustrated:
After your SAML setup is complete, a link to Sign in with Saml must appear on your eFront index page.
Note: If most of your users log in via SAML, you can check Bypass the default sign in screen and send users directly to the IDP's SAML signin page to redirect users from the eFront log-in page to the SAML log-in page. Users can still access the eFront log-in page at http://[your efront domain]/start/op/login.
Note: eFront allows you to configure a different SAML SSO setup for each branch. To do that, go to a branch page from Home > Branches, click Settings and, from the drop-down list, choose SAML. After you finish the SSO setup, branch members can log in through the branch SAML IdP instead of the branch log-in URL.
Note: In any case, eFront does not initiate a full-scale synchronization of data. Instead, it pulls information on each user that tries to sign in for the first time and limits this information to the absolutely necessary fields. Also, know that eFront does not store user passwords, but performs authentication against the AD itself (in the case of SAML, it doesn’t even transmit credentials).
In the LDAP API case, the data is configured in the connection settings screen; there is also a possibility for someone to use the connection credentials stored in the system to perform additional queries on the LDAP server. This can be controlled by limiting the permissions of the user that's used to perform the queries. For example, if you create a user that has access to a specific part of the LDAP tree, and to specific fields of the entries found in this subtree, then you can guard your data against any misuse.
In the case of SAML 2.0, instead, the data set is limited by the protocol, as SAML is used to perform the authentication and grant access to eFront.
The above API call returns a URL that can be used on a single instance to sign a user in without a username and password.
Note: A complete guide to using the eFront REST API can be found here.
If signing in a user automatically requires some process not covered by the system, the required functionality can be implemented with a custom plugin that calls the User::login function to do the sign-in.
Note: A comprehensive guide to creating custom plugins can be found here.