Why teams host the EspoCRM customer portal on its own domain
Teams host the EspoCRM customer portal on its own domain when they want customers to sign in at a branded address, such as a support or account address, instead of the internal CRM host that staff use. The portal is the customer-facing part of the same EspoCRM instance, so the separate address changes how the public name resolves, which certificate the browser sees and how the web server routes requests. Nothing about the data model changes, but the entry point customers and their security teams see does.
A separate domain adds work in three places. In DNS, you create a record for the portal name that points to the same server or load balancer as the CRM. For TLS, the certificate must cover the portal name, so it is a new certificate request or a new name on an existing one. On the web server, the virtual host or server block must answer for the portal name and serve the same EspoCRM application, and the portal URL configured in EspoCRM must match the address customers type. Confirm the exact portal URL setting, the portal domain behavior and any portal-specific authentication options in the documentation for your EspoCRM version, since portal role capabilities and settings have changed between releases.
Keep the portal on the main domain when the customer base is small, when staff and customers share one identity provider and login page, or when the team has no operational capacity to manage an extra certificate and DNS record. A separate domain is worth the extra moving parts when customers should see a brand that is not yours internally, when access rules or IP restrictions must differ for external traffic, or when security reviews require the customer entry point to be isolated from the staff console.
Portal domain options and when each fits
This table compares three ways to give customers a portal address: the main instance domain, a dedicated portal subdomain on one instance, and a separate instance for customers. Read each row against your DNS, certificate, web server and maintenance responsibilities, then pick the option that matches how much isolation your customers and auditors expect. The main takeaway is that a subdomain adds DNS and certificate work but keeps one codebase to maintain.
| Factor | Main instance domain | Dedicated portal subdomain, one instance | Separate instance for customers |
|---|---|---|---|
| Typical use | Small teams with few customers who accept a shared address | Branded customer address with staff and portal users on one platform | Strict separation of customer data and admin access from staff systems |
| DNS records | No new record beyond the existing host | One extra A or CNAME record for the portal host, pointing to the same server | Records for a second host, often on separate servers or load balancers |
| TLS certificates | Existing certificate covers the address | Certificate must cover the portal hostname, for example through a SAN or wildcard, to confirm with your CA | Separate certificate and renewal process for the second instance |
| Web server server blocks | One block, no portal-specific routing | Additional server_name entry in Nginx or Apache, with the same document root and PHP setup | Full second server block and PHP-FPM pool, plus its own logs |
| Portal authentication | Portal users sign in on the same login page as staff | Portal-specific authentication provider can be considered, to confirm in the EspoCRM OIDC and portal docs | Separate user base and identity settings, reducing shared sign-in paths |
| Session and cookie scope | Cookies shared with staff sessions on the same host | Cookies scoped to the portal host, to confirm in your environment before launch | Cookies fully separate from staff sessions |
| Maintenance effort | Lowest, one instance to patch and back up | Moderate, one instance but more routing and certificate checks at each upgrade | Highest, two instances to patch, back up, upgrade and monitor |
| Data separation | Shared database and file storage | Shared database and file storage, controlled through roles and portal access | Separate database and storage, with its own backup and restore scope |
| Confirm before choosing | Whether portal users can see only their own records under your roles | Portal default URL setting and any extra host list in the server configuration docs | Licensing and hosting cost of a second instance, and whether your auditors accept shared infrastructure |
How the default portal URL and portal settings connect
EspoCRM builds the default portal address from the instance's own site URL and the portal's identity, so the portal link a customer sees depends on how the application believes it is reached. When a team moves the portal to its own hostname, it has to check the settings that feed that link, not only the DNS record. In the server configuration documentation for the deployed version, confirm the exact setting names that control the portal URL and any portal-specific base address, along with how the portal is identified within the instance. Names and behavior can differ between releases, so the check should be run against the version in production, not against a remembered setting.
The reverse proxy must send requests for the portal host to the same EspoCRM application that serves the internal host, with the same document root and PHP handling. A second virtual host that points at a different directory or a separate copy of the code creates two sessions, two sets of cache files and two sets of background job settings, which is a common source of confusion. Keep one code base and one database, and route the portal hostname through the same server block or container service that handles the main hostname, forwarding the original host header so the application builds the correct links.
Before go-live, test three things: that a portal link generated inside EspoCRM uses the new hostname, that a portal user who signs in from that hostname lands on the portal and not the staff interface, and that the certificate covers the portal name on every path a customer will use. A mismatch in the base URL often shows up only in emailed links such as password resets or invitations, so send a test message from a portal user and open the link from outside the office network. Record the settings you changed so that a later upgrade or proxy change does not silently revert them.
Nginx and Apache configuration for a portal domain
On Nginx, the portal hostname usually gets its own server block that points to the same document root as the main instance, which is the public directory of the EspoCRM installation. The block terminates TLS for the portal name, passes PHP requests to the PHP-FPM socket used by the main site, and applies the same rewrite rules so that portal routes resolve to the same front controller. Because the application decides which interface to show from the host name, the block should not serve different files or a separate copy of the code.
- Server name and certificate: Give the block the portal hostname in
server_nameand point the certificate directives at a certificate that covers that name, whether issued by Let's Encrypt or your own certificate authority. - Shared root and PHP handling: Use the same
rootand the same PHP-FPMfastcgi_passtarget as the main instance, so both hostnames run the same code and configuration. - Rewrite and internal paths: Keep the front-controller rewrite used by the main instance and keep the deny rules for internal directories, so the portal block does not expose files the main block protects.
- Redirects and HTTP: Redirect port 80 traffic for the portal name to HTTPS, and confirm that the WebSocket location, if you run one, is defined for the portal hostname too.
- Upload size and timeouts: Match
client_max_body_sizeand timeout values to the main instance so portal users can attach files and submit forms without hitting limits set on only one block.
After reloading Nginx, test the portal hostname with a portal user account and check that the main and portal blocks return identical headers for shared assets. Exact directives are in the EspoCRM server configuration docs.
On Apache, the portal hostname is served by a second VirtualHost that matches the portal ServerName and uses the same DocumentRoot as the main site. The virtual host must allow overrides so that the .htaccess rewrite rules in the public directory apply to portal requests, and the PHP handler and modules must be the same as those used by the main instance. The main difference from Nginx is that Apache reads rewrite behavior from the directory context, so the Directory block for the shared root has to be defined consistently for both hosts.
- Virtual host and name matching: Create a
VirtualHoston port 443 withServerNameset to the portal hostname, and include the TLS directives for that name in the same block. - Shared document root: Point
DocumentRootat the public directory of the same installation, and avoid copying the application into a second folder. - Overrides and rewrite: Set
AllowOverridefor the shared directory so the bundled.htaccessfile applies, and confirmmod_rewriteis enabled. - Modules and PHP: Load the same PHP module or PHP-FPM handler and the same extensions as the main virtual host, since a missing extension usually appears only on the portal.
- HTTP redirect: Add a port 80 virtual host for the portal name that redirects to HTTPS.
After enabling the site and reloading Apache, test a portal login and a file download through the portal name. Check the exact directives in the EspoCRM server configuration docs before you copy any example, because required settings change between releases.
Whichever web server you use, the portal block is only a routing layer. The checks that matter most are the settings that must be identical between the main hostname and the portal hostname, because any mismatch produces behavior that is hard to diagnose from the user side. Several of these settings live in the application configuration rather than in the web server, so changing the web server alone does not fix them.
- Application code and configuration: Both hostnames should read the same installation, including the same configuration file and the same database connection.
- PHP runtime: Both hostnames should run the same PHP version and extensions, using the versions listed in the server configuration documentation for your EspoCRM release.
- Limits and timeouts: Upload size, request timeouts and buffer settings should be identical, so a file that uploads on the main site does not fail on the portal.
- Security headers and TLS settings: Apply the same protocol versions, cipher policy and HSTS behavior to both names, so one hostname is not the weaker entry point.
- Access restrictions: Keep the same denial rules for internal directories, and confirm that any IP allowlist your security policy requires is applied to both the main and portal hosts where it fits your design.
Before go-live, compare the response headers of both hostnames with a simple request and confirm they match for every setting above. Ask your administrator to record which settings are shared in the configuration so that future changes are applied to both blocks.
Testing the portal block is different from testing the main instance, because the portal user sees a restricted set of pages and the request path is often the first place where a redirect loop, a missing asset or a certificate warning appears. A short, repeatable test run reduces the chance that the portal goes live with a configuration issue that only appears for external customers. Testing should cover both the web server layer and the application layer.
- Certificate and chain: Check that the portal name presents a valid certificate chain from a client outside your network, not only from inside it.
- Login and session flow: Sign in as a portal user, log out and sign in again, and confirm the session persists across page loads.
- Static assets and uploads: Load pages with scripts and styles, then upload and download a file to confirm rewrites and size limits behave as expected.
- Redirects and error pages: Request an unknown path and an HTTP URL, and confirm the responses match your standards for the main site.
- Logs: Confirm that both web server access and error logs record requests for the portal name, which gives your operations team a clear trail.
Hand over the final configuration files with a short note that lists which settings must stay aligned. Ask your team to confirm the exact PHP version and web server version supported for your EspoCRM release before the first deployment.
Setup sequence for a branded portal domain
This sequence moves a customer portal from the default EspoCRM address to a branded hostname that your team controls. Each step ends with a check, so the portal is only handed to customers once the name, certificate, web server rules and sign-in path all behave as expected.
Decide the portal hostname and scope
Your product or marketing owner and the platform team agree on the hostname customers will see, such as a subdomain of your main brand, and confirm that the internal CRM hostname stays separate. The security owner records which paths must sit behind the portal domain and which must never be reachable from it. The output is a short written decision with the hostname, the owner and the list of internal-only paths, which becomes the reference for later checks.
Create the DNS record
The DNS administrator adds a record that points the chosen hostname to the same public address as your EspoCRM server or reverse proxy. Use a short time-to-live while you test, then raise it once the setup is stable. Confirm the record from more than one resolver, for example with a lookup tool, and check that the name resolves to the expected address and nothing else. Do not proceed until the name resolves consistently.
Set the portal URL in EspoCRM
An EspoCRM administrator opens the portal settings and sets the portal URL to the new hostname, using HTTPS. Review the portal records and any email templates or links that reference the old default address, since those are where customers will notice a mismatch. Save the change, then open a portal link generated from the system and confirm it points to the new name. The check is a generated link that uses the branded hostname.
Configure the web server for the new host
The platform engineer adds a server block or virtual host for the portal hostname to the same web server that serves EspoCRM, whether Nginx, Apache or IIS. The block must route to the same application root and carry the same rules that deny access to internal directories. Validate the configuration syntax before reloading, then confirm that requests for the new name return the portal sign-in page over plain HTTP before TLS is added. The check is a clean configuration test and a valid response for the new host.
Issue and install the certificate
The platform engineer obtains a certificate that covers the portal hostname from your certificate authority or your chosen ACME-based process, then installs it with the full intermediate chain. Enable the HTTP to HTTPS redirect for the new host only after the certificate is in place. Inspect the chain from an outside client and confirm the certificate names the correct hostname, is trusted and has not expired. Do not accept a certificate that browsers report as incomplete.
Verify that portal users stay inside the portal
A tester signs in on the portal hostname with a portal user account and tries to open internal-only pages, administration screens and API endpoints that the portal role should not reach. Repeat the same attempts with a direct request that bypasses the browser, since access control must hold regardless of how the request is made. Record each attempt and its result. The check passes only when every restricted path returns a denial and no internal data appears in responses.
Test sign-in and asset loading from a clean browser
A tester uses a fresh browser profile or a private window with no cached cookies, signs in through the portal, and then checks that styles, scripts, images and uploaded files all load from the new hostname without mixed-content warnings or failed requests. If you use portal-specific authentication, test that path too, including sign-out and the fallback login method. The sequence is complete when sign-in, navigation and asset loading succeed on the branded domain with no console errors.
Choosing portal sign-in: password, OIDC or LDAP
The sign-in method you choose for the portal decides who can create customer accounts, how access is revoked and what happens when your identity provider is down. EspoCRM supports its own portal accounts with a password, OpenID Connect (OIDC) and LDAP, and the choice should be made before the portal domain goes live because switching later changes how every customer logs in. Start by asking whether your customers already have identities you manage. If they do not, EspoCRM's own accounts are the simplest path, and the password policy and session settings in the security documentation become your main controls.
If you use OIDC, the EspoCRM OIDC documentation describes several settings that matter for portal users: optional user creation on first login, mapping identity provider groups to EspoCRM teams, backchannel logout and a fallback login method. Confirm whether user creation on first login and group-to-team mapping apply to portal users or only to internal users, because a portal user created through the wrong path may land with the wrong access. Keep the fallback login method in mind as an access path during identity provider outages, and confirm who is allowed to use it. EspoCRM's own two-factor authentication is not compatible with OIDC, so the identity provider must carry the second factor for any portal user who needs one.
LDAP, including Active Directory and OpenLDAP, is documented by EspoCRM, but customer accounts are rarely held in a corporate directory. Use LDAP for portal sign-in only if your customers are actually provisioned there, and confirm with the vendor and in your own test environment how the LDAP login behaves for portal roles and whether it can be combined with a portal-specific provider. Whichever method you choose, test a portal login, a failed login, a password reset and a revoked account on the portal domain itself, not only on the internal address.
Security checks for a customer-facing portal address
A portal gives customers a sign-in page on the public internet, while the admin console holds the same data and far more power. The checks below keep those two surfaces apart and set the controls that apply to portal users and staff. Confirm each one in your own environment before the portal address is shared with customers.
Password policy and session limits
Portal users sign in from unmanaged devices, so the password policy and session lifetime matter more here than on internal accounts. The EspoCRM security docs recommend enforcing a password policy and limiting authentication token lifetime. Check both settings for portal users specifically, and confirm whether your portal authentication method, such as OIDC, takes over these controls from EspoCRM.
Admin access limited by IP rules
Admin logins should be reachable only from networks your organization controls, such as a office range or VPN egress. The security docs describe restricting access by IP address. Test the rule from an allowed network and from an outside network, and confirm that the admin host and portal host are evaluated separately.
Separate admin and portal hosts
Serving the admin console and the customer portal from one hostname makes every portal exposure an admin exposure. Give the portal its own domain and reverse proxy rules, and keep the admin host on an internal name or restricted path. Confirm that the proxy blocks admin routes on the public host and that portal users cannot reach internal pages through it.
Password recovery and admin accounts
Disable password recovery for admin accounts so that a reset email cannot grant administrative access. The security docs also advise against using admin accounts for daily work. Keep a small set of named administrators, use separate accounts for routine tasks, and document who holds admin rights and how they are reviewed.
Two-factor authentication for staff
The security docs recommend requiring 2FA. EspoCRM's own 2FA is not compatible with OIDC, so a deployment that signs staff in through an identity provider should rely on that provider's MFA instead. Confirm which second factor applies to each login path, and test that admin accounts cannot skip it through the fallback login method.
Sign-in logging and monitoring
Failed and successful portal sign-ins should reach a log your security team reviews. Confirm where EspoCRM writes its logs, how long they are kept, and whether they are forwarded to a central system. Set alerts for bursts of failed logins against portal accounts and for any admin sign-in from outside the allowed networks.
Questions teams ask before hosting a portal on their own domain
How much effort does a customer portal on its own domain take?
Most of the effort sits in the web server, DNS and certificate work, not in EspoCRM itself. You need a second virtual host or server block that answers on the portal domain, a certificate that covers it, a DNS record that points to your server, and a tested login path for customers. The amount grows with the number of web servers, the number of portals, and whether customers sign in through your own identity provider. A fixed-scope written plan makes the effort visible before work starts, so ask for the list of hosts, certificates and identity steps in the quote.
Can an in-house team host a portal on a separate domain?
Yes, if the team already runs EspoCRM on Apache, Nginx or IIS and can manage PHP, databases and TLS. EspoCRM's server configuration lists PHP 8.3 to 8.5, MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15, and background jobs need cron or a scheduled task. The team also needs someone who can test portal permissions, because customers must see only their own records. If nobody on the team has run a public-facing web tier before, a partner can plan and implement the change inside your infrastructure and hand over the configuration and runbook.
What drives the cost of a portal domain up or down?
The main cost drivers are the number of web servers and load balancers the portal passes through, whether sign-in is integrated with an existing identity provider, how many extensions or custom entities the portal exposes, and how much testing is needed before customers arrive. Each driver adds planning, configuration and verification work. Ask for a quote that lists each host, each identity integration, each extension in the portal and each test cycle as a separate line. Self-hosted EspoCRM has no per-user license fee under the open-source edition, so your cost is mainly infrastructure and services, while the EspoCRM Cloud pricing page lists per-user plans for comparison.
What does a portal domain project need from our side?
The project needs four things from your side. First, DNS access, or a change owner who can create the portal record and approve it. Second, a certificate process, meaning either an approved certificate authority workflow or permission to use automated issuance on your server. Third, administrator access to your identity provider if customers sign in through it, including the ability to register a new client application and set redirect addresses. Fourth, a named owner for the web servers and firewall rules. Agree these dependencies in the written scope so they do not stall the build.
How long does a portal on its own domain take to set up?
The duration depends on scope: how many portals you need, how many web tiers sit in front of EspoCRM, whether sign-in is integrated with an identity provider, and how long your change approvals and certificate requests take. We do not publish a fixed timeline for this topic, because the same portal can take days or weeks depending on those inputs. Ask for a timeline in the written scope that separates planning, configuration, testing and go-live, and ask which of your internal approvals sit on the critical path.
Does a portal on a separate domain change EspoCRM licensing?
EspoCRM is licensed under AGPL-3.0, according to the license metadata of the espocrm/espocrm GitHub repository, and the open-source edition can be downloaded and self-hosted for free, according to the EspoCRM pricing page. Serving the portal from a different domain does not appear in that published pricing as a separate charge. Still, confirm the edition, extensions and any portal features your design depends on with EspoCRM before go-live, and check the AGPL-3.0 obligations with your legal team if you modify the software. The published Cloud plans charge per user, which is a different model from self-hosting.
Should portal customers sign in with a separate identity provider?
Consider it when customers already have accounts in an identity provider, or when you want one sign-in policy for staff and customers. EspoCRM supports OpenID Connect sign-in since version 7.3, with optional user creation on first login, mapping of identity provider groups to teams, backchannel logout and a fallback login method, according to the EspoCRM OIDC docs. Two details matter: EspoCRM's own two-factor authentication is not compatible with OIDC, so the identity provider must enforce second factors, and the fallback login must be planned so you do not lock out customers if the provider is down.
What should we verify after the portal domain goes live?
Verify the portal from outside your network, not only from inside. Check that the certificate chain is valid for the portal name, that HTTP redirects to HTTPS, that a test customer sees only their own records, and that the staff login address is not reachable through the portal domain. Confirm that cron or the scheduled task still runs background jobs, that certificate renewal is automated or calendared, and that backups include the configuration files for the new virtual host. Also review the EspoCRM security guidance on IP restrictions and token lifetimes for the portal and staff domains.
How DeployOpen scopes and delivers a portal domain
DeployOpen scopes a portal domain as one piece of work with four owners: the hostname, the DNS records, the TLS certificate and the EspoCRM and web server settings that connect them. The engagement starts by agreeing which hostname customers will use, who controls the DNS zone, who issues and renews the certificate, and which portal roles and authentication methods the portal will expose. Those decisions are written into the scope before any server is changed, because a mismatch between the public name, the certificate and the portal settings is the most common reason a portal fails at launch.
Delivery happens inside the client's own infrastructure, in their cloud accounts, data center or private network. DeployOpen configures the web server for the portal host, sets the portal URL and any portal-specific authentication provider in EspoCRM, and then tests the boundary that matters most: a portal user should reach only their own portal records, and staff sign-in on the main domain should stay separate from customer sign-in. The result is documented as a runbook covering the settings changed, the certificate renewal path and the test cases used, so the client's own team can operate it afterwards.
Most engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts, and quoted from that written scope rather than from a published price list. Ongoing support after go-live, such as certificate checks, configuration changes when new portal features are enabled or periodic access reviews, is available as a retainer. Before requesting a quote, confirm who owns the DNS zone, which web server the EspoCRM instance already runs on, and whether your identity provider supports the sign-in method you intend to offer customers.
