Troubleshoot miscellaneous issues

This topic describes how to troubleshoot common issues:

Before you begin

To troubleshoot Access Gateway issues, you must meet the following prerequisites:

  • You have admin access to your Okta org.
  • You have access to the Access Gateway Management console.
  • You can retrieve and monitor logs from network appliances and, application servers, and so on.

An SSH error appears when connecting to an Access Gateway instance by command line

Message Permission denied (publickey,gssapi-keyex,gssapi-with-mic)
Description The oag-mgmt username wasn't specified when you attempted to connect to the Access Gateway instance using the command line.
Log statement example 
username$ ssh 100.25.225.222
username@100.25.225.222:Permission denied (publickey, gssapi-keyex,gssapi-with-mic).
username $
Validation and mitigation steps Specify the oag-mgmt username when connecting to an Access Gateway instance.

The time isn't in sync

When the time isn't synchronized between Access Gateway and applications, Access Gateway can't process SAML assertions correctly.

Access Gateway couldn't validate the SAML assertion

Message Requester/RequestDenied: Could not validate the following SAML AuthnRequest from partner Access Gateway Application Name:
Description The time on the Access Gateway or protected app computers isn't synchronized.
Log statement example 
Apr  3 14:20:18 accessgw01 ACCESS AUTHN SAML ERROR USER_AUTHN [TYPE="SAML_2_0" TRACKER_ID="882d8b2faf" 
SOURCE="<IDP SSO URL>" RESULT="FAIL" REASON="Invalid SAML Assertion" REMOTE_IP="<Remote IP address>" 
USER_AGENT="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) 
Chrome/65.0.3325.181 Safari/537.36"] Requester/RequestDenied: Could not validate the following SAML 
AuthnRequest from partner <Access Gateway Application Name>:
Validation and mitigation steps
  1. Sign in to the Access Gateway Admin UI console.
  2. Select the Settings tab.
  3. Select Advanced.
  4. Verify that the time is correct. If it's not, click Resync.
  5. Click the refresh button to refresh the system time and verify that it's current.
  6. Verify the time in the Access Gateway Admin UI console and in the application.
  7. Verify that the times match.

The SAML assertion date and time are in the future

Message Received an assertion that is valid in the future. Check clock synchronization on IdP and SP.
Description The SAML assertion from the protected app has a date and time in the future.
Log statement example 
Apr  3 14:20:09 oag01 ACCESS_GATEWAY ACCESS AUTHN SAML ERROR USER_AUTHN [TYPE="SAML_2_0" 
TRACKER_ID="882d8b2faf"SOURCE="<IDP SSO URL>" RESULT="FAIL" REASON="Invalid SAML Assertion" 
REMOTE_IP="<Remote IP address>" USER_AGENT="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 
(KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36"] Received an assertion that is valid in the future. 
Check clock synchronization on IdP and SP.
Validation and mitigation steps
  1. Sign in to the Access Gateway Management console
  2. Select the Service option.
  3. Select the NTP option.
  4. Select the option to restart the NTP service.
  5. Verify that the time in the Access Gateway Admin UI console matches the time in the application.

The SAML assertion expired

Message Received an assertion that has expired. Check clock.
Description The SAML assertion from the protected app has expired. The time might not be configured correctly on the computer that hosts the protected app.
Log statement example 
Apr  4 16:20:11 oag01 ACCESS_GATEWAY ACCESS AUTHN SAML ERROR USER_AUTHN [TYPE="SAML_2_0" TRACKER_ID="d7703c136c"
SOURCE="<IDP SSO URL>" RESULT="FAIL" REASON="Invalid SAML Assertion" REMOTE_IP="<Remote IP address>" 
USER_AGENT="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) 
Chrome/65.0.3325.181 Safari/537.36"] Received an assertion that has expired. Check clock
Validation and mitigation steps
  1. Sign in to the Access Gateway Management console.
  2. Select the Service option.
  3. Select the NTP option.
  4. Select the Set System Time option.
  5. Enter the time in MON DD YYYY HH:MI:SS AM/PM format.
  6. Verifythat the time in the Access Gateway Admin UI console matches the time in the application.

The browser doesn't trust the domain and doesn't post a SAML request

Message Caused by: Exception: Unable to find the current binding.
Description This error can occur if a user keeps reposting SAML assertions or if an error occurs in the process of accepting a self-signed SSL certificate.
Log statement example 
Apr 04 14:19:44 ACCESS ERROR [3137b1cb3f] Caused by: Exception: Unable to find the current binding.
Validation and mitigation steps

Solution 1: Ensure that the certificate was validated.

  1. Open the returned certificate.
  2. Verify that the certificate is valid.
  3. If the certificate isn't valid, request a new certificate and update it in Access Gateway Management console. See Certificate management.
  4. Test access to the application.

Solution 2: Verify that the browser trusts the application URL.

  1. Verify whether the browser trusts the URL of the application.
  2. Add the URL of the application and all other Access Gateway endpoints under the trusted zone settings in the browser. See your browser's documentation for instructions.
  3. Restart the browser.
  4. Verify that you can access the application.

Unexpected application or Access Gateway instance behavior

Behavior Unexpected behaviors occur in applications or in the Access Gateway instance.
Description

Outdated pages or cookies stored in the browser cache can cause Access Gateway and applications to read and process out-of-date data.
Validation and mitigation steps
  1. Clear the browser cache.
  2. Verify that you can access the application and Access Gateway.

Application certificate errors

Behaviors
  • When a user accesses an application, the browser shows a certificate warning. The user must click the link to proceed to the application.The application fails to open and the user receives an error page.
  • The application works normally if it's opened in the same browser session as used previously.
Description

These behaviors occur when a browser doesn't trust the certificate. When the user clicks the proceed link, the browser doesn't post data to the SAML endpoint and the SAML assertion fails. If the user opens the application again in the same browser session, the browser trusts the URL because the user granted permission earlier. The application then posts the correct data to the SAML endpoint.
Validation and mitigation steps

Fix this issue on the local system only:

Add the Access Gateway client certificate to the browser's trust store. See your browser's documentation for instructions.

Fix this issue for all systems:

  1. Procure a valid certificate. See Certificate management.
  2. Update the certificate on the Access Gateway appliance.
  3. Update the certificate on the load balancer if necessary.

Microsoft Internet Explorer redirect looping

Browser trust

Behavior Microsoft Internet Explorer tabs can open and close by themselves or redirect the user in a loop.
Description The browser doesn't trust the application or the Access Gateway endpoints.
Validation and mitigation steps

Add the Access Gateway hostname endpoint and application endpoint URLs to the Trusted Zone settings in Microsoft Internet Explorer settings.

Load balancing

Behavior Microsoft Internet Explorer tabs can open and close by themselves or redirect the user in a loop.
Description If you're using a load-balanced solution, the browser resolves the Access Gateway hostname to one node and the application public domain to another node.
Validation and mitigation steps
  1. Verify that the load balancer enforces sticky sessions.
  2. Ping the Access Gateway hostname and the application public domain to verify that they're resolving to different IP addresses. See Ping.
  3. Update the local hosts file or DNS entry to match the correct IP addresses.

Invalid Identity Provider API key

Messages The IdP API token has been deleted from the IdP.
Validation and mitigation steps
  1. Create a new Identity Provider API token in the Identity Provider in your Okta org. See API token management.
  2. Update the API Key in Access Gateway. See Configure your Okta org as an Identity Provider. Follow the instructions in the Use Workforce Identity Cloud as the IdP for Access Gateway section.

The app name is out of sync

Message <App Name> is out of sync with IdP. Would you like to recreate this application is <IDP Org name>?
Description The application has been deleted from the Identity Provider.
Validation and mitigation steps
  1. Ensure that the API key used to configure the Access Gateway is still active. If it isn't, continue with the following steps.
  2. Delete the existing application from Access Gateway.
  3. Confirm that the application is deleted from the Identity Provider before recreating the app.
  4. Add the application again in the Access Gateway.
  5. Ensure that the application has been created in the Identity Provider. See Configure your Okta org as an Identity Provider. Follow the instructions in the Use Workforce Identity Cloud as the IdP for Access Gateway section.

The site can't be reached or displayed

Behavior The browser is unable to reach the site.
Description The application or Access Gateway services aren't running or the DNS entry is missing.
Validation and mitigation steps
  1. Restart the Access Gateway service or the application.
  2. Add the required DNS entry in the DNS or local hosts file.

App setup or creation is unresponsive

Behavior The progress indicator spins for a long time during initial setup or while creating an application in Access Gateway.
Description This occurs when Access Gateway fails to reach the designated Identity Provider.
Log statement example 
Mar 7 17:19:43 localhost.localdomain WEB_CONSOLE IOException occurred validating IDP host :IDP login URL
Validation and mitigation steps
  1. Verify that the Access Gateway appliance is able to connect to the Identity Provider.
  2. Look for the component that is blocking the connection and allow the connection to the Identity Provider.
  3. Verify the connectivity to the Identity Provider from the Access Gateway appliance.
  4. Ensure that the Client ID and Client Secret values are correct.
  5. Validate the Identity Provider configuration in Access Gateway and save the settings. See Configure your Okta org as an Identity Provider. Follow the instructions in the Use Workforce Identity Cloud as the IdP for Access Gateway section.

The TLS page doesn't appear

Behavior The TLS page doesn't appear.
Description This occurs when a browser's TLS security settings don't authenticate a secure connection with Access Gateway.
Log statement example 
Apr 16 10:55:41 test-oag icsDefault443Error 2018/04/16 10:55:41 [crit] 18480#0: *3047 SSL_shutdown() failed
(SSL: error:140E0197:SSL routines:SSL_shutdown:shutdown while in init) while SSL handshaking, client: 
Client IP address, server:0.0.0.0:443
Apr 16 10:55:41 test-oag icsDefault443Error 2018/04/16 10:55:41 [crit] 18480#0: *3047 SSL_shutdown() failed
(SSL: error:140E0197:SSL routines:SSL_shutdown:shutdown while in init) while SSL handshaking, client: 
Client IP address, server:0.0.0.0:443
Validation and mitigation steps

Ensure that your browser uses TLS 1.1, 1.2, and 1.3. See your browser's documentation for instructions.