Customize Caches

OTK policies take advantage of caching to avoid database calls and improve performance. The policies use local caches (visible on a single node only) and database backed caches (visible throughout all cluster nodes). Default configuration for these caches is optimized for performance. Although you can customize the configuration of these caches to your specifications, we recommend that you use the default values.
otk40
OTK policies take advantage of caching to avoid database calls and improve performance. The policies use local caches (visible on a single node only) and database backed caches (visible throughout all cluster nodes). Default configuration for these caches is optimized for performance. Although you can customize the configuration of these caches to your specifications, we recommend that you use the default values.
Customization of cache properties is more likely when you create caches for your own services.
The following sections relate to OTK cache customization:
OTK Cache Assertions
Centralized customization of caches is made possible by using the following OTK Cache encapsulated assertions instead of local cache assertions (Look Up in Cache, Store to Cache):
  • OTK Cache Look Up
  • OTK Cache Store
  • OTK Cache Remove
  • OTK Cache Flush
These OTK encapsulated assertions are used in multiple policies. See Existing Caches and Policies.
Cache Identification
Identification of the cache for setting custom values requires the combination of two input variables: 
  •  
    cacheID
     
  •  
    maxEntryAge 
     
Together these variables are used to create the 
actualCacheID
 variable.
Identification of the cache contents requires the following variable:
  •  
    cacheKey
     
Default Cache Settings
Default settings for the OTK cache assertions are set in the read-only OTK Cache Handler policy. 
The following input variables are set with default values and are used as criteria for storage, retrieval, and removal operations:
  •  
    maxEntries
     – The default is 10000.
    Indicates the number of cached entries that a store can hold. When this maximum is reached, each new item replaces the oldest one in the store.
  •  
    maxEntryAge
     – The default is 300 seconds.
    Indicates the maximum age (in seconds) of items in the cache before they are discarded.
  •  
    maxEntrySize
     – The default is 10000 bytes.
    Indicates the maximum size (in bytes) of the items to cache.
The Cache Handler policy and the OTK encapsulated assertions are located in OTK/Policy Fragments/caching.
Encapsulated Assertions
OTK Cache
Encapsulated Assertion
Required Input Variables
Optional Input Variables
Notes
OTK Cache Store
cacheID
cacheKey
maxEntriesmaxEntryAge
maxEntrySize
Stores an item to the cache. If the cache does not exist, one is created. If the key exists, the existing item is overwritten. Reduces the load on back-end services and improves response times.
Optional Variables:
maxEntries – The number of cached entries that the store can hold. When this maximum is reached, each new item replaces the oldest one in the store.
maxEntryAge – The maximum age (in seconds) of items in the cache before they are discarded.
maxEntrySize – The maximum size (in bytes) of the items to cache.
OTK Cache Look Up
 
cacheID
cacheKey
 
maxEntryAge
Retrieves the cached contents from an existing cache store. On success, the contents are placed into the message target of your choice (request, response, or context variable). On failure, an error is returned.
The maxEntryAge variable acts as a filter. If an item is determined to be below this age, it is retrieved from the cache and returned in the response. If the cached item exceeds this age, it is not retrieved.
OTK Cache Remove
cacheID
cacheKey
maxEntriesmaxEntryAge
maxEntrySize
Removes an item from the cache.
Items meeting criteria set by any of the optional properties are removed. Items exceeding any of the maximum thresholds set by optional properties remain in the cache.
 
OTK Cache Flush
cacheID
maxEntryAge
Empties the cache.
If an item is determined to exceed the maxEntryAge value, it remains in the cache.
Examine existing policies such as OTK Client Validation to learn how the OTK Cache Look Up and OTK Cache Store assertions are used together.
OTK Cache Remove and OTK Cache Flush assertions are used for the specific removal of items and cache clean up.
Customizing OTK Cache Properties
The OTK Cache policies can be customized to override the cache assertions that are used in individual caches. Identification of the cache is made by 
cacheID
 and 
maxEntryAge
.
The OTK/Customizations/caching folder contains the following policies:
 
OTK Caching Customization
 
Create custom cache values in the OTK Caching Customization policy. Identify a specific cache by the combination of 
cacheID
 and 
maxEntryAge
. Together these values create the 
actualCacheID
 variable that is used by the look up and store cache operations.   
To customize a cache: 
  1. Go to OTK/Customizations/caching.
  2. Open the OTK Caching Customization policy. 
  3. Expand the folders, right-click, and select 
    Enable All Assertions
  4. Click 
    Show Comments 
    to view the example.
     
  5. Double-click the "Compare Variable: ${cacheID} is equal to myCache: If Multivalued all values must pass" assertion.
  6. Click 
    Edit
     and replace the Right Expression "myCache" default value with the 
    cacheID
     of the cache you want to customize.
    For example, "accessTokenValidation". 
  7. Click 
    OK
    .cacheIDreplaced.png 
  8. Provide custom values for one or more Context Variables.
    The screenshot shows customization of the accessTokenValidation cache with the maxEntryAge Context Variable set to zero (0). This setting requires a database lookup for each single access_token validation. 
    maxEntryAgeCustom.png 
  9. Remember to delete any Context Variables that you do not want to customize!
    The Context Variable settings in the OTK Caching Customization policy override the default settings in the policies using the cache.
  10.  
    Save and Activate
Monitoring Caches
Use the Add Audit Detail assertion to monitor content going into and retrieved from the cache.  
The messages are recorded either in the audit records or a Gateway log, depending on how the assertion is configured.  If audit details are directed to the audit log, the message appears in  the "Associated Logs" tab in the Event Details Pane of the Gateway Audit Events window.
To monitor content going into the cache:
  1. Open the OTK Cache Store Customization policy.
  2. Place an 
    Add Audit Details
     assertion before the 
    Store to Cache
     Assertion. 
  3. Double-click the Add Audit Details assertion and add the properties you want to return. See Audit Detail Properties.
  4.  
    Save and Activate
    .
To monitor content retrieved from the cache: 
  1. Open the OTK Cache Lookup Customization policy
  2. Place an 
    Add Audit Details
     assertion after of the 
    Look Up in Cache
     assertion.
  3. Double-click the Add Audit Details assertion and add the properties you want to return. See Audit Detail Properties.
  4.  
    Save and Activate
    .
 
Audit Detail Properties
 image2017-3-1 16:3:46.png 
Setting
Description
 
Message
 
Type a message in the box. This message is displayed when the audit appears in the Gateway Audit Events window.
Include context variables within the message to reveal additional information about the audit condition, if necessary.
 
Audit
 
Select this option to direct the audit detail message to the Audit log sink.
 
Log
 
Select this option to direct the audit detail message to the Gateway log sink. This is useful for situations where (for example) the logged information is too large to be comfortably stored in the audit database for extended periods of time. For example, storing trace information from a policy debug tracing.
 
Custom logger name
 
Select this check box if you want the logged information to be identified by a custom logger name, rather than the default logger name com.l7tech.server.policy.assertion.ServerAuditDetailAssertion.
If you choose to use a custom logger name, enter a suffix to be added to the custom logger name, to ensure uniqueness. You can reference context variables.
If a specified context variable cannot be resolved during run time, the default logger name shown above is used.
 
Level
 
Select a severity level for your message from the drop-down list. This level, along with the level set in the Audit Messages in Policy assertion, determines whether your message appears in the Gateway Audit Events window.
 
 
Existing Caches and Policies
For your reference, the following caches are used by read-only OTK policies and target endpoints. 
Cache ID
Target Policy or Endpoint
Using this Cache 
Notes
allClientValuesCache
OTK Client DB GetOTK Client DB Revoke KeyOTK Client DB UpdateOTK Client NoSQL GetOTK Client NoSQL Revoke KeyOTK Client NoSQL Update
The cache stores client values when access_token requests are made. The maxEntryAge value determines how often the client configuration is looked up from the database.
Reduce the cache maxEntryAge value for more frequent calls. Increase the value for less frequent calls.
allClientValidationValuesCache
OTK Client DB Revoke Key
OTK Client DB Update
OTK Client NoSQL Revoke Key
OTK Client NoSQL Update
OTK Client Validation 
 
OTK Client Validation is used to validate that the client is still active in the system.
By default, the allClientValidationValuesCache stores the following client details:
client_type
client_name
scope
environment
created_by
client_custom
client_key_custom
serviceids
accountplanmappingids
client_secret 
 
defaultCache
OTK Session DB
Caches the OTK session information.
The cache name can be configured when using any encapsulated assertion named "OTK Session".
openIDConnectCache
OTK Session GET
Used to retrieve values associated with an authorization_code in the context of OpenID Connect when the client exchanges the code for an access_token.
OTK grant_type=AUTHORIZATION_CODE
accessTokenValidation
OTK Require OAuth 2.0 Token
Caches access_token validation results at OAuth 2.0 protected endpoints. This value is a compromise between performance and accepted lifetime of invalid tokens. The default cache time for saving client information is set to 30 seconds. Increasing this time elevates the risk of unauthorized access. 
The lifetime value is passed in through the interface of the encapsulated assertion wherever access_token_validation is used. Modify the cache lifetime to lookup access_tokens from the database more or less frequently.
A lifetime value of 0 reduces performance by requiring a database lookup for each single access_token validation. Increasing the lifetime value extends the expiration time of an access_token.
authorizeCache
/auth/oauth/v2/authorize
Caches the static content on the authorization server website (except for images). This is useful if the website is hosted on an external web server.
If the website template for the authorization server website changes often, consider modifying the cache lifetime. The cache does not include form values of images.
userSessionIDCacheV2
/auth/oauth/v2/authorize
OTK Session - Store
Used with the session cookie "l7otk2a"
Customize the lifetime of the user session (cookie lifetime) by modifying the variable "ownerCacheAge. The value is expressed in seconds.
l7ManagerCache
/oauth/manager
/oauth/manager/clients
/oauth/manager/tokens
OTK Session - Store
Used with the cookie "l7manager".
consumerSecretCache
/oauth/validation/validate/v1/signature
Used with temporary values during the OAuth 1.0 flow to validate the signature.