What SSO for SuiteCRM 8 involves
The first decision is which authentication mode SuiteCRM 8 will use. The application can sign users in against LDAP (AUTH_TYPE=ldap) or against a SAML identity provider (AUTH_TYPE=saml). The choice determines who can sign in, whether each person needs a local CRM account, and how sign-out behaves. Confirm with your identity team which directory is authoritative for employees and contractors before you set the value, because the CRM will inherit that answer.
Teams usually need this for three reasons. The first is central joiner and leaver control, so that disabling a person in the directory also removes their CRM access. The second is multi-factor authentication enforced at the identity provider, so SuiteCRM does not need its own second factor. The third is audit, where sign-in activity must trace back to a corporate identity. Write these requirements down with the security team first, since each one changes how the LDAP or SAML configuration should be built.
Several parts are harder than they look. Local CRM accounts often already exist, including administrator and integration accounts, and they can keep working with a local password unless you disable or restrict them. The logout gap is significant: per the SuiteCRM 8.7.0+ SAML reference, IdP-initiated logout and POST binding to the logout service are not supported, so signing out at the identity provider does not end the SuiteCRM session. Directory groups also need a documented mapping to SuiteCRM roles and security groups, and you should test that a leaver loses access and a mover's permissions change.
API clients need separate attention. Integrations that call the SuiteCRM API may not use interactive login, so an SSO change can leave them untouched or break them in ways your browser tests will not reveal. Inventory each integration and its authentication method before cutover. Because SuiteCRM is open source and self-hosted, your team or your implementation partner owns the identity integration, including certificates, SAML metadata, the LDAP bind account and the test plan on a staging instance.
Components and settings involved
SuiteCRM 8 single sign-on spans the application login setting, the protocol library, the identity source, local user records and the web tier that carries the login traffic. Each component needs a named owner, because a gap in any one of them blocks sign-in or leaves access open.
AUTH_TYPE login setting
The AUTH_TYPE setting selects the login method for SuiteCRM 8, with ldap or saml as the values relevant to this topic. The team owns the environment configuration that sets it, along with the connection and attribute settings that accompany it. Confirm the value and its companion settings in staging before cutover, because an incorrect setting can lock out administrators who depend on local accounts.
Symfony Security LDAP authenticators
LDAP login in SuiteCRM 8 is built on the Symfony Security LDAP authenticators, which bind to the directory, search for the user and verify the supplied password. The team owns the bind account, search base, user filter and the attribute used to match a directory entry to a CRM user. Use a service account with only the directory rights it needs, and confirm which directory fields the authenticator reads.
nbgrp onelogin-saml-bundle
SAML login in SuiteCRM 8 is built on the nbgrp onelogin-saml-bundle, which builds and validates the authentication requests and assertions exchanged with the identity provider. The team owns the service provider metadata, the signing certificates, their rotation schedule and the entity and callback URLs. Mismatched values usually surface only at sign-in, so compare them against the identity provider registration before go-live.
Directory or identity provider
The identity source is Active Directory or another LDAP directory for LDAP login, or a SAML identity provider such as Microsoft Entra ID or Keycloak. The team owns group membership, account disabling and the attributes released to SuiteCRM. Logging out at the identity provider does not end the SuiteCRM session in 8.7.0 and later, so plan session timeouts and user guidance.
Local SuiteCRM user records
Even with external login, SuiteCRM keeps its own user records, which hold roles, security group membership, record ownership and preferences. The team owns the process that creates, updates and deactivates these records when a person joins, changes role or leaves. Review how a disabled directory account is reflected locally, and decide which local administrator account stays available during an identity outage.
Web server and reverse proxy
SAML sign-in returns the browser to SuiteCRM at a callback endpoint, so the public hostname, TLS termination and any reverse proxy must pass the request through unchanged. The team owns the Apache 2.4 virtual host or proxy rules, forwarded headers and the URL registered with the identity provider. Test the full redirect cycle through the same proxy path that users will use.
Decisions and trade-offs
Each row sets out one identity design choice for SuiteCRM 8 sign-in, when that option fits and what it costs your team to run.
| Decision | Option | When it fits | Operational cost |
|---|---|---|---|
| Authentication source | LDAP (AUTH_TYPE=ldap) | Users sign in with Active Directory or LDAP credentials and SuiteCRM can reach the directory directly. | Store, rotate and protect the bind account, keep the directory path open, and handle MFA outside this login flow. |
| Authentication source | SAML (AUTH_TYPE=saml) | An identity provider such as Microsoft Entra ID or Keycloak already enforces sign-in policy and MFA. | Maintain IdP metadata and certificates, keep attribute mapping current, and retest after every IdP change. |
| Identity connection | Direct IdP connection or broker such as Keycloak | Direct suits one identity source. A broker suits several sources, such as LDAP plus a cloud IdP, feeding one SuiteCRM trust. | A direct link is simpler to run. A broker adds a service to patch, back up and debug when logins fail. |
| Account creation | Just-in-time user creation | Anyone with a valid directory or IdP login should get access on first sign-in without an admin step. | Accounts appear automatically, so offboarding and role checks need a recurring review. Confirm creation behavior for your release. |
| Account creation | Pre-provisioned accounts | Access must be approved before first login, for example where CRM records are regulated or commercially sensitive. | An admin creates and changes every account, and SuiteCRM records can lag behind directory changes. |
| Role mapping | Roles from directory groups or SAML attributes | Group membership already reflects job function, and team moves should flow from the directory without manual edits. | Group names or claim values must match SuiteCRM roles and security groups, and each mapping needs testing. |
| Break-glass access | Keep local admin accounts | A directory or IdP outage must not lock every administrator out of the CRM. | Local passwords to store, rotate and monitor, plus a documented procedure for when they may be used. |
| Logout | Accept the logout limitation | Users sign out inside SuiteCRM, devices are personally assigned and the risk of a lingering session is low. | IdP sign-out does not end SuiteCRM sessions, so offboarding still needs a separate step and session timeouts need review. |
| Logout | Add a process-level control | Shared workstations or regulated data where a departed user's open CRM session is unacceptable. | A written procedure, tighter session timeouts and periodic checks that staff follow the procedure. |
Build sequence
Seven ordered steps take SuiteCRM 8 from a supported staging build to a tested LDAP or SAML sign-in with a recovery path and documented settings.
Confirm the version and compatibility
Confirm the SuiteCRM 8 release you plan to deploy, then check its PHP, Apache and database combination against the compatibility matrix for that release. Record the versions in staging next to the matrix entry you checked. The step closes when the staging host runs a combination the matrix lists and a written compatibility record is signed off.
Choose the authentication type
Choose LDAP, enabled with AUTH_TYPE=ldap, or SAML, enabled with AUTH_TYPE=saml, based on where your users are authoritative, such as Active Directory or an identity provider like Microsoft Entra ID or Keycloak. Collect the directory or IdP metadata, the attributes to map and the group names that will drive roles. The step closes when a signed-off inventory lists each attribute and group with its owner.
Configure the authenticator in staging
Enter the chosen authenticator settings in a staging instance only, following the reference for your authentication type. Keep bind credentials, certificates and client secrets out of version control and out of shared chat. The step closes when a test user is sent to the directory or identity provider from the login page and returns to SuiteCRM with an active session.
Map attributes to user fields and roles
Map directory or SAML attributes to SuiteCRM user fields such as username, email address and name, and map group membership to the security groups and roles that govern module access. An administrator checks each mapping against the inventory from the previous step. The step closes when a test account shows the expected fields and no unexpected group memberships.
Set up a break-glass local admin
Create a local administrator account that does not depend on LDAP or SAML, store its credentials in your approved secrets store, and limit its use to documented emergencies. The step closes when a person outside the admin team signs in with it on staging, which shows the recovery path works if the identity provider or directory is unavailable.
Test pilot sign-in and first-login roles
Have a pilot group sign in on staging and record the security group each person receives on first login. Remove one test user from the directory group and confirm the change applies at the next login. Also test sign-out, because SAML in SuiteCRM 8.7.0 and later does not support IdP-initiated logout. The step closes when each pilot user lands in the expected group and the logout result is recorded.
Document the configuration and secrets
Write a runbook covering every authentication setting, the attribute and group mappings, the break-glass procedure, the logout limitation, and where each secret is stored with its owner and rotation contact. The step closes when a second administrator can rebuild the staging login from the runbook without help from its author.
How to verify and fail safely
Verify the login path end to end on a staging instance before any production change, and record the result of each test so the team can repeat it after every certificate rotation, IdP change or SuiteCRM upgrade. Run the first set of tests against a staging copy that uses the same AUTH_TYPE setting, identity provider metadata and directory structure as production. Confirm the staging directory contains test accounts placed in each group that maps to a SuiteCRM role or security group.
For each directory group, test a successful login and a failed login with a wrong password. Then sign in with an account that is disabled in the directory and confirm SuiteCRM refuses access, including for any session that was already open. After first login, check which roles and security groups the new user received, because group mapping is the most common source of excess access. Repeat the check after changing a group membership in the directory to confirm the change takes effect as your design expects.
Test the failure modes before go-live. Rotate the SAML signing certificate or metadata on staging and confirm the new metadata is picked up and old assertions are rejected. Set a short session lifetime, wait for it to expire, and confirm the user is asked to authenticate again. Then stop the identity provider or block the LDAP server and confirm that the break-glass local account still signs in, and that the team knows who holds its credentials and where access is logged. Confirm the expected behavior with your SuiteCRM partner and your own security team before relying on it.
Test the logout limitation directly. Documented SuiteCRM 8.7.0 and later SAML behavior states that signing out at the identity provider does not end the SuiteCRM session, so sign in, sign out at the identity provider, and confirm the SuiteCRM session stays active. Then confirm the compensating control your team documented, such as a shorter session timeout, a SuiteCRM logout step in the user procedure, or a monitored offboarding task. If the control is not in place, the test has failed and go-live should wait.
Security and access control
These cards cover the decisions that determine whether SuiteCRM SSO holds up under review. Each one names a control to set up and a check to repeat after go-live.
Keep directory and signing secrets out of source
The LDAP bind password, the SAML signing and encryption private keys, and the SuiteCRM application secret belong in a secrets store or the server environment, never in the Git repository or the .env file committed with the code. Confirm which values SuiteCRM reads from the environment in your release, and check that the repository history and CI logs contain none of them.
Use a least-privilege bind account
SuiteCRM needs only enough directory rights to search for the users who sign in and read the attributes it maps to fields. Create a dedicated, read-only service account scoped to the relevant organizational units, and confirm that it cannot write, reset passwords or enumerate unrelated directory branches.
Enforce TLS to the directory
LDAP traffic carrying the bind credential must be encrypted, using LDAPS or StartTLS with the certificate chain of your domain controllers trusted by the SuiteCRM server. Test that a connection with certificate verification disabled fails, so the configuration cannot silently fall back to cleartext or an unverified peer.
Validate SAML signatures and audience
Configure SuiteCRM to require signed assertions or responses from the identity provider, verify the signing certificate you registered, and check that the audience restriction matches your SuiteCRM entity ID. Test with a response that has a tampered attribute or a wrong audience and confirm that login is rejected.
Limit which groups receive admin roles
Mapping an identity provider group to SuiteCRM administrator rights is the most consequential setting in the integration. Restrict admin mapping to a small, named group owned by the security team, review membership on a schedule, and confirm that broad groups such as all staff cannot grant administrative access through attribute mapping.
Protect the local break-glass account
Keep one local administrator account that does not depend on LDAP or the identity provider, so the team can recover if the directory or SAML configuration fails. Store its password in a sealed vault, restrict its use to documented recovery, enable alerting on each login, and test that it still works in a staging instance.
Review API credentials that skip SSO
API clients and integrations authenticate with their own credentials and tokens, so they bypass the interactive SSO login and may outlive the employee who created them. Inventory every API user and token, assign each to a service identity with minimal roles, set expiry or rotation, and remove credentials that no longer map to a running integration.
Stay on supported SuiteCRM and PHP releases
SSO code paths depend on the SuiteCRM release and the PHP runtime beneath it, so an unsupported version can leave a known flaw in the login path. Check the SuiteCRM compatibility matrix for the PHP version you run, plan to apply patch releases, and confirm the release line you choose is still receiving security fixes. Server hardening beyond this login path is covered in the SuiteCRM security hardening topic.
What drives effort and cost
The table lists the factors that most change the size of a SuiteCRM SSO with SAML and LDAP project, how to keep each one under control, and what to ask for in a quote.
| Driver | Why it changes effort or cost | How to keep it down |
|---|---|---|
| Identity sources and directory domains | Each LDAP directory, Active Directory forest or SAML identity provider adds its own attribute mapping, certificate handling, test accounts and failure cases. Multiple domains multiply login paths. | Choose one identity provider as the single source of sign-in, with LDAP used only for directory lookups where needed. Confirm the domain list before build. |
| Group-to-role mapping complexity | SuiteCRM roles and security groups must be assigned from directory groups or SAML attributes. Many nested groups or exceptions mean more mapping rules to design, test and document. | Agree a role matrix before build that maps each SuiteCRM role to one directory group. Keep exceptions in the matrix, not in ad hoc rules. |
| Number of SuiteCRM instances | Production, staging and test instances each need their own SSO registration, redirect URLs, certificates and test users. Every instance is verified separately. | Register SSO on staging first and promote the same configuration to production. Ask whether test instances need full SSO or only local accounts. |
| MFA and conditional access changes on the identity provider | MFA prompts, device checks and conditional access rules live in the identity provider. Changing them affects SuiteCRM sign-in and needs testing with real user paths. | Decide before build which policies apply to SuiteCRM. Keep the policy change list short and test each one against a pilot group. |
| Existing local SuiteCRM accounts to reconcile | Accounts created locally may not match directory identities. Duplicates, unused admin accounts and mismatched email addresses require review and a decision on each. | Export the local account list early. Agree which accounts stay local (for example, a break-glass admin) and which map to directory users. |
| Custom login pages or branding | SAML and LDAP login flows can be customized, but each change needs testing after every SuiteCRM minor release and every identity provider change. | Limit changes to the standard login experience unless a business need is documented. Ask the quote to separate branding work from core SSO work. |
| Integration with API clients | Legacy API authentication and service accounts used by integrations may not follow the same login path as users. Each client needs its own credential and test plan. | Inventory all API clients before build. Decide which ones move to new authentication and which need a separate, documented credential. |
| Compliance evidence | Access control, logging, joiner and leaver tests and session behavior must be documented for an assessor. Evidence collection adds review time and recurring tasks. | Agree the evidence list in the scope. DeployOpen prepares systems, controls and evidence for assessments, but independent auditors issue any report or attestation. |
Frequently asked questions
How much effort does SSO add to a SuiteCRM implementation?
The effort depends mostly on how many identity sources you connect and how closely your directory and identity provider match what SuiteCRM needs. A single LDAP or SAML connection with clean attribute mapping is a bounded task. Mapping groups to SuiteCRM security roles, deciding what happens to accounts that already exist, keeping a local login for emergency access, and testing logout and session behavior all add time. Other drivers include the number of environments, the identity team's change approval process and the depth of testing your security team expects. Ask any partner, including DeployOpen, for a written scope that lists each identity source, attribute, group mapping, environment and test case, then compare quotes against that list.
Can our team set up SuiteCRM SSO in-house using the documentation?
Yes, if your team has administrators comfortable with web server configuration, application settings and directory or identity provider administration. SuiteCRM publishes configuration references for LDAP and for SAML, and the login method is selected with AUTH_TYPE=ldap or AUTH_TYPE=saml. The harder work is usually outside the application: agreeing attribute names with the identity team, testing sign-in in a staging instance and handling existing user records. Use the reference that matches your SuiteCRM version, because SAML behavior changed at 8.7.0. Teams without this mix of skills often bring in a partner for the integration and keep upgrades in-house.
Should we use LDAP or SAML for SuiteCRM 8 login?
Choose LDAP when your users are managed in a directory such as Active Directory or another LDAP service that SuiteCRM can reach directly, and your security team accepts SuiteCRM checking passwords against that directory. Choose SAML when you want an identity provider to handle sign-in, multi-factor authentication and access policies, with SuiteCRM receiving a signed assertion. SuiteCRM 8 supports both, enabled with AUTH_TYPE=ldap or AUTH_TYPE=saml. Organizations using Microsoft Entra ID or Keycloak often find SAML fits better because the identity provider already enforces policy. Confirm network paths, certificates and attribute release rules in your environment before deciding.
What happens to the SuiteCRM session when users log out at the identity provider?
The SuiteCRM session stays active. The SuiteCRM 8.7.0 and later SAML implementation does not support IdP-initiated logout or POST binding to the logout service, so signing out at the identity provider does not end the SuiteCRM session. The session remains until it expires or the user logs out of SuiteCRM. Plan for this in your user guidance and security policy: tell users to log out of SuiteCRM explicitly, set session lifetimes that match your risk tolerance, and document the residual risk for shared workstations. Test the behavior in staging with your actual identity provider settings, since the result depends on how that provider sends logout requests.
Does SAML work with Microsoft Entra ID or Keycloak for SuiteCRM?
In general terms, SuiteCRM 8 can use SAML with identity providers that support the protocol, and Microsoft Entra ID and Keycloak are commonly deployed providers for this pattern. Exact settings, including entity IDs, certificate handling, attribute names, signing requirements and logout configuration, depend on your tenant or realm and your SuiteCRM version. Confirm each one in your own environment before go-live. Create a test application in the identity provider, compare its metadata and attribute claims against the SuiteCRM SAML reference, and validate sign-in with a test user from each group that needs access. Treat a working lab login as a starting point and confirm the rest in staging.
How does legacy API authentication work alongside SSO in SuiteCRM?
SSO changes how people sign in to the user interface, so integrations that authenticate with their own credentials often keep working, but each one still needs checking. Inventory every integration and identify which ones depend on a named user account that follows the login path. Confirm in the documentation for your SuiteCRM version how API authentication is configured when AUTH_TYPE is set to ldap or saml. Keep service accounts separate from named users, with their own secrets and a rotation schedule. After enabling SSO, test each integration in staging, including error handling when credentials expire. Do not assume a legacy endpoint behaves the same way until you have tested it.
How DeployOpen approaches SuiteCRM identity work
DeployOpen plans, builds, documents and supports SuiteCRM 8 login against your LDAP directory or SAML identity provider inside infrastructure you control. Each engagement starts from a written scope that sets out the identity sources, the login path and the logout behavior you will accept.
How we scope
- Confirm which login path SuiteCRM 8 will use, LDAP or SAML, and which directory or identity provider is the source of truth.
- Record which user attributes, groups and roles must map into SuiteCRM security groups and roles before any build starts.
- Agree in writing how the documented SAML logout limitation will be handled for users, support staff and the identity provider team.
How we build
- Configure the LDAP or SAML settings on a staging SuiteCRM 8 instance first, then test sign-in with representative test accounts.
- Verify how the legacy API authentication path and any integrations that depend on it behave once the login method changes.
- Review existing customizations and the public legacy folder before changes are applied, because customizations can affect login behavior.
How we hand over
- Deliver a written configuration record covering identity settings, attribute mapping, certificate or bind account ownership and rollback steps.
- Walk your identity and CRM administrators through sign-in, provisioning, deprovisioning and the logout limitation with recorded test results.
- Document the runbook for certificate renewal, directory changes and when to rerun sign-in tests after a SuiteCRM minor release.
How we support
- Retest SSO sign-in after each SuiteCRM minor release, which arrives roughly every eight weeks, before it reaches production.
- Review identity settings whenever your directory, identity provider or certificates change, as part of an ongoing retainer if you choose one.
- Ongoing support, upgrades and continuous testing are available as retainers, and the scope of each can be agreed in writing.
