Admin Console Settings

When you install the Akana API Platform, some additional settings become available in the Configuration section for the Akana Administration Console of the container. This document provides information you can use to customize these settings for your installation.

Note that although the configuration settings in the Community Manager developer portal user interface apply to the Community Manager developer portal itself, the Admin Console settings apply only to the container, not the entire deployment. In some cases, configuration settings might need to be set differently in specific containers based on factors such as the features installed in the container and the container's network access.

The Site Admin for the Community Manager developer portal might not have access to the Admin Console for the container; if you do not have access, work with the deployment operator and/or Administrator to change the configuration properties as needed.

For general information regarding the Akana Administration Console, please refer to the applicable online help.

For information about the configuration settings defined by the Akana API Platform Site Admin within the Community Manager developer portal, refer to Site Resource Settings (Site Admin help).

Table of Contents

How do I get to the Akana API Platform Configuration Settings in the Akana Administration Console?

To modify the Akana API Platform settings in the Admin Console, you must be a Site Admin for the Admin Console.

To navigate to the CM configuration settings

  1. Log in to the Akana Administration Console.
  2. Click the Configuration tab.
  3. On the left, under Configuration Categories, scroll down to find the applicable category.
  4. Change the values as needed, and then click Apply Changes.

What are the Akana API Platform Configuration Settings in the Akana Administration Console?

The configuration settings allow you to set values for the specific container. They are in these categories:

Some of the settings are explained below.

com.akana.elasticsearch

Configuration settings that you can use to manage how the Elasticsearch index is distributed across nodes.

elastic.config.index.number.of.replicas
The number of replicas (additional copies) of the Elasticsearch index. Each replica includes a replica of each shard, so one replica might be distributed across multiple nodes, just as the index itself is split into shards which are distributed across nodes.
Default: 1
elastic.config.index.number.of.shards
The number of shards (splits) for the Elasticsearch index.
Note: This is a one-time setting. An Elasticsearch index cannot be re-sharded; if you want to change the number of shards, after changing the setting you'll need to delete the /index folder that the search index is stored in and then rebuild the index.
Default: 2

com.soa.api.security

When the request comes in, the API Security Policy validates whether the request has the correct security values. To do that, it must retrieve the app's shared secret or certificate. This policy caches the app's shared secret, app certificate, or both; these configuration properties manage the caching of these values.

com.soa.api.security.cache.expirationPeriod
Indicates how long an app's shared secret, certificate, or both are stored in the cache, once they are retrieved, if they are not used again. When the expiration time has passed, if the values were not used again, they are removed from the local cache.
Default: 86400000 milliseconds (1 day)
com.soa.api.security.cache.refreshTime
Indicates how long an app's shared secret, certificate, or both are stored in the cache without checking whether the cached data is out of date.
If values are used, they are kept in the cache, but the refresh time governs how often the platform checks to make sure the cached values are still current.
Default: 900000 milliseconds (15 minutes)

com.soa.atmosphere

Config properties for com.soa.atmosphere

atmosphere.config.applyDefaultPasswordRules
Enables or disables the default password rules. Applies to newly added tenants. Default values, if enabled: Minimum length 8, maximum length 64, minimum letters 1, minimum numbers 1, minimum uppercase letters 1, minimum special characters 1, allowed special characters !'#$%&'()*,-./:;<=>?@^_{}, spaces not allowed, password cannot match username or email address.
atmosphere.config.authTokenMaxLength
Because the AtmoAuthToken cookie includes a lot of information about the user, in some cases the auth token is long, and could potentially cause requests to fail if the server has a limitation on HTTP header length. For this reason, container configuration properties include Auth Token Max Length. When the auth token would be greater than the max length, the platform creates a mini auth token, and saves the full auth token in the database.
This causes a slight additional overhead on performance, therefore it is configurable.
Default: 512k
atmosphere.config.authTokenTimeToIdleTimeInSeconds (Valid in version: 2019.1.24 and later)
Removes idle user authorization tokens from the cache after the specified time. Before this setting was introduced, tokens were cached for 30 minutes regardless of their usage. This could use a large chunk of memory, resulting in out-of-memory errors on portal containers. With this setting, idle tokens are removed much sooner, but the setting can be modified as needed.
Default: 62 seconds.
atmosphere.config.businessSettingsCacheRefreshOnChange
Allows security configuration changes to be implemented immediately. When set to false, configuration settings might take up to 5 minutes to take effect due to caching.
Note: The configuration only works when there is no load balancing set up, since the in-memory configuration update is limited to the container instance, not all the instances in the cluster.
Default: false
atmosphere.config.contentPath
Internal use only.
atmosphere.config.csrfHttpWriteSkipUserAgents
Allows you to specify values for the user-agent request header that will be allowed to use POST, PUT, and DELETE operations without providing the custom X-Csrf-Token_fedmemberID header. If one of the specified values is in the user-agent request header, the Akana API Platform does not check for the custom header. Separate multiple values with commas; use wildcard if needed. Example: Mozilla* allows all Mozilla Firefox versions.
Default: No default.
atmosphere.config.defaultFileTypesAllowed
The default list of media types allowed, in Community Manager developer portal security settings, for newly added tenants. The value of this field is used as the default list of media types allowed, for the new tenant. Once the new tenant is created, to update the list of media types allowed, see How do I configure settings for business security?
atmosphere.config.defaultXSSBlackListKeywords
The default list of keywords that are disallowed in certain input fields in the Community Manager developer portal, in Community Manager developer portal security settings, to help prevent cross-site scripting (XSS) attacks. Used only when a new tenant is created. The value of this field is used as the default list of keywords that are disallowed, for the new tenant. Once the new tenant is created, to update the list of disallowed characters, see How do I configure settings for business security?
atmosphere.config.defaultXSSWhiteListKeywords
The default list of characters that are allowed, in Community Manager developer portal security settings, on the allowlist for cross-site scripting prevention. Used only when a new tenant is created. The value of this field is used as the default allowlist for the new tenant. Once the new tenant is created, to update the allowlist, see How do I configure settings for business security?
atmosphere.config.enterpriseInstall
Indicates whether it is an enterprise install (true) or a multi-tenant install (false).
In an enterprise install, the user identity and the user profile name are the same; for example, johnsmith.
In a multi-tenant install, the user identity name is formatted as tenantid-username, for example, acmepaymentscorp-johnsmith.
This helps ensure that if the same user has an account on two different tenants there is no conflict and each account is treated separately.
atmosphere.config.loadContentFromWorkspace
Internal use only.
atmosphere.config.loadResourcesFromWorkspace
Internal use only.
atmosphere.config.resourcesPath
Internal use only.
atmosphere.config.useMimeTypesFile (Valid in version: 2020.2.12 and later)
A property that is not there by default, but which you can add if you want to use the mime.types file. See How do I add the configuration property so that the Community Manager developer portal uses the mime.types file?
Default: False.
atmosphere.config.userRolesDenied
Allows you to set up one or more roles that cannot use this implementation. For example, you might want to dedicate a special container for administrator use only.
Use comma separators as needed. For example: 
Site Administrator,Business Administrator,ApiAdmin, BusinessAdmin,SiteAdmin
For more information, see How do I exclude specific roles from platform access? (Site Admin help for managing users).
atmosphere.config.workflowReservedActions
Internal use only.
openid.provider.proxy
Used in scenarios where there is a federation with a proxy in front of the Akana API Platform. This setting is valid for legacy purposes only.
sni.x509.refresh.job.enabled
Enables or disables the refresh job. If the refresh job is disabled, the tenant x.509 SNI certificate cache will not be refreshed.
Default: true
sni.x509.refresh.trigger.repeatInterval
The interval in milliseconds between each auto refresh of the tenant x.509 SNI certificate cache.
Default: 86400000 milliseconds (1 day)
sni.x509.refresh.trigger.startDelay
The time in milliseconds before the tenant x.509 SNI certificate cache refresh job begins, after the bundle is started.
Default: 1800000

com.soa.atmosphere.console

This configuration category includes settings that affect the Community Manager developer portal Console Resources service. Certain API operations (HTTP GET) in the Console Resources service (context path /resources/{path:.*}) are affected by the settings below. In the Community Manager developer portal, these operations control the initial page load of the user interface.

atmosphere.console.config.xFrameOptions
Allows you to use the X-Frame-Options HTTP response header to indicate whether the browser is allowed to render the Akana API Platform Community Manager developer portal URL in a <frame> or <iframe> which could be embedded in another site.
If this entry is set to Deny, prevention is turned on. In the Community Manager developer portal, this setting can be used to protect two things: the page load, and the GET /resources/{path:.*} operation in the Console Resource platform API service.
This preventive measure helps protect the platform against a clickjacking attack where the content would be embedded in another site.
Valid values: sameorigin, deny.
Note: A third value for the X-Frame-Options header, ALLOW-FROM, is obsolete. Do not use it.
Default: No value set.
Note: There is an additional setting for configuring the X-Frame-Options header. See com.soa.uif below.
atmosphere.context.root
Determines the path for the console URL, from which the Community Manager developer portal is accessed. The value provided is included in the URL in this pattern: {protocol}/{hostname}/{context root value}/#/{path/page}. If no value is provided, the context is {protocol}/{hostname}/; for example, {protocol}/{hostname}/#/home/login.
Example with value provided: developerportal results in a console login URL of http://acmepaymentscorp.com/developerportal/#/home/login. With no value provided, this would be: http://acmepaymentscorp.com/#/home/login.
When installing the product, if you use a value in the installation Jython script other than atmosphere, you'll need to change the context root accordingly.
For instructions on changing this value, see Conditional: updating configuration setting for new context root (installation instructions).

com.soa.atmosphere.forwardproxy

forward.proxy.allowedHosts
Allows you to specify one or more hosts that are allowed for forward proxy. Any other hosts are rejected as unauthorized, with a message that the host is not allowed. To allow all, use the asterisk wildcard (*). To allow multiple hosts, use a comma separator; for example, host1,host2,host3.
Note: This setting applies only to the current container. If you want to set the same value for all containers that are running Akana API Platform, there is a database script you can run to change the setting in the database. For help, contact Technical Support.
Default value: * (allow all).
The Site Admin can set up specific allowed hosts in the user interface: More > Admin >Site > Limit forward proxy feature to allow only these hosts field. However, this field in the Akana Administration Console takes precedence. The setting in the Community Manager developer portal works only if this Admin Console property is set to * (allow all). For more information, see How do I configure site settings?

com.soa.atmosphere.schedule.jobs

These settings allow you to control the scheduled job that purges inactive users. You can enable or disable the job and control how often it runs.

delete.expired.user.job.enabled
Setting this value to false disables the job.
Default value: true.
delete.expired.user.job.trigger.repeatInterval
The interval, in milliseconds, between each process of looking for expired users.
Default value: 86400000 milliseconds (1 day)
delete.expired.user.job.trigger.startDelay
The time, in milliseconds, before the process of looking for expired users job begins, after the bundle is started.
Default value: 600000 (10 minutes)

com.soa.oauth

Indicates settings applicable when the platform is used as an OAuth Resource Server.

Note: These caching properties are node-specific. In a load balancing environment, the properties must be applied individually to each container. Each Network Director has a local cache, and the cache settings apply to that container property only. You must change the property on each Network Director container. The same property is applicable to all containers but must be manually applied on each container.

com.soa.oauth.resourceserver.grant.cacheMaxCapacity
Maximum cache size for OAuth Resource Server grants. See note above re cache settings.
com.soa.oauth.resourceserver.grant.expirationPeriod
Expiration period for OAuth Resource Server grants.
com.soa.oauth.resourceserver.grant.refreshTime
Refresh time for OAuth Resource Server grants: the length of time for which a refresh token is valid.

com.soa.oauth.client.cache

The Akana OAuth Provider feature can add/retrieve OAuth client details to/from an in-memory cache. Configure the settings below in all containers where the Akana OAuth Provider feature is installed.

Note: These caching properties are node-specific. In a load balancing environment, the properties must be applied individually to each container. Each Network Director has a local cache, and the cache settings apply to that container property only. You must change the property on each Network Director container. The same property is applicable to all containers but must be manually applied on each container.

com.soa.oauth.client.cache.dirtyCheckEnabled
Enable/Disable dirty checking of cached client objects.
When this property is enabled, each time the platform retrieves client details from cache it also retrieves the last updated timestamp of the OAuth client/application from the database and compares to see if the application has been modified since it was added to the cache. If there is a change, it retrieves the specific details from the database, returns them to the caller, and updates the cache. This means that app changes are immediately reflected in the OAuth Provider. However, there can be a performance impact.
If this property is set to false, caching is used.
Default: true.
com.soa.oauth.client.cache.lifeTime
The number of seconds for which the client details can be stored in cache. After this, the client details must be refreshed in the cache during the next scheduled job run.

com.soa.oauth.provider

Indicates settings are applicable when the platform is used as an OAuth Provider. Tuning the settings to your installation can help you achieve better performance and make the OAuth Provider more scalable. To access the settings, log in to the Policy Manager console and go to Configuration > com.soa.oauth.provider.

The following settings are available:

com.soa.oauth.provider.config.allowedAuthenticationTokenLength
Indicates the allowable length for the OAuth token.
com.soa.oauth.provider.config.allowedClockSkewInSecondsForJWT
Indicates the allowable clock skew value, in seconds, for JSON web key tokens.
com.soa.oauth.provider.config.defaultJwkValidityInSeconds
When asymmetric signature keys are used to sign ID tokens, the keys are rolled over by periodically adding new keys to the JWK Set. By default, all JSON Web Keys that the Community Manager developer portal's OpenID Connect provider create will have a validity of 24 hours (86400 seconds). This setting allows you to modify the validity period.
com.soa.oauth.provider.config.grantAttributesCacheExpirationTime
The expiration time for grant attributes stored in the cache, in milliseconds. A scheduler takes care of refreshing the cache entries depending upon their expiration, as follows:
  • Value = 0: the cache is not cleared. Cache entries are retained.
  • Value < 0 (negative number): the cache is deleted.
  • Value > 0 (positive number): the scheduler checks the last access time of the entry. If the last access time is greater than the expiration time, the cache entry is expired since this indicates that probably the grant attributes are no longer required. If they are required, they are retrieved from the database.
com.soa.oauth.provider.config.grantAttributesCacheMaxSize
Maximum cache size for OAuth Provider grants. The cache cannot exceed the max size. The scheduler uses the cache max size and cache expiration time to refresh and update the cache data.
com.soa.oauth.provider.config.grantSequenceIDCacheExpirationTime
The cache expiration time for the Grant sequence ID (seqID) in the cache, in milliseconds. This property works in the same way as grantAttributesCacheExpirationTime above, for the grant seqID. The scheduler takes care of refreshing the cache entries depending upon their expiration, as follows:
  • Value = 0: the cache is not cleared. Cache entries are retained.
  • Value < 0 (negative number): the cache is deleted.
  • Value > 0 (positive number): the scheduler checks the last access time of the entry . If the last access time is greater than the expiration time, the cache entry is expired since this indicates that probably the grant sequence ID is no longer required. If it is required, it is retrieved from the database.
com.soa.oauth.provider.config.grantSequenceIDCacheCacheMaxSize
Maximum cache size for OAuth grantSeqID values. The grantSeqID represents a unique OAuth grant or token, and is the primary key of the OAUTH_GRANTS table as well as the OAUTH_TOKENS table. When doing a lookup for a grant or grant-related properties, instead of querying on huge grants or the tokens table it is faster to fetch it from cache.
com.soa.oauth.provider.config.maxRedirectURLLength
Indicates the maximum allowable length of a redirect URL when the platform is used as an OAuth Resource Server.
com.soa.oauth.provider.config.rsaJwkKeySize
Indicates the RSA JSON Web Key size when the platform is used as an OAuth Resource Server.

com.soa.oauth.agent.client.cache

The platform's OAuth provider can add/retrieve OAuth client details to/from an in-memory cache. Configure the settings below in all containers where the Akana OAuth Provider feature is installed.

Note: These caching properties are node-specific. In a load balancing environment, the properties must be applied individually to each container. Each Network Director has a local cache, and the cache settings apply to that container property only. You must change the property on each Network Director container. The same property is applicable to all containers but must be manually applied on each container.

com.soa.oauth.agent.client.cache.dirtyCheckEnabled
Enable/Disable dirty checking of cached client objects.
When this property is enabled, each time the platform retrieves client details from cache it also retrieves the last updated timestamp of the OAuth client/application from the database and compares to see if the application has been modified since it was added to the cache. If there is a change, it retrieves the specific details from the database and returns them to the caller, and updates the cache.
True if enabled, false otherwise.
com.soa.oauth.agent.client.cache.lifeTime
The number of seconds for which the client details can be stored in cache. After this, the client details must be refreshed in the cache during the next scheduled job run.

com.soa.uif

This configuration category includes settings that affect the user interface framework. The UI framework is used by the Community Manager developer portal as well as certain other Akana products such as Envision. For example, in the Community Manager developer portal, API operations in the platform's UI Application service (context path /ui/apps/) are affected by the setting below. These API operations upload and manage platform resources such as platform CSS, customizable platform content pages, and platform help files.

uif.config.xFrameOptions (Valid in version: 2019.1.3 and later)
The X-Frame-Options header is an optional header sometimes used as a security measure to control whether content can be displayed within an <iframe> tag. When a value is set for this property, the platform uses the configured value for the X-Frame-Options header returned by API operations in the platform's UI Application service (context path /ui/apps/), that return Community Manager developer portal content. You can set a value for this header for protection against cross-frame scripting. Valid values: sameorigin, deny.
Note: A third value for the X-Frame-Options header, ALLOW-FROM, is obsolete. Do not use it.
Default: No value.

How do I add the configuration property so that the Community Manager developer portal uses the mime.types file?

Valid in Version: 2020.2.12 and later

For additional security, you can add a configuration setting to the Akana Administration Console, com.soa.atmosphere category, to configure the platform to reference the mime.types file, a file that maps Internet media types to unique file extensions. For example, this file maps the file extensions htm and html to the MIME type text/html.

If this file is in use, the platform performs the following checks against the file, for security purposes:

  1. The platform checks the file extension and uses the mime.types file to determine the MIME type. If the MIME type is not on the list of file types allowed for upload, in the Community Manager developer portal security settings (see How do I configure settings for business security?, Limit file types allowed for upload setting), the file is rejected.
  2. If the file matches a valid MIME type that is allowed in the security settings. the platform checks the content of the file to ensure that the file is actually the declared file type. If it is not, the file is rejected. For example, if a file is named index.htm but is not a valid HTML file, it is rejected. This helps prevent malicious file content being passed as a supported file type.

To use this file, you'll need to manually add a configuration setting with a value of true. Follow the steps below.

To add a configuration property to use the mime-types file

  1. Log in to the Akana Administration Console for the Community Manager developer portal instance.
  2. Click the Configuration tab.
  3. In the Configuration Categories section on the left, choose com.soa.atmosphere.
  4. At the bottom right, click Add Property. The Add Configuration Property overlay appears.
  5. Enter the following:
    • Property Name: atmosphere.config.useMimeTypesFile
    • Property Value: true
  6. Click Apply to save the change and close the overlay.
  7. Click Apply Changes.

By default, the mime.types file is not used, which equates to a setting of false.

How do I get to the MongoDB Configuration Settings in the Akana Administration Console?

Before you can access the MongoDB configuration settings, you'll need to install an additional optional product feature. This provides connectivity to a MongoDB instance for features that have NoSQL persistence capabilities.

Once the add-on is installed, in the Akana Administration Console, go to Configuration > com.soa.persistence.mongodb and configure the settings as needed. For additional information, refer to Using the MongoDB Support Feature. Notes on a few settings are below:

  • com.akana.persistence.oidc.provider.dataset.8.0.0: indicates whether OAuth Provider collections are in the database.
  • persistence.mongodb.async.thread: Number of threads to process asynchronous requests

Note: When the MongoDB plug-in is installed and MongoDB is configured, the auditing data automatically uses MongoDB; there is no option to use MongoDB for OAuth and the RDBMS for auditing information, unless different features are installed in different containers.

What are the configuration options to guard against potential security vulnerabilities in the platform?

There are a number of different ways that you can adjust platform configuration to increase security in the platform.

For a full list, covering settings in the Akana Administration Console and also settings in the Community Manager developer portal, see Akana Platform Hardening Guide.