Doc. Number | Article Title | Effective Date | Version |
FHC-XX | MS Entra Single Sign On | October 04, 2024 |
Basic |
This article was developed to describe the use of Microsoft Entra (formerly Azure) as a single sign-on tool to log into the Forth CRM. It is organized into the following sections:
-
Overview
-
Creating and Setting Up the Forth SSO in Entra
-
Entra User SSO Configuration
-
Configuring the Entra SSO Integration
-
SSO Behavior
Overview
The Forth system offers an enterprise-grade identity access management (IAM) solution called Microsoft Entra (formerly Azure AD) to manage users' digital identities. This was done using a federated identity and Single Sign On (SSO) via Microsoft Entra into the Forth ecosystem. This enables you to maintain a high level of security and access control and improve your security and governance posture and practice.
Creating and Setting Up the Forth SSO in Entra
To begin, create a new Enterprise Application within Microsoft Entra Admin (see below). Read more on how to do this in this article.
Add the necessary users/groups per your organizational setup into the Users & Groups area within the Entra admin (see below).
Under the Single Sign On configuration, edit the Basic SAML Configuration Parameters section as illustrated in the example below.
The reply URL will always be https://ACCTIDENTIFIER.forthcrm.com/login.php. Also, please note the “Identifier (Entity ID)” field, as this value is needed to configure the ForthCRM Entra integration.
In the Attributes and Claims section, pass either the email (usually User Principal) or a separate user-level field attribute for the Forth user ID (numerical ID for the user in CRM).
This information is transmitted by Entra to ForthCRM upon successful identity validation, and is needed to federate the ID and associate it with a user session in ForthCRM.
Finally, note the “Login URL,” as this will be needed later in the process (see the image below).
Entra User SSO Configuration
The ForthCRM can be set up to transmit and verify identity information between the two systems using either the user's email/UPN or the numerical Forth user ID.
IMPORTANT: Configuration must be performed by the Forth Development Team, and a JIRA ticket must be opened for this task.
Configuring the Forth CRM Entra Integration
The Entra integration is built as a Forth add-on that can be enabled at an account level. It is under the SSO Providers section on the "edit accounts" page. The add-on must be enabled for the integration settings page to be available within the account.
The controlling company (the highest-level company within the account) should request the configuration of this integration.
SSO is a domain-level configuration item that applies to all users within an account who try to log in via a specific subdomain of Forth CRM (e.g., mateo.forthcrm.com).
As stated earlier, this domain should always be in the acctidentifier.forthcrm.com format. The SSO will not function correctly if a domain outside of Forthcrm.com is used. If clients want to use their domain, they must set it up to redirect to this Forthcrm subdomain.
Once the add-on is enabled, the Forth CRM integration setup is done via the Entra integration setup page under Integrations (see image below).
On this page, enter the following values into the setting fields:
-
Domain :
acctidentifier.forthcrm.com
This has to match the Reply URL domain or SSO will not work. -
Entity ID: This comes from the Identifier (Entity ID) in Basic SAML Settings within Entra
-
Login URL : This is generated and comes from Entra.
-
Forth SSO Claim Field : Depending on how you want SSO to function, you can select either
Username
orEmail
as an option.-
If Email, the ForthCRM user’s email address has to match the Entra User’s UPN.
-
If Username, the ForthCRM user’s user ID has to be present in the “forthuserid” field within the “Attributes and Claims” section, and that field has to be transmitted as
forthuserid
in the claim. -
If logging in using email, the email has to be unique within the account for SSO to work. Only one user can have an email address associated with an Entra UPN. SSO will fail if the same email is used with multiple users, and an error will be shown.
-
User IDs are unique for every user on the ForthCRM platform, so an SSO failure when userID is selected as the claim field is likely due to the user ID missing on the Entra side.
-
-
Entra can be enabled for specific companies within an account. If configured, only users from these companies can use the integration.
-
If a ForthCRM user goes to a generic login domain, e.g., login.forthcrm.com, they can still log in using their normal username/password. Forth has no way to enforce SSO because it is domain-specific.
SSO Behavior
Users who access this domain are automatically redirected to Microsoft Entra for SSO. Entra handles all items related to identity verification according to how it is configured. Depending on the organization, this may include 2FA/MFA or additional login steps.
If the SSO launch is successful, they are logged in to the CRM seamlessly as the user is mapped via UPN/User ID. Otherwise, Entra launches an error screen providing an error code.
If a user has previously logged in and the Entra session has not expired, the user will be redirected to Entra and then sent back to the CRM with an active session without being put through the Entra login process.
If a user has been suspended or deleted, they cannot use this SSO.
If a user logs out of the CRM, it does not terminate the Entra session; it just logs them out of the CRM
NOTE: Logging in via Entra counts toward billable usage for the specific user and counts toward monthly usage charges. All logins via SSO are logged in the system log.
Article Version History:
Version | Effective Date | Description |
Basic | 10/04/2024 | Initial Release |