Known Issues

This topic describes known issues in version 9.2 and 9.2 CR3 of the gateway, with workarounds if available.
This topic describes known issues in version 9.2 and 9.2 CR3 of the
Layer7 API Gateway
, with workarounds if available.
Known Issues in 9.2
Gateway Now Uses SunJSSE TLS Provider: Increased Time for Authentication Bind Operation
Impacts all Gateway form factors that perform LDAP authentication. Beginning with Gateway version 9.2, SunJSSE became the primary TLS provider, which is used by LDAP user authentication when the Gateway communicates with an LDAP provider over a secure network. Unlike previous TLS providers (i.e., the deprecated FIPS/BSAFEJSSE), LDAP binds performed by SunJSSE require a full TLS handshake for each LDAP user. This process adds approximately
100 ms to the LDAP authentication bind for each user
when compared to the same process for Gateway version 9.1.
The Gateway provides authorization caching of previously completed or successful binds.To reduce the performance impact of the full TLS handshake for repeat binds against the same user, the authorization cache size and storage of successful binds may be increased:
  • authCache.successCacheSize (default is 2000)
  • authCache.maxSuccessTime (default is 60000 ms)
Both properties can be configured as Gateway Cluster Wide Properties - see Credential Caching Cluster Properties for more information.
The optimal size of the cache is dependent on the size of your LDAP user base. Note that the cache success will not take into account of users changing passwords or being disabled on the LDAP server while success is cached.
Decode JSON Web Token Assertion Unaffected by Invalid JWT Signature
This issue is corrected in version 9.2.00 CR3. For more information, see "Issues Resolved in Version 9.2 CR3" in Resolved Issues (DE292005).
The Decode JSON Web Token Assertion does not fail when an invalid JSON Web Token (JWT) signature is detected. Although this behavior is by design, some users may construct policies assuming that an invalid JWT signature causes the assertion to fail. (DE292005)
To ensure that policy processing stops when an invalid JWT signature is detected, place a Compare Expression Assertion to fail.
The instructions below describe how to identify all occurrences of the Decode JSON Web Token assertion, how to configure the Compare Expression assertion and where to place it in your policy.
How to Identify Instances of the "Decode JSON Web Token Assertion"
Do the following steps to identify all policies that contain a Decode JSON Web Token Assertion:
  1. Run the following command:
    # mysql ssg -u gateway -p -e "select name from policy where xml like \"%L7p:DecodeJsonWebToken%\""
  2. Make note of the results. They list all the policies and services that contain the assertion.
  3. Log in to the Policy Manager either as the administrator or as someone with permissions to modify all policies/services.
  4. Open a policy that is identified by the MySQL command above.
  5. Press Ctrl-F to invoke the Search bar and then type "Decode JSON Web Token” to show all instances of the assertion in the policy.
  6. Click a search hit to go to the line in the policy.
  7. Add the Compare Expression Assertion in the appropriate place. This is described next.
How to Configure the Compare Expression Assertion
Configure the Compare Expression Assertion to test whether the
context variable is 'true', where the "<prefix>" is defined in the Decode JSON Web Token Assertion. For example, if the prefix is 'output', you define the comparison:
${output.valid} == true
. The properties dialog should look like this:
Compare Expression.PNG
Where to Place the Compare Expression Assertion
Where you place the Compare Expression Assertion depends on the policy logic in use at the branch. These are the main scenarios:
  • Decode JSON Web Token Assertion in Default Policy:
    In this case, simply place the Compare Expression assertion immediately after the Decode JSON Web Token assertion.
  • Decode JSON Web Token inside an ‘All assertions must evaluate to true’ Assertion:
    Similar to the above, place the Compare Expression assertion within "All assertions...", immediately following the Decode JSON Web Token assertion.
  • Decode JSON Web Token inside an ‘At least one assertion must evaluate to true’ Assertion:
    In this instance, enclose both the Decode JSON Web Token and Compare Expression assertions within a new "All assertions must evaluate to true" assertion.
    At least one assertion must evaluate to true
    Decode JSON Web Token
    At least one assertion must evaluate to true
    All assertions must evaluate to true
    Decode JSON Web Token
    Compare Expression
Unsupported Cipher Suites During Upgrade
This issue is corrected in version 9.2.00 CR1. For more information, see "Issues Resolved in Version 9.2 CR1" in Resolved Issues (DE270482 and DE274604).
Upgrading to version 9.2 with unsupported cipher suites enabled causes issues with the specific connection on which they are configure (DE270482, DE274604):
  • On listen ports, the specific listen port does not start until the affected cipher suites are removed.
  • On outbound (HTTP Options, Routing Assertion, Cassandra connection), the connection fails with an error message until the affected cipher suites are removed
Before upgrading to version 9.2, disable any affected cipher suites that you may have enabled on any Cassandra connection. These are the affected cipher suites:
Migration Issue Between Gateways
Migration issues may occur after upgrading. Release 9.1 introduces a new "gateway-hazelcast" FIREWALL_RULE. This rule is automatically added to the Gateway upon restart, if it does not already exist. This entity is created with a unique ID per Gateway. If you attempt a bundle import, the mapping for the "gateway-hazelcast" FIREWALL_RULE must be "MapBy:name" in order to prevent a 409 conflict. (DE211367)
Modify the bundle file that is created during bundle export as follows:
Locate this line:
<l7:Mapping action="NewOrExisting" srcId="
" srcUri="http://
" type="FIREWALL_RULE"/>
And then modify it as follows:
<l7:Mapping action="NewOrExisting" srcId="
" srcUri="http://
<l7:Property key="
Gateway Fails to Start When Thales HSM Is Present
When a Thales nShield Solo+ (formerly nCipher) HSM is present, the CA API Gateway may fail to start properly after upgrading to 9.2.00 from a
Layer7 API Gateway
version 9.0.00 or earlier. This causes the Policy Manager to fail to connect to the Gateway. (DE211352)
Do the following after upgrading to 9.2.00
  1. Disable use of the HSM in the Gateway main menu, using option
    (Manage HSM), then option
    (Manage Gateway Thales nShieldHSM status).
  2. In the Policy Manager, run the  Manage Listen Ports task.
  3. Double-click on port
    and then navigate to the SSL/TLS Settings tab.
  4. Make a note of all the cipher suites enabled for this port.
  5. Click
    Use Default List
    and then
  6. Repeat steps 2 to 4 for ports
  7. Exit the Manage Listen Ports task when done.
  8. Re-enable use of the HSM in the Gateway main menu, using option
    (Manage HSM), then option
    (Program into an existing security world).
    When the HSM is re-enabled, revisit the SSL/TLS Settings tab for each of the above ports and reset the supported cipher suites back to the original settings.
Gateway Fails to Start with SafeNet Luna HSM Is Present
When a SafeNet Luna HSM is in FIPS 140-2 approved configuration mode, the following error is logged: (DE243553)
WARNING 203 com.l7tech.server.util.UnsupportedExceptionsThrowsAdvice: An exception during a remote invocation is not supported by the Luna provider not configured
  1. Open the
    file in a text editor.
  2. Add the following line to the file:
  3. Save and exit the file.
  4. Restart the
    Layer7 API Gateway
Use of SSLv3 Protocol
The SSLv3 protocol is considered insecure and obsolete and is deactivated in the latest JDK. Please see for details.
Selecting "SSL 3.0" from any TLS drop-down list causes this error message to be logged during message processing: (DE247298)
Unable to obtain HTTP response from <URL>. No appropriate protocol (protocol is disabled or cipher suites are inappropriate)
If SSLv3 is absolutely required for legacy compatibility purposes, do the following to re-enable it:
  1. Open this file in a text editor:
  2. Remove "
    " from the
  3. Save and exit.
  4. Restart the
    Layer7 API Gateway
File Permissions After a Restore
Some file permissions may not be correctly restored after a Gateway is restored using the
command, resulting in the Policy Manager being unable to connect to the
Layer7 API Gateway
. To correct this, see "Problem: Gateway is not running properly after a restore" in  Troubleshoot. (DE221036)
Assertion Outcome During HTTP(S) Routing
The [Other] tab in the HTTP(S) Routing Properties contains the control [
Never fail as long as target returns an answer
]. There is a known issue that can still cause the assertion to fail even when an answer is returned under the following scenario:
  • In the [Security] tab, the Service Authentication is “Use HTTP Credentials from Request”.
  • The backend services return a 401 HTTP error.
To prevent assertion failure in this scenario, use “Specify HTTP Credentials” as the Service Authentication method instead. Specify the username and password as context variables from the request (i.e.,
). (DE215522)
HTTP Keep-Alive Is Ignored in HTTP Routing Assertion
When Client Mutual Authentication is enabled for the HTTP Routing assertion and the back-end requests the certificate, the HTTP keep-alive is not respected, and a new connection is created for each pass.
Set com.l7tech.server.policy.assertion.ServerHttpRoutingAssertion.statePool.enable=true in /opt/SecureSpan/Gateway/node/default/etc/conf/ Do not enable this system property if any policy depends on NTLM authentication to the back end. (DE210752)
Siteminder R12 Custom Assertion Does Not Authenticate HTTP Credentials After Invalid Cookie Token
When the policy encounters the invalid cookie, the logs show that an exception is thrown. The user is not authenticated or authorized.
Use current CA Single Sign On assertions to achieve the same functionality. (DE211281)
Connection Timeout During SSH Routing
There is a known issue in the
Route via SSH
assertion that causes the connection timeout to be twice as long as the value specified in the assertion when the SFTP protocol is selected. (DE215650)
Dependency Errors When Deleting OAuth Folder
Deleting an OAuth policy that contains policy fragments serving as backing policies for encapsulated assertions trigger dependency errors in the Policy Manager. These errors cannot be acknowledged in bulk nor can the deletion be canceled. For workarounds to avoid this, see "Problem: Deleting OAuth policy creates dependency errors" in  Troubleshoot. (DE222685)
Caching Issues with JDBC Connection
  Deleting a JDBC connection deletes it from the database, but not from the cache. Recreating the same connection before resetting the cache causes an exception.
: Restart the ssg service after the JDBC connection is removed to clear the cache, or rename the JDBC connection. (DE245098)
RBAC Issues for Manage IIP Role
Permissions do not work for groups/roles that only control Identity Providers. A user with the Manage Identity Providers role cannot see Identity Provider properties.
Add a role that can create and update Identity Providers. Assign the new role and the Manage Identity Providers role to users who manage Identity Providers. (DE221709)
Retrieving Certificate When Gateway in FIPS Mode
The Add Certificate Wizard fails to retrieve a certificate from a HTTP URL if the
Layer7 API Gateway
is in FIPS mode (that is, when the cluster property
= true).
Retrieve the certificate from the certificate chain of the private key instead. Use the "Import from Private Key's Certificate Chain" option in "Step 1: Enter Certificate Info" of the wizard. (DE211158)
WebSocket Server Fails to Initialize
The WebSocket server fails to initialize after installing the
Layer7 API Gateway
Enterprise license. (DE263359)
After installing the
Layer7 API Gateway
Enterprise license, access a privileged shell and run this command:
service ssg restart
The failure to initialize is not immediately obvious when you use the View Logs for the Gateway.
JDBC Connection Test False Positives
The [Test] button in the JDBC Connection Properties may fail to detect invalid JDBC URLs. This is caused by a problem in a third-party library used by the Gateway.
For MySQL, ensure that the URL is in this format:
jdbc:mysql://[host1][:port1][,[host2][:port2]] ...[/[database]]
Note that if a database is defined, it must be preceded by the '/' character.Broken Links in Docops
CA Technologies continually improves its user documentation throughout the year. If you maintain bookmarks to topics in Docops, there is a slight chance that the link may be broken. This could be caused by the topic being moved in a reorganization or consolidation. To resolve, simply search for the topic title and then update your bookmark.
JSON Schema Validation Unexpected Results
The current version of the
Layer7 API Gateway
does not support the "format" attribute in JSON Schema V2. This may result in dates not being validated correctly, for example.
If feasible, upgrade to CA API Gateway v9.3, which supports both JSON Schema Validation V2 and V4. The "format" attribute is fully supported when using V4.
Gateway Does Not Connect to Azure MySQL Database (fixed in 9.2 CR10)
An error occurs when you try to connect the
Layer7 API Gateway
to an external Azure MySQL database. Microsoft requires usernames in the format "[email protected]_name", but the Gateway does not allow special characters in usernames. (DE371781)
  1. Create a database on the localhost.
  2. Dump the database to a file using
  3. Create an empty database in the Azure Database for the MySQL instance.
  4. Create the user on the AzureSQL for MySQL instance with the same rights as on the local instance.
  5. Load the dump using this command:
    mysql ssg -h [host] -u [rootuser] -p < dumpfile.sql
Account Lock Outs When Running Gateway in Azure Cloud
You are locked out when attempting to connect to a Gateway running in the Microsoft Azure Cloud. This is caused by the Gateway incorrectly counting successful login attempts as failure attempts. (DE368072)
Edit the
file and move the line "account required" to immediately below the "auth required" line. The file should resemble this:
auth required deny=5 even_deny_root_account onerr=fail unlock_time=1200 root_unlock_time=1200
auth required
account required
auth sufficient try_first_pass
auth requisite uid >= 500 quiet
auth required
Resource Management Causing Performance Issues
The Gateway service must be restarted periodically to resolve slow response/high CPU usage issues. This affects version 9.2 and 9.2 CR1.
There is no workaround. The resolution is to install the
API Gateway
9.2 CR2 or later, where the issue is resolved.
Policy Manager Does Not Display Correctly
The Policy Manager may not display correctly on some high resolution monitors. If you experience display problems such as small fonts and illegible lines, try overriding the high DPI scaling behavior of the executable file. (DE211450)
See procedure to override high DPI scaling behavior in the Troubleshooting section on  Start the Policy Manager.
Known Issues in 9.2 CR3
The 9.2 CR3 cumulative release contains the following issue.
  • MQ Native Routing assertion starts to time out when the connections to MQ Server from Gateway exceeds the value that is defined in mq.ConnectionPool.maxActive cluster property. (DE291462)