Skip to content

Troubleshooting

Setup

Gateway on ESXi doesn't show as ready to approve

Issue

Gateway hosted on ESXi doesn't show an "Approve" button in Sophos Central after deployment.

What to do

  1. Check whether your gateway can connect to these URLs. If it can't, allow them. Use port 443 unless otherwise stated.

    • sophos.jfrog.io
    • \*.amazonaws.com
    • production.cloudflare.docker.com
    • \*.docker.io
    • \*.sophos.com
    • login.microsoftonline.com
    • graph.microsoft.com
    • ztna.apu.sophos.com (Port 22)
    • sentry.io
    • \*.okta.com (If you use Okta as an identity provider)
  2. Make sure that ESXi has the latest firmware version.

  3. Make sure that the time is set correctly (GMT 0) on ESXi.

  4. Make sure that the CD-ROM is attached. If it isn't, power the VM off and reattach it. If that fails, recreate the gateway VM.

  5. Run a TCP probe on internal interface:6443 to make sure K3S is running.

  6. If your gateway is behind Sophos Firewall, sign in to the firewall, go to Diagnostics > Packet Capture and turn packet capturing on, or set up web filtering, to see which requests fail. You can also do this on a third-party firewall.

No user groups are available to be given access to resources

Issue

When you add a resource to ZTNA, there are no user groups that you can allow to access it.

What to do

Check that your directory service (Microsoft Entra ID (Azure AD) or Active Directory) has user groups and that they're synchronized in Sophos Central.

The certificates aren't shown on the 'Edit gateway' page

Issue

When you open the Edit gateway page, you don't see the certificates you uploaded when you added the gateway.

What to do

This is as designed. You can't view the current certificates there.

ZTNA on endpoints

ZTNA is shown as 'Not Configured' on endpoints

Issue

When you open Sophos Endpoint on a device managed by Sophos Central, the Status page shows "Zero Trust Network Access: Not configured".

What to do

Go to Devices > Computers (or Servers). Check whether the ZTNA agent is installed on the device. If it's installed, you see a green checkmark. If it isn't, you see a plus sign. Click to install ZTNA.

ZTNA is shown with the warning 'Zero Trust Network Access: Error' on endpoints

Issue

When you open Sophos Endpoint on a device managed by Sophos Central, the Status page shows "Zero Trust Network Access: Error". This indicates that there's a connection problem.

What to do

  1. Check that a ZTNA policy has been set up in Sophos Central.

  2. Check that the gateway FQDN can be resolved.

  3. Check whether Sophos TAP adapter configuration failed.

  4. Turn off the IPv6 network interface on the agent. The tunnel will then be established.

User groups

User groups lose access

Issue

Users in an Microsoft Entra ID (Azure AD) user group that previously had access to an app can no longer access it.

Cause

If you change the name of an Microsoft Entra ID (Azure AD) user group that's been given access to an app, the Assigned User Groups list in ZTNA isn't updated to reflect the change. Users won't be able to access the app.

What to do

  1. Go to Zero Trust Network Access > Resources & Access.

    Resources & access menu.

  2. On the Resources & Access page, find the app and click it to edit its details.

    Resources list.

  3. In the Edit Resource dialog, do as follows:

    1. Go to the Assign User Groups section.
    2. In Available User Groups, find the renamed user group and select the checkbox next to it.
    3. Move the group to Assigned User Groups and select the checkbox next to it.
    4. Click Save.

    Edit Resource dialog.

User's been added to an allowed user group but can't access the app

Issue

You've added a user to an allowed user group for an app but the user sees a 403 Access Denied error.

What to do

If the user's been added recently, ask them to try again later. Changes to user groups can take up to an hour to take effect.

Alternatively, if it's a web app, tell the user to go into Incognito or Private mode in their browser and then try again.

User's been removed from an allowed user group but can still access the app

Issue

You've removed the user from an allowed user group for an app but they can still access it.

What to do

Check again later. Changes to the allowed user group can take up to an hour to take effect.

Access issues

User sees a 404 Not Found error when they try to access an agentless app

Issue

When the user tries to access an app that's been set up for agentless access, they see a 404 Not Found error.

What to do

In your DNS management settings, do as follows:

  1. Check that you have a CNAME record for the app that points to the gateway's FQDN.

  2. Make sure you don't have a CNAME record for any app that's accessed via a ZTNA agent.

User sees a 403 Access Denied error when they try to access an agentless app

Issue

The user sees a 403 Access Denied error when they try to access an agentless app.

What to do

  1. Check that you've enabled all the required API Permissions for your identity provider.

    For Azure, you need these Microsoft Graph API permissions:

    • Directory.Read.All (Delegated)
    • Directory.Read.All (Application)
    • Group.Read.All (Delegated)
    • openID (Delegated)
    • profile (Delegated)
    • User.Read (Delegated)
    • User.Read.All (Delegated)

    Currently you also need an Microsoft Entra ID (Azure AD) API permission: Directory.ReadWrite.All (Application). See Register the ZTNA app.

    For Okta:

    • okta.groups.read
    • okta.idps.read (You only need this if you use AD Sync)
  2. Check that the ZTNA policy allows access to the app.

  3. Check that the user is in an assigned user group for the app.

  4. Check that you have network connectivity to the identity provider:

    For Azure:

    • login.microsoftonline.com
    • graph.microsoft.com

    For Okta:

    • *.okta.com
User sees an upstream request error when they try to access an agentless app

Issue

User sees an upstream request error when they try to access an agentless app.

What to do

  1. Check that the application is accessible from the network that the ZTNA gateway is on.

  2. Check that the application is still running.

  3. If the internal FQDN or IP address is shown, make sure it resolves to the app.

  4. If you use a private DNS Server, check that it's running and resolves to the app's external FQDN.

  5. Check that the port numbers specified for the app are correct.

User is authenticated but can't access an app that needs ZTNA agent

Issue

The user is authenticated but can't access an app.

What to do

  1. Check the SNTP logs for errors.

  2. Check the certificates are valid in heartbeat.xml.

User loses access to an app accessed via ZTNA agent

Issue

The user could previously access an app but can't do so anymore.

What to do

  1. Check the SNTP logs for errors.

  2. Check the certificates are valid in heartbeat.xml

  3. Check whether ZTNA is shown with "red" health status in the Sophos Endpoint UI.

User doesn’t see the IDP sign-in screen the first time they try to access apps

Issue

The IDP should prompt the user to sign in the first time they try to access apps. If this doesn't happen, the user can't access apps.

What to do

Check that the user's device can contact the ZTNA gateway.

User doesn't see a sign-in popup when they try to access an app that needs the agent

Issue

The user should see a popup that prompts them to sign in when they try to access an app that needs the ZTNA agent. If they don't, they can't access the app.

What to do

  1. Check the SNTP logs for errors.

  2. Check the DNS settings. The DNS server must not have a CNAME record for the app.

  3. Check the ZTNA agent process is running.

User can access an app but links in that app don't work

Issue

The user can access an app but links there to other apps don't work.

What to do

Add the other apps to ZTNA as described in Add resources. This lets ZTNA give the user access when they click on the links.

User is authenticated but isn't redirected to the app

Issue

The user sees the sign-in screen and is authenticated but isn't redirected to the app they tried to access.

What to do

  1. Check that you specified the correct redirect URI in the identity provider (IdP) settings.

    • If Microsoft Entra ID (Azure AD) is the IdP, you specified the Redirect URI when registering the ZTNA app. See Register the ZTNA app.
    • If Okta is the IdP, you specified the Sign-in redirect URI when you created an app integration in Okta. See the Okta instructions in Set up an identity provider.
  2. If Okta is the IdP, check that you entered the "Groups claim expression" with the correct capitalization. This expression is case-sensitive.

User sees a 403 Access Denied error when they try to access an internal resource

Issue

The user sees a 403 Access Denied error when they try to access an internal resource, for example, an internal webserver.

What to do

  1. Make sure the user is part of a user group mapped to the resource.
  2. Make sure the user groups mapped to the resource are locally created user groups and not synced from the directory service.
  3. Make sure the group configuration is correct in the directory service settings. For example, in Microsoft Entra ID (Azure AD), make sure that your imported user groups are security-enabled.
  4. Make sure you turn the ZTNA policy on in Sophos Central.
  5. If you're accessing the resource with the ZTNA agent, make sure the synchronized security health status of your device matches the ZTNA policy. For example, ZTNA may show a "green" or "yellow" health status.

ZTNA user portal

User can't see apps in the ZTNA user portal

Issue

The user can't see any apps in the ZTNA user portal.

Note

Currently the portal doesn't show apps that are accessed via the ZTNA agent. Users only see agentless apps.

What to do

  1. Ensure that your imported user groups are security-enabled.

  2. Go to Resources & Access and click an app to edit its settings.

  3. Check that the user is in assigned user groups for the apps they need. Users can only see apps that they are authorized to access.

  4. Check that the admin selected Show resource in user portal when they added the apps.

User signs in but isn't given access to the ZTNA user portal

Issue

The user tries to access the ZTNA user portal and is shown the identity provider's sign-in screen. After they sign in, they're not returned to the user portal.

What to do

Check that you specified the correct redirect URI in the identity provider (IdP) settings.

If Microsoft Entra ID (Azure AD) is the IdP, you specified the Redirect URI when you registered the ZTNA app. See Set up directory service.

If Okta is the IdP, you specified the Sign-in redirect URI when you created an app integration in Okta. See the Okta instructions in Set up an identity provider.

DNS issues

DNS lookups fail after you install the ZTNA agent

Issue

After you install the ZTNA agent, if you use nslookup to do a DNS lookup, it sometimes fails.

What to do

Specify the network adapter for the lookup to use.

Installing the ZTNA agent changes the default TAP adapter. If you use nslookup to do a DNS lookup, it now uses the ZTNA TAP adapter by default. Lookups of apps that aren't behind the ZTNA gateway will fail.

To avoid this issue, add the correct adapter to your nslookup command. For example:

nslookup <FQDN-to-be-resolved><DNS-Server>

ZTNA diagnostics

This section describes the reasons a gateway may fail the diagnostic tests and the steps you can take to fix the issue.

Network diagnostics

Not able to read interface configuration

What to do

Verify that the ISO file downloaded from Sophos Central is attached.

Interface eth0 did not receive IP

What to do

Verify the network interface configuration. If you need to edit the gateway's network settings, create a new instance of the gateway on Sophos Central and download a new ISO file.

Interface eth1 did not receive IP

What to do

Verify the network interface configuration. If you need to edit the gateway's network settings, create a new instance of the gateway on Sophos Central and download a new ISO file.

DNS diagnostics

ZTNA Gateway could not resolve ntp.ubuntu.com

What to do

Check your DNS server configuration and make sure ntp.ubuntu.com can be resolved.

ZTNA Gateway could not resolve Sophos Central

What to do

Check your DNS server configuration and make sure sophos.jfrog.io can be resolved.

Network Connectivity diagnostics

Failed to contact ntp.ubuntu.com on port 123

What to do

Verify the network interface configuration. If ntp.ubuntu.com is unreachable, ZTNA services won't start.

Failed to contact sophos.jfrog.io on port 443

What to do

Make sure all the URLs mentioned in the ZTNA requirements are allowed: Allowed websites.

Sophos Services Diagnostics

Note

When you encounter errors in the Sophos services diagnostics, wait for 5-10 minutes then rerun the diagnostics. If the same error is encountered, restart the gateway. If the same error occurs after following both steps, contact Sophos support.

Kubernetes service is not running

What to do

It may take up to 10 minutes for the service to start after the gateway starts. Follow the steps below if the service doesn't start after 10 minutes.

Ensure the time on the gateway is synchronized with the time in Kubernetes. Also, ensure that the timezone is UTC.

Ensure the gateway can connect to the internet.

If you configure your gateway cluster in DHCP mode, ensure the IP addresses of your gateways haven't changed.

If the gateway platform is VMware ESXi, ensure the CD-ROM is attached to the VM instance when you start it.

Ensure at least half the nodes in your gateway cluster are active.

If the service still doesn't start, contact Sophos Support for help.

Redis Pod is not running

What to do

Contact Sophos Support for further help.

Cluster pods are not in running state

What to do

Contact Sophos Support for further help.

Gateway not registered with Sophos Central

What to do

Check connectivity to Sophos Central.

Failed to find Gateway details

What to do

Verify that the gateway has succesfully registered and check connectivity to Sophos Central.

Please wait for the Gateway to register and connect to Sophos Central

What to do

Approve the gateway on Sophos Central.

The gateway can't be managed by Sophos Central because services aren't running. Error: <cloud agent name>: crashloopback off <node number>: pending

What to do

Check the ISO that's mapped when booting up the gateway. Ensure the latest ISO is used and redeploy the gateway.

Unable to resolve Sophos Central FQDN

What to do

Verify that the firewall settings are updated to make sure that the dynamic URL displayed gets resolved.

Note

Dynamic URLs (For example: https://ztna-proxy.cloudstation.eu-west-1.prod.hydra.sophos.com) are generated based on the region where the user’s account is located. The dynamic URL is displayed in the gateway console’s error message.

Unable to connect to Sophos Central dynamic URL on port 443

What to do

Check connectivity to Sophos Central.

Note

Dynamic URLs (For example: https://ztna-proxy.cloudstation.eu-west-1.prod.hydra.sophos.com) are generated based on the region where the user’s account is located. The dynamic URL is displayed in the gateway console’s error message.

Time Diagnostics

Kubernetes Cluster time and Local time have a difference greater than 60 seconds

What to do

Verify the settings on the gateway platform. A time mismatch leads to connectivity issues.

NTP time and local time have a difference greater than 60 seconds

What to do

Verify the settings on the gateway platform. A time mismatch leads to connectivity issues.