Troubleshoot App Gateway

Learn about common problems that you might encounter when setting up App Gateway and how to solve them:

I Made Changes in Oracle Identity Cloud Service but the App Gateway Server Doesn't Reflect the Changes

Changes you make to enterprise applications and App Gateway definitions in Oracle Identity Cloud Service may not be reflected immediately on App Gateway because App Gateway caches Oracle Identity Cloud Service information, such as resources, authentication policies, and header values of enterprise applications.

Explanation: App Gateway contacts Oracle Identity Cloud Service using agents to collect host and port information. When you start App Gateway, its NGINX server is automatically configured with this information. Any changes to Oracle Identity Cloud Service is periodically polled by the agents.

By default the policy and headers refresh time are 3600 seconds (1 hour) each. To change these values, log in to the App Gateway server, and edit the /usr/local/nginx/conf/cloudgate.config file. Change the ttl value for policy and headers in the caching section as per the following example, and then restart both App Gateway server and the agent.
"caching" : {
  "minimumTtl"            : 300,
  "headers"               : { "ttl": 3600 },
  "discovery"             : { "ttl": 3600 },
  "policy"                : { "ttl": 3600},
  "tenantKeys"            : { "ttl": 86400 }
}
You can also change the poll interval of the agents. By default, the agent's refresh time to get new App Gateway configuration from Oracle Identity Cloud Service is 60 seconds, which is the minimum amount of time supported. In the /usr/local/nginx/conf/cloudgate.config file, change the pollIntervalSecs value in the agentConfig section as per the example:
"agentConfig": {
    "pollIntervalSecs"    : 60,
    "daemon"         : true,
    "logLevel"        : "warn",
    "logFolder"        : "" 
}
If you want the changes in the Enterprise Application configuration to be reflected immediately, stop the App Gateway server and then start the server.
/scratch/oracle/cloudgate/home/bin/cg-stop
/scratch/oracle/cloudgate/home/bin/cg-start
If you want the changes in the App Gateway configuration to be reflected immediately, stop the agent and then start the agent.
/scratch/oracle/cloudgate/home/bin/agent-stop
/scratch/oracle/cloudgate/home/bin/agent-start

See Start and Stop App Gateway

Error Log Files Contain Invalid_session Message

When App Gateway can't communicate correctly with Oracle Identity Cloud Service, you'll find invalid_session messages in the App Gateway error log files.

The following is an example of an invalid_session messages in error.log file:

www-authenticate: Bearer error="invalid_session", error_description="Authentication Failure

This can be because of the way App Gateway processes a client request to a protected resource. App Gateway uses NGINX sub requests to make requests to Oracle Identity Cloud Service, and then App Gateway requires Linux NGINX resolver to be configured appropriately to allow these sub requests to function correctly.

  1. Verify that the resolver setting in the file /usr/local/nginx/conf/nginx-cg-sub.conf is set to the correct IP.
  2. Verify that the tenant name in /usr/local/nginx/conf/cloudgate.config file is configured correctly.

Error Log Files Contain GET 127.0.0.1:53 Command Responding Error Number 500

Because App Gateway makes sub requests to an internal servlet, App Gateway requires your virtual machine to listen to port 53.

The App Gateway server must communicate to itself through IP address 127.0.0.1 and port 53.

If you're running App Gateway in a virtual machine software, configure port forward for this port from the host to the guest. See Configure Port Forwarding Rules

App Gateway Server Can't Communicate With Oracle Identity Cloud Service

If during the configuration of the App Gateway server, the communication with Oracle Identity Cloud Service instance fails, then you need to perform extra configuration in the App Gateway server to enable this communication.

Use a SSH client such as PuTTY and the following credentials to log in to the App Gateway server, and then execute the ping <idcs-tenant>.identity.oraclecloud.com command to verify if the App Gateway server can reach the Oracle Identity Cloud Service instance.

If ping command fails, then execute the following procedure:
  1. Execute the sudo su - command to login as root, and the provide the oracle password when prompted.

  2. Execute the vi /etc/hosts command, and then add an entry to map your Oracle Identity Cloud Service host name if it isn't publicly available. For example: <your_identity_cloud_service_ip> idcs-tenant.identity.oraclecloud.com

  3. Execute the vi /etc/resolv.conf command, and then add a nameserver entry to configure the Virtual Machine as a nameserver. For example: nameserver 127.0.0.1

    This is necessary because App Gateway makes HTTP requests to itself.

  4. Install and start dnsmasq on the App Gateway server using the following command lines:
    yum install dnsmasq
    chkconfig dnsmasq on
    service dnsmasq start
  5. Install telnet by running the following command:
    yum install telnet
  6. Run the following telnet command and try to establish a connection to your Oracle Identity Cloud Service instance and your application from the App Gateway server.
    telnet <idcs-tenant>.identity.oraclecloud.com 443

    If telnet can't connect to your Oracle Identity Cloud Service, then contact your network administrator to apply any other network configuration to enable the App Gateway server to establish connection with your Oracle Identity Cloud Service instance.

  7. Execute the exit command, to log out from root account.