Internal documentation only
This page has been marked as draft.
SSO Agent Basic Troubleshooting tips
When SSO agent is either newly configured or steps have been, there is always a strong chance that you’ll run into errors. This guide is to help with some troubleshooting steps you can perform to see the status of your SSO agent and gain a little understanding where an issue could lie.
Below are some basic network commands you can run to check the connectivity between Gateway server and SSO agent host.
Windows Copied
ping - (CMD/Powershell) would show us if it is reaching the SSO agent host directly
e.g. ping sso.agent.url
tracert- (CMD/Powershell) helps identify how it reaches the target host on the network
e.g. tracert sso.agent.url
nslookup- (CMD/Powershell) helps us identify if the resolved IP address is the same host
e.g. nslookup sso.agent.url
Test-NetConnection - (Powershell only) this shows us if the target host and port is reachable directly (similar to telnet)
e.g. Test-NetConnection sso.agent.url -port xxxx
telnet - same as above, if in case Powershell isn’t available
e.g. telnet sso.agent.url xxxx
netsh winhttp show proxy - (CMD/Powershell) This shows if/how a system-wide proxy is configured on the actual Windows machine
Unix/Linux & MacOS Copied
ping - Check Basic Connectivity (ICMP Ping) e.g. ping -c 4 sso.agent.url
traceroute- Check the Path (Route) e.g. traceroute sso.agent.url
dig- Check DNS Resolution (Name-to-IP) e.g. dig sso.agent.url
nc(netcat) - Check Target Port Connectivity (TCP) e.g. nc -zvw 2 sso.agent.url xxxx
telnet - same as in Windows, if command is available e.g. telnet sso.agent.url xxxx
networksetup -getwebproxy "Wi-Fi" (or "Ethernet") - Checks System/Network Proxy settings
Status Copied
Use the /status endpoint in the browser to check the status of the SSO agent service.
Example URL - http://sso.agent.url:8083/status. You’ll be presented with a page which shows the agent is running and can be reached by browsers running on the client machines. If the page fails to load, check the agent is running or not. Also check firewall to ensure the connection is not blocked.
Test Authentication Copied
Use the /testuser endpoint in the browser to check if you can authenticate. You’ll be presented to a login dialogue. If authentication is successful, you’ll be presented details stating the authentication status and user permissions.
Some further troubleshooting can be found here.
Log Messages Copied
You maybe see the following message in the sso-agent.log - Authentication outcome was NOT_ATTEMPTED with method. This means that the SSO agent did not reach the stage where authentication could take place.
At this stage, it’s worth checking AD/LDAP is correctly set up so that the SSO agent can reach AD/LDAP. If Kerberos is being used, check that the user is on the domain, valid Kerberos tickets are issued and the browser is not configured for SPNEGO. Usually if Kerberos fails, the SSO agent will fall back on SPNEGO which is not compatible with SSO agent.