Known Issues

This topic describes known issues in version 9.2 and 9.2 CR3 of the gateway, with workarounds if available.
gateway92
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
2
Gateway Now Uses SunJSSE TLS Provider: Increased Time for Authentication Bind Operation
Issue:
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.
Workaround:
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).
Issue:
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)
Workaround:
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
${
<prefix>
.valid}
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.
    Before:
    At least one assertion must evaluate to true
    ...
    Decode JSON Web Token
    ...
    After:
    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).
Issue:
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
Workaround:
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:
TLS_DH_RSA_WITH_AES_128_GCM_SHA256
TLS_DH_DSS_WITH_AES_128_GCM_SHA256
TLS_DH_RSA_WITH_AES_256_GCM_SHA384
TLS_DH_DSS_WITH_AES_256_GCM_SHA384
TLS_DH_RSA_WITH_AES_128_CBC_SHA256
TLS_DH_DSS_WITH_AES_128_CBC_SHA256
TLS_DH_RSA_WITH_AES_256_CBC_SHA256
TLS_DH_DSS_WITH_AES_256_CBC_SHA256
TLS_DH_RSA_WITH_AES_128_CBC_SHA
TLS_DH_DSS_WITH_AES_128_CBC_SHA
TLS_DH_RSA_WITH_AES_256_CBC_SHA
TLS_DH_DSS_WITH_AES_256_CBC_SHA
SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA
SSL_DH_RSA_WITH_DES_CBC_SHA
SSL_DH_DSS_WITH_DES_CBC_SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_RC4_128_MD5
TLS_ECDH_RSA_WITH_RC4_128_SHA
TLS_ECDH_anon_WITH_RC4_128_SHA
SSL_DH_anon_WITH_RC4_128_MD5
SSL_NULL_WITH_NULL_NULL
TLS_RENEGO_PROTECTION_REQUEST
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
TLS_ECDH_ECDSA_WITH_RC4_128_SHA
Migration Issue Between Gateways
Issue:
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)
Workaround:
Modify the bundle file that is created during bundle export as follows:
Locate this line:
<l7:Mapping action="NewOrExisting" srcId="
<unique_ID>
" srcUri="http://
<IP_address>
:8080/restman/1.0/firewallRules/
<identifier>
" type="FIREWALL_RULE"/>
And then modify it as follows:
<l7:Mapping action="NewOrExisting" srcId="
<unique_ID>
" srcUri="http://
<IP_address>
:8080/restman/1.0/firewallRules/
<identifier>
" type="FIREWALL_RULE">
<l7:Properties>
<l7:Property key="
MapBy
">
<l7:StringValue>
name
</l7:StringValue>
</l7:Property>
</l7:Properties>
</l7:Mapping>
Gateway Fails to Start When Thales HSM Is Present
Issue:
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)
Workaround:
Do the following after upgrading to 9.2.00
  1. Disable use of the HSM in the Gateway main menu, using option
    6
    (Manage HSM), then option
    1
    (Manage Gateway Thales nShieldHSM status).
  2. In the Policy Manager, run the  Manage Listen Ports task.
  3. Double-click on port
    9443
    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
    OK
    .
  6. Repeat steps 2 to 4 for ports
    2124
    and
    8443
    .
  7. Exit the Manage Listen Ports task when done.
  8. Re-enable use of the HSM in the Gateway main menu, using option
    6
    (Manage HSM), then option
    3
    (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
Issue:
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 client.java.security.KeyStoreException: Luna provider not configured
Workaround:
  1. Open the
    /opt/SecureSpan/JDK/jre/lib/security/java.security
    file in a text editor.
  2. Add the following line to the file:
    security.provider.10=com.safenetinc.luna.provider.LunaProvider
  3. Save and exit the file.
  4. Restart the
    Layer7 API Gateway
    .
Use of SSLv3 Protocol
Issue:
The SSLv3 protocol is considered insecure and obsolete and is deactivated in the latest JDK. Please see http://disablessl3.com 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)
Workaround:
If SSLv3 is absolutely required for legacy compatibility purposes, do the following to re-enable it:
  1. Open this file in a text editor:
    /opt/SecureSpan/JDK/jre/lib/security/java.security
  2. Remove "
    SSLv3
    " from the
    jdk.tls.disabledAlgorithms
    property.
  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
ssgrestore.sh
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.,
${request.username}
,
${request.password}
). (DE215522)
HTTP Keep-Alive Is Ignored in HTTP Routing Assertion
Issue:
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.
Workaround:
Set com.l7tech.server.policy.assertion.ServerHttpRoutingAssertion.statePool.enable=true in /opt/SecureSpan/Gateway/node/default/etc/conf/system.properties. 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
Issue:
When the policy encounters the invalid cookie, the logs show that an exception is thrown. The user is not authenticated or authorized.
Workaround:
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
Issue:
  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.
Workaround
: 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
Issue:
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.
Workaround:
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
Issue:
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
security.fips.enabled
= true).
Workaround:
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
Issue:
The WebSocket server fails to initialize after installing the
Layer7 API Gateway
Enterprise license. (DE263359)
Workaround:
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
Issue:
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.
Workaround:
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
Issue:
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.
Workaround:
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)
Issue:
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)
Workaround:
  1. Create a database on the localhost.
  2. Dump the database to a file using
    mysqldump
    .
  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
Issue:
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)
Workaround:
Edit the
/etc/pam.d/password-auth
file and move the line "account required pam_tally2.so" to immediately below the "auth required pam_env.so" line. The file should resemble this:
auth required pam_tally2.so deny=5 even_deny_root_account onerr=fail unlock_time=1200 root_unlock_time=1200
auth required pam_env.so
account required pam_tally2.so
auth sufficient pam_unix.so try_first_pass
auth requisite pam_succeed_if.so uid >= 500 quiet
auth required pam_deny.so
Resource Management Causing Performance Issues
Issue:
The Gateway service must be restarted periodically to resolve slow response/high CPU usage issues. This affects version 9.2 and 9.2 CR1.
Workaround:
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
Issue:
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)
Workaround:
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)