Known Issues

This topic describes known issues in version 9.1 of the gateway, with workarounds if available.
gateway91
This topic describes known issues in version 9.1 of the
CA API Gateway
, with workarounds if available.
Decode JSON Web Token Assertion Unaffected by Invalid JWT Signature
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 immediately following the Decode JSON Web Token Assertion and have it test for
${<prefix>.valid}
= true. If the JWT signature fails,
${<prefix>.valid}
returns 'false' causing the 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
        ...
How to Modify OTK Policies
For detailed instructions on how to modify your OAuth Took Kit policies, please refer to "Release Notes" in the CA API Management OAuth Toolkit online documentation.
Performance Issues
Issue:
Excessive transactions caused by application events results in performance issues.
Workaround:
Service Pack v9.1.01 contains several fixes for performance issues caused by unnecessary transaction events.
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. (SSG-13553)
Workaround:
Modify the bundle file 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 installing 9.1.00. This causes the Policy Manager to fail to connect to the Gateway. (SSG-12909)
Workaround: 
Do the following before installing 9.1.00
  1. In the Policy Manager, run the Manage Listen Ports task.
  2. Double-click on port 
    9443
     and then navigate to the SSL/TLS Settings tab.
  3. Make a note of all the cipher suites enabled for this port.
  4. Click 
    Use Default List
     and then 
    OK
    .
  5. Repeat steps 2 to 4 for ports 
    2124
     and 
    8443
    .
  6. Exit the Manage Listen Ports task when done.
You can now install 9.1.00. After installation is complete, revisit the SSL/TLS Settings tab for each of the above ports and reset the supported cipher suites back to the original settings.
Evaluate JSON Path Assertion Incorrectly Returning False
Using the Evaluate JSON Path Expression Assertion to retrieve an object that contains an empty array causes the assertion to incorrectly return 'false' (fail). For example, if the expression is "members" and the input is: {"members":[]}, the assertion fails rather than succeeding and returning a list with zero items. (SSG-13320)
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 
API Gateway
. To correct this, see "Problem: Gateway is not running properly after a restore" in Troubleshoot. (SSG-9735)
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 returns 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}
). (SSG-5372)
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. (SSG-5116)
Dependency Errors when Deleting OAuth Folder
Deleting an OAuth policy that contains policy fragments serving as backing policies for encapsulated assertions will trigger dependency errors in the Policy Manager. These errors cannot be acknowledged in bulk nor can the deletion be cancelled. For workarounds to avoid this, see "Problem: Deleting OAuth policy creates dependency errors" in Troubleshoot. (SSM-5068)
Behavior Change of Client Certificate CN in Require SSL or TLS Transport Assertion
Issue:
The logged CN from the Require SSL or TLS Transport Assertion is from the client certificate's issuer CA, and not from actual CN of the Client Certificate. This change in behavior is intentional and has been in effect since version 9.0. (DE213001)
Workaround:
To revert to the previous behavior found in v8.4 and earlier, see this article on the CA Support site: "TEC1678781 - How to log Client Certificate Common Name".
JSON Schema Validation Unexpected Results
Issue:
The current version of the
CA 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
Issue:
An error occurs when you try to connect the
CA API Gateway
to an external Azure MySQL database. Microsoft requires usernames in the format "username@server_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
    gateway@%
    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