API Manager Configuration Catalog¶
The new configuration model based on the toml format is introduced from API Manager 3.0.0 onwards. In older versions of the product, users had to modify different configuration files depending on the components related to the specific feature they were configuring. With this update, all configuration files have been merged to make configurations easier. Therefore, the <API-M_HOME>/repository/conf/deployment.toml file is the single source used to configure and tune the various features in API Manager.
This document describes all the configuration parameters that are used in WSO2 API Manager.
Instructions for use¶
Select the configuration sections, parameters, and values that are required for your use and add them to the .toml file. See the example .toml file given below.
# This is an example .toml file.
[server]
pattern="value"
enable_port_forward=true
[key_mgr_node]
endpoints="value"
[gateway]
gateway_environments=["dev","test"]
[[database]]
pool_options.maxActiv=5
Server¶
[server]
hostname = "localhost"
#offset=0
mode = "single" #single or ha
base_path = "${carbon.protocol}://${carbon.host}:${carbon.management.port}"
#discard_empty_caches = false
server_role = "default"
disable_shutdown_from_ui = false
disable_restart_from_ui = false[server]
Required
This includes configurations required for configuring the deployment parameters that are used for identifying an API Manager server node.
hostname
string Required
localhost
localhost,127.0.0.1,<any-ip-address>,<any-hostname>
The hostname or IP address of the machine hosting the API Manager instance.
offset
integer
0
Port offset allows you to run multiple WSO2 products, multiple instances of a WSO2 product, or multiple WSO2 product clusters on the same server or virtual machine (VM). Port offset defines the number by which all ports defined in the runtime such as the HTTP/S ports will be offset. For example, if the default HTTP port is 9443 and the port offset is 1, the effective HTTP port will be 9444. Therefore, for each additional WSO2 product instance, set the port offset to a unique value so that they can all run on the same server without any port conflicts.
server_role
string Required
default
default,api-devportal,api-key-manager,api-publisher,gateway-worker,traffic-manager
The profile name of the API Manager instance.
enableMTOM
boolean
false
true,false
Use this paramater to enable MTOM (Message Transmission Optimization Mechanism) for the product server.
enableSwA
boolean
false
true,false
Use this paramater to enable SwA (SOAP with Attachments) for the product server. When SwA is enabled, the API Manager will process the files attached to SOAP messages.
disable_shutdown_from_ui
boolean
false
true,false
Use this parameter to disable the shutdown server option from carbon management console UI.
disable_restart_from_ui
boolean
false
true,false
Use this parameter to disable the restart server option from carbon management console UI.
Super admin configurations¶
[super_admin]
username = "admin"
password = "admin"
create_admin_account = true
[super_admin]
Required
This includes the configurations related to the super admin user.
username
string
admin
super admin username
password
string
admin
super admin password
create_admin_account
string
TRUE
Set this to true to create a new user with the super admin details given.
Enabling the H2 database console¶
[database_configuration]
enable_h2_console = true[database_configuration]
Configurations required to enable browsing the H2 database from a web browser.
enable_h2_console
boolean Required
false
true, false
True when required to browser the H2 database from a browser. False when not.
Database configurations¶
[database.apim_db]
type = "h2"
url = "jdbc:h2:./repository/database/WSO2AM_DB;DB_CLOSE_ON_EXIT=FALSE"
username = "wso2carbon"
password = "wso2carbon"[database.apim_db]
Required
Database configurations related to API Manager
type
string Required
h2
mysql,h2,mssql,postgre,oracle,db2
Database vendor
hostname
string Required
You can use either hostname and port or the URL(given below). If you specify the URL the hostname and port will be overridden.
port
string Required
url
string
jdbc:h2:repository/database/WSO2AM_DB;DB_CLOSE_ON_EXIT=FALSE
The connection URL is required when you use the h2 db. You have to add the URL to use the JDBC properties listed below. Otherwise it is optional.
username
string Required
wso2carbon
The username used to create a connection to the database.
password
string Required
wso2carbon
The password used to create a connection to the database.
validationQuery
string Required
SELECT 1
The value changes according to the Database query
pool_options.maxActive
string
50
The maximum number of active connections that can be allocated from the connection pool at the same time. Change according to the preferred database.
pool_options.maxWait
string
60000
The maximum time that requests are expected to wait in the queue for a connection to be released. This property comes into effect when the maximum number of active connections allowed in the connection pool (see maxActive property) is used up.
pool_options.testOnBorrow
string
TRUE
The indication of whether connection objects will be validated before they are borrowed from the pool. If the object validation fails, the connection is dropped from the pool, and there will be an attempt to borrow another connection.
pool_options.validationInterval
string
30000
This parameter controls how frequently a given validation query is executed (time in milliseconds). That is, if a connection is due for validation, but has been validated previously within this interval, it will not be validated again.
pool_options.defaultAutoCommit
string
TRUE
When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.
Shared database configurations¶
[database.shared_db]
type = "h2"
url = "jdbc:h2:./repository/database/WSO2SHARED_DB;DB_CLOSE_ON_EXIT=FALSE"
username = "wso2carbon"
password = "wso2carbon"[database.shared_db]
Required
Configurations related to the databases shared between nodes
type
string
h2
mysql,h2,mssql,postgre,oracle,db2
Database type
url
string
jdbc:h2:repository/database/WSO2SHARED_DB;DB_CLOSE_ON_EXIT=FALSE
connection url
username
string
wso2carbon
username
password
string
wso2carbon
password
JWT Configurations¶
[apim.jwt]
enable = true
encoding = "base64"
generator_impl = "org.wso2.carbon.apimgt.keymgt.token.JWTGenerator"
claim_dialect = "http://wso2.org/claims"
header = "X-JWT-Assertion"
signing_algorithm = "SHA256withRSA"
enable_user_claims = true
claims_extractor_impl = "org.wso2.carbon.apimgt.impl.token.DefaultClaimsRetriever"[apim.jwt]
Required
Enable APIM to generate a JWT within itself. JSON Web Token (JWT) is used to represent claims that are transferred between two parties such as the end-user and the backend.
enable
string Required
FALSE
true, false
Enable JWT.
encoding
string
base64
base64,base64url
Use base64 encoding for the default JWT generator. Use the url-safe JWT generator if it is base64url.
header
string
X-JWT-Assertion
The HTTP header name used to send the JWT generated prev.
enable_user_claims
string
FALSE
false true
No user store claims included in the JWT if false.
claims_extractor_impl
string
You can define the custom claim retiriver implmentation by adding the following apim.jwt.enable_user_claims=true. Make sure that it is the fully-qualified class name.
claim_dialect
string
http://wso2.org/claims
A set of claims are identified as a dialect. Different dialects represent the same piece of information with different claim URIs.
signing_algorithm
string
SHA256withRSA
NONE
Specify NONE to disbale the sigining.
enable_claim_retrieval
boolean
true, false
Enable to add user claims to the backend JWT token. This will provide the user claims related to the authorized user to the default Keymanager implementation. For custom keymanager implementations, implement the getUserClaims() in the KeyManager implementation.
gateway_generator.impl
string
org.wso2.carbon.apimgt.gateway.handlers.security.jwt.generator.APIMgtGatewayJWTGeneratorImpl
Fully qualified custom JWT generator to used in JWT(Self Contained) Access Tokens.
gateway_generator.excluded_claims
string
List of claims that are not supposed to be included in the Backend JWT when using JWT (Self Contained) Access Tokens.
binding_federated_user_claims
boolean
false
true, false
This disables the binding federated user claims to the backend JWT generator.
use_kid_property
boolean
true
true, false
Specifies whether the backend JWT header should include the kid claim.
use_sha256_hash
boolean
false
true, false
Specifies whether the certificate header is signed using the SHA256 algorithm. The default algorithm used to generate the header value is SHA1.
[[apim.jwt.issuer]]
name = "https://test.apim.integration"[apim.jwt.issuer]
To specify the issuers of the JWT tokens if third-party Key Managers are used.
name
string
The issuer name of the JWT.
[apim.jwt.issuer.jwks]
url = "https://localhost:8743/jwks/1.0"[apim.jwt.issuer.jwks]
To specify the JSON Web Key Set (JWKS) endpoint of the issuer.
url
string
The JWKS endpoint URL of the issuer.
[[apim.jwt.issuer.claim_mapping]]
remote_claim = "http://idp1.org/claims/givenname"
local_claim = "http://wso2.org/claims/givenname"[apim.jwt.issuer.claim_mapping]
remote_claim
string
The name of the remote claim.
local_claim
string
The local claim name that the remote claim needs to be mapped to.
API-M gateway environment configurations¶
[[apim.gateway.environment]]
name = "Default"
type = "hybrid"
display_in_api_console = true
description = "This is a hybrid gateway that handles both production and sandbox token traffic."
show_as_token_endpoint_url = true
service_url = "https://localhost:${mgt.transport.https.port}/services/"
username = "admin"
password = "admin"
ws_endpoint = "ws://localhost:9099"
http_endpoint = "http://localhost:${http.nio.port}"
https_endpoint = "https://localhost:${https.nio.port}"[apim.gateway.environment]
Required
Configuring the gateways used by API Manager.
name
string Required
Default
User can add preferred values as the name.
type
string Required
hybrid
production, sandbox, hybrid
display_in_api_console
string Required
TRUE
Displays the environment under 'Try it' in the API Developer Portal, in the API console.
description
string Required
This is a hybrid gateway that handles both production and sandbox token traffic.
Describe the function of the gateway here.
show_as_token_endpoint_url
string Required
TRUE
Use to construct the sample curl request in the API Developer Portal.
service_url
string Required
https://localhost:9443/services/
APIs will be published using this URL
username
string Required
$conf{super_admin.username}
Credentials used to publish APIs
password
string Required
$conf{super_admin.password}
Credentials used to publish APIs
ws_endpoint
string Required
no default value
E.g., ws://localhost:9099
https_endpoint
string Required
no default value
https://localhost:8243/
http_endpoint
string
no default value
http://localhost:8280/
[apim.sync_runtime_artifacts.gateway]
gateway_labels = ["Default"][apim.sync_runtime_artifacts.gateway]
Required
Define information on labels that the gateway is going to subscribe to. Only the APIs with these labels will be pulled from the extension point and deployed
gateway_labels
string array Required
Default
TestGWLabel,Default
Array of the labels that the gateway is going to subscribe to
Virtual host of API-M gateway environment configurations¶
[[apim.gateway.environment]]
name = "Default"
type = "hybrid"
display_in_api_console = true
description = "This is a hybrid gateway that handles both production and sandbox token traffic."
show_as_token_endpoint_url = true
service_url = "https://localhost:${mgt.transport.https.port}/services/"
username = "admin"
password = "admin"
ws_endpoint = "ws://localhost:9099"
http_endpoint = "http://localhost:${http.nio.port}"
https_endpoint = "https://localhost:${https.nio.port}"[apim.gateway.environment.virtual_host]
Configuring virtual host for the gateways environment.
http_endpoint
string
http://<host of https endpoint>:80
http://<host>:<por>/<optional context>
HTTP endpoint e.g. http://dev.wso2.com:8280
https_endpoint
string Required
https://<host>:<por>/<optional context>
HTTPS endpoint e.g. https://dev.wso2.com:8243
ws_endpoint
string
ws://<host of https endpoint>:9099
ws://<host>:<por>
WS endpoint e.g. ws://dev.wso2.com:9099
wss_endpoint
string
wss://<host of https endpoint>:8099
wss://<host>:<por>
WSS endpoint e.g. wss://dev.wso2.com:8099
Gateway token cache¶
[apim.cache.gateway_token]
enable = true
expiry_time = "900s"
[apim.cache.gateway_token]
Required
enable
string
TRUE
Enable the gateway token cache. WSO2 recommends to enable this feature by default. The token validation request checks with the cached value.
expiry_time
string
15 m
Set the cache expiry time in minutes. Recommended value is 15 minutes.
Cache resource¶
[apim.cache.resource]
enable = true
expiry_time = "900s"[apim.cache.resource]
Required
enable
string
TRUE
Enable the gateway resource cache. Caches the API resources at the gateway. Expires in 15 minutes.
Keymanager token cache¶
[apim.cache.km_token]
enable = false
expiry_time = "15m"[apim.cache.km_token]
Required
enable
string
FALSE
Enable the Key Manager token cache. The token validation request checks with the value cached at the Key Manager. At any given time you should only have one cache enabled, which is either the Key Manager cache or the API Gateway cache. WSO2 does not recommend using both caches at the same time.
expiry_time
string
15 m
Set the cache expiry time.
Cache recent APIs¶
[apim.cache.recent_apis]
enable = false[apim.cache.recent_apis]
Required
enable
string
FALSE
Enable cache for recently added apis in the API Developer Portal. This expires in 15 minutes by default.
Cache scopes¶
[apim.cache.scopes]
enable = true[apim.cache.scopes]
Required
enable
string
TRUE
Enabel cache for scopes. This expires in 15 minutes by default.
Cache publisher roles¶
[apim.cache.publisher_roles]
enable = true[apim.cache.publisher_roles]
Required
enable
string
TRUE
Enable cache for publisher roles. Expires in 15 minutes by default
Cache JWT claims¶
[apim.cache.jwt_claim]
enable = true
expiry_time = "15m"[apim.cache.jwt_claim]
Required
enable
string
TRUE
Enable JWT claim cache. The user's claims used to create the JWT are cached.
expiry_time
string
Not defined
Set the cache expiry time. Would be same as the JWT expiry time.
Cache tags¶
[apim.cache.tags]
expiry_time = "2m"
[apim.cache.tags]
Required
expiry_time
string
2m
Set when the tag cache expires. This option is disabled when not defined.
API-M Analytics configurations¶
[apim.analytics]
enable = false
store_api_url = "https://localhost:7444"
username = "$ref{super_admin.username}"
password = "$ref{super_admin.password}"
event_publisher_type = "custom"
event_publisher_impl = "org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageDataBridgeDataPublisher"
publish_response_size = true[apim.analytics]
Required
enable
string Required
FALSE
Set TRUE to enable analytics in API Manager
store_api_url
string Required
https://localhost:7444
The Store REST API URL for Analytics. If there are mutiple analytics node, use the loadbalancing URL
username
string Required
Credentials of the super admin user.
Credentials of the super admin user, in the analytics node
password
string Required
Credentials of the super admin user.
Credentials of the super admin user, in the analytics node
receiver_username
string
Uses the "apim.analytics.username"
Change this if a specific user is required for event publishing.
receiver_password
string
Uses the "apim.analytics.password"
Change this if a specific user is required for event publishing.
store_api_username
string
use apim.analytics.username
Change this if a specific user is required to access the Store REST API.
store_api_password
string
use apim.analytics.password
Change this if a specific user is required to access the Store REST API.
event_publisher_impl
string
If you have defined a custom "event_publisher_type", the custom publisher needs to be defined to the following value 'event_publisher_impl = "org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageDataBridgeDataPublisher"
publish_response_size
string
FALSE
Set TRUE to enable and define size of the publisher response sent to Analytics. Size is set bytes.
API-M Analytics - URL group configurations¶
#LOADBALANCER CONFIGS
[[apim.analytics.url_group]]
analytics_url =["tcp://analytics1:7611","tcp://analytics2:7611"]
analytics_auth_url =["ssl://analytics1:7711","ssl://analytics2:7711"]
type = "loadbalance"
#FAILOVER CONFIGS
[[apim.analytics.url_group]]
analytics_url =["tcp://analytics1:7612","tcp://analytics2:7612"]
analytics_auth_url =["ssl://analytics1:7712","ssl://analytics2:7712"]
type = "failover"[apim.analytics.url_group]
Required
string
Define each analytics node that the API Manager will connect to, as an array. If there are mutiple node, you need to define this configuration for each node.
analytics_url
string Required
tcp://localhost:7612
The list of server URLs e.g.,: analytics_url = ["tcp: //localhost:7611, tcp://localhost:7611"]"
analytics_auth_url
string Required
ssl://localhost:7712
The list of auth server URLs e.g.,: analytics_auth_url = ["ssl: //localhost:7711,ssl://localhost:7711"]
type
string
no default value
loadbalance failover
Loadbalance or Failover
API-M Key Manager related configurations¶
[apim.key_manager]
service_url = "https://localhost:${mgt.transport.https.port}/services/"
username = "$ref{super_admin.username}"
password = "$ref{super_admin.password}"
pool.init_idle_capacity = 50
pool.max_idle = 100
key_validation_handler_type = "custom"
key_validation_handler_impl = "org.wso2.carbon.apimgt.keymgt.handlers.DefaultKeyValidationHandler"[apim.key_manager]
Required
service_url
string Required
https://localhost:9443/services/
URL that offers services of the KM
username
string
Credentials of the super admin user.
Credentials of the super admin user, in the Key Manager node.
password
string
Credentials of the super admin user.
Credentials of the super admin user, in the Key Manager node.
pool.init_idle_capacity
string
50
Minimum no. of clients created, to connect to the key manager.
pool.max_idle
string
100
Maximum no. of clients created, to connect to the key manager.
key_validation_handler_type
string
default
default or custom
If custom, then provide the "key_validation_handler_impl" value
key_validation_handler_impl
string
You can provide a custom key validation handler implmentation. To do this, set the "key_validation_handler_type" to custom
[apim.http_client]
Required
Configuration related to the http client used for key validation calls made from gateway to key manager component. For the default JWT tokens (from APIM 3.2.0 onwards, the default token type is JWT), the key validation takes place within GW node itself, as the JWT token is self-contained. So no key validation call is made for JWT tokens. But if the token used is a reference token (if the deployment is migrated from older version which used reference tokens), the key validation http calls will be made to the Key manager component for token introspection. This dedicated http client is used for this purpose.
max_total
int Required
100
The maximum number of connections that will be created for the key validation calls. If there is a considerable latency, the connections in use at a given time will take a long time to be released and added back to the connection pool. As a result, connections may not be available for some requests. In such situations, it is recommended to increase the value for this parameter.
default_max_per_route
int Required
50
The maximum number of connections that will be created per host server by the client. Will have to increase this too, when required as similarly for the config max_total.
API-M AI configurations¶
[apim.ai]
enable = true
token = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
endpoint = "https://e95488c8-8511-4882-967f-ec3ae2a0f86f-prod.e1-us-east-azure.choreoapis.dev/lgpt/interceptor-service/interceptor-service-be2/v1.0"[apim.ai]
Required
Collection of AI feature related configs
enable
boolean Required
true
true,false
Enable the AI features.
token
string Required
The access token to authenticate AI feature related requests
endpoint
string
The endpoint that exposes the AI capabilities for API Manager
API-M OAuth configurations¶
[apim.oauth_config]
enable_outbound_auth_header = false
auth_header = "Authorization"
revoke_endpoint = "https://localhost:${mgt.transport.https.port}/oauth2/revoke"
enable_token_encryption = false
enable_token_hashing = false[apim.oauth_config]
Required
Collection of OAuth related configs
enable_outbound_auth_header
string
FALSE
If TRUE, sends Auth header to the backend as received from the client.
auth_header
string
Authorization
Any custom value
Valid authorization header for OAuth configurations.
revoke_endpoint
string
https://localhost:9443/oauth2/revoke
Valid URL for revocation endpoint.
Token revocation endpoint used in the API Developer Portal
enable_token_encryption
string
FALSE
If set to TRUE, the token stored in the database will be encrypted/decrypted when reading and storing. RSA/ECB/OAEPwithSHA1andMGF1PaddingIf FALSE - Setting Up OAuth Token Encryption | Extension Points for OAuth - IS Docs
enable_token_hashing
string
FALSE
Similar to prev. Get desc from IS docs
allowed_scopes
string
["^device_.*,openid"]
List of allowlisted scopes. Take desc from Key Concepts page.
API-M Mutual SSL Configuration¶
[apimgt.mutual_ssl]
certificate_header = "SSL-CLIENT-CERT"
enable_client_validation = false
client_certificate_encode = false
enable_certificate_chain_validation = false
[apimgt.mutual_ssl]
Required
Collection of Mutual SSL related configs
certificate_header
string
X-WSO2-CLIENT-CERTIFICATE
Specifies the header name for the client certificate.
enable_client_validation
boolean
false
true, false
This property needs to be true if the MutualSSL connection is established between the load balancer and the Gateway.
client_certificate_encode
boolean
false
true, false
This property needs to be true if the certificate should be decoded when it is passed from the load balancer to the Gateway.
enable_certificate_chain_validation
boolean
false
true, false
Specifies if certificate chain validation is enabled.
API Definitions Security Audit Configurations¶
[security_audit]
api_token="c21404ea-p13x-1swq-013a-pur90605uiwl"
collection_id="a5213vyo-6tre-560u-p04h-p0inb98i0gt1"
global=true
base_url="https://platform.42crunch.com/api/v1/apis"
[security_audit]
Required
Configures API definitions security audit settings.
api_token
string Required
Specifies the API token for security audit.
collection_id
string Required
Specifies the collection ID for security audit.
global
boolean
true
true, false
Specifies if security audit is globally enabled.
base_url
string
https://platform.42crunch.com/api/v1/apis
Specifies the base URL for the 42Crunch platform.
API-M Developer Portal configurations¶
[apim.devportal]
url = "https://localhost:${mgt.transport.https.port}/devportal"
enable_application_sharing = false
if application_sharing_type, application_sharing_impl both defined priority goes to application_sharing_impl
application_sharing_type = "default" changed type, saml, default todo: check the new config for rest api
application_sharing_impl = "org.wso2.carbon.apimgt.impl.SAMLGroupIDExtractorImpl"
display_multiple_versions = false
display_deprecated_apis = false
enable_comments = true
enable_ratings = true
enable_forum = true[apim.devportal]
Required
Configures the API Developer Portal
url
string Required
https://localhost:9443/devportal
Public API Developer Portal URL
enable_application_sharing
string
FALSE
Enable application sharing according to the claims.
application_sharing_type
string
If the config is not mentioned, then undefined.default
default, saml
Use the application_sharing_impl as default implmentationIf it is saml, the group extractor extracts the claims to group the applications from the saml response.
application_sharing_impl
string
Based on the application sharing type.
Need to define if the application_sharing_type is custom. If both application_sharing_type and application_sharing_impl is defined, take value from application_sharing_impl.
login_username_case_insensitive
string
TRUE
Check with new UI
display_multiple_versions
string
FALSE
If TRUE displays all the versions of the API under the API listing (and search depending on the new UI)
display_deprecated_apis
string
FALSE
If TRUE displays all the deprecated APIs under the API listing (and search depending on the new UI)
enable_comments
string
TRUE
Can comment on the API
enable_ratings
string
TRUE
Enable rating the API with a star-based rating
enable_forum
string
TRUE
^
application_sharing_claim
string
http://wso2.org/claims/organization
The user claim used to group the applications.
API-M CORS configurations¶
[apim.cors]
allow_origins = "*"
allow_methods = ["GET","PUT","POST","DELETE","PATCH","OPTIONS"]
allow_headers = ["authorization","Access-Control-Allow-Origin","Content-Type","SOAPAction"]
allow_credentials = false[apim.cors]
Required
Configures CORS headers on the Publisher and the Gateway.
enable
string
TRUE
CORS configurations are enabled by default.
allow_origins
string
*
Denotes "Access-Control-Allow-Origin" response header. Specify an origin to share the response with.
allow_methods
string
GET,PUT,POST,DELETE,PATCH,OPTIONS
Configures the methods allowed by the access control.
allow_headers
string
authorization,Access-Control-Allow-Origin,Content-Type,SOAPAction
Configures the type of headers allowed by the access control.
allow_credentials
string
FALSE
Specifying this header to true means that the server allows cookies (or other user credentials) to be included on cross-origin requests. It is false by default and if you set it to true then make sure that the Access-Control-Allow-Origin header does not contain the wildcard (*)
API-M Throttling configurations¶
[apim.throttling]
enable_data_publishing = true
enable_policy_deploy = true
enable_blacklist_condition = true
enable_persistence = true
enable_header_based_throttling = true
enable_jwt_claim_based_throttling = true
enable_query_param_based_throttling = true
enable_unlimited_tier = true
throttle_decision_endpoints = ["tcp://localhost:5672","tcp://localhost:5672"]
skip_redeploying_policies = ["carbon.super_app_unitApp","carbon.super_app_20PerMin"]
[apim.throttling]
Required
Configures API-M traffic control.
event_type
string
Binary
Thrift
Binary - Uses the binary transport. Recommended.Thrift - Uses thrift tranport
receiver_url
string
tcp://${carbon.local.ip}:${receiver.url.port}
Define traffic manager connection url inline. If none of this is defined consider it as "tcp://${carbon.local.ip}:${receiver.url.port}".
enable_header_based_throttling
string
false
Specifying this header to true will enable a user to define header condition throttling policies in the Admin Portal.
enable_unlimited_tier
string
true
Specifying this config to false will disable the unlimited throttling tier of basic throttling configurations.
enable_jwt_claim_based_throttling
string
false
Specifying this config to true will enable a user to define JWT claim based throttling policies in the Admin Portal.
enable_query_param_based_throttling
string
false
Specifying this config to true will enable a user to define Query parameter condition throttling policies in the Admin Portal.
skip_redeploying_policies
string
Define an array of throttle policies which don't need to redeploy on startup
enable_decision_connection
boolean
true
true, false
This will enable/disable the JMS Message retrieval connection based on the provided value(true/false).
jms.ssl
boolean
false
true, false
This will configure SSL in the JMS connection.
jms.start_delay
string
not defined
Connection delay to read the Traffic Manager at startup.
jms.conn_jndi_name
string
TopicConnectionFactory
custom value
The JNDI name of the connection factory.
jms.destination_type
string
topic
Type of the destination.
jms.java_naming_factory_initial
string
org.wso2.andes.jndi.PropertiesFileInitialContextFactory
Define JMS factory initials. If decision_connection_type is andes, this is "org.wso2.andes.jndi.PropertiesFileInitialContextFactory"
jms.topic_connection_factory
string
not defined
custom value
Type of the connection factory.
jms.username
string
super username
If the credentials of the user is different, use the credentials of the user configured for the JMS connection.
jms.password
string
super user password
If the credentials of the user is different, use the credentials of the user configured for the JMS connection.
enable_data_publishing
boolean
true
true, false
Enable publishing of request and throttling data.
enable_policy_deploy
boolean
true
true, false
Enable deploying of throttling policies.
enable_blacklist_condition
boolean
true
true, false
Enable blocking conditions from the admin portal.
enable_persistence
boolean
false
true, false
Enable persisting current counter state of the TM.
API-M Throttling URL group configs¶
[apim.throttling.blacklist_condition]
start_delay = "5m"
period = "1h"
[apim.throttling.jms]
start_delay = "5m"
[apim.throttling.event_sync]
hostName = "0.0.0.0"
port = 11224
[apim.throttling.event_management]
hostName = "0.0.0.0"
port = 10005
LOADBALANCE CONFIGS
[[apim.throttling.url_group]]
traffic_manager_urls = ["tcp://localhost:9611","tcp://localhost:9611"]
traffic_manager_auth_urls = ["ssl://localhost:9711","ssl://localhost:9711"]
type = "loadbalance"
FAILOVER CONFIGS
[[apim.throttling.url_group]]
traffic_manager_urls = ["tcp://localhost:9611","tcp://localhost:9611"]
traffic_manager_auth_urls = ["ssl://localhost:9711","ssl://localhost:9711"]
type = "failover"[apim.throttling.url_group]
Required
username
string
super username
Credentials of the Traffic Manager user.
password
string
super user password
Credentials of the Traffic Manager user.
receiver_username
string
super username
If the username of the receiver is different, use the username of the receiver configured on the Traffic Manager.
receiver_password
string
super user password
If the credentials of the receiver is different, use the password of the receiver configured on the Traffic Manager.
policy_deploy.username
string
super username
If the credentials of the user is different, use the credentials of the user configured for deploying policies.
policy_deploy.password
string
super user password
If the credentials of the user is different, use the credentials of the user configured for deploying policies.
jms.username
string
super username
If the credentials of the user is different, use the credentials of the user configured for the JMS connection.
jms.password
string
super user password
If the credentials of the user is different, use the credentials of the user configured for the JMS connection.
publisher.max_idle
string
1000
Ideal values for the maximum no. of connections to the data publisher pool.
publisher.init_idle_size
string
200
Ideal values for the minimum no. of connections to the data publisher pool.
publisher.pool_size
string
200
The size of the thread pool in the API Publisher.
publisher.max_pool_size
string
1000
The maximum size of the thread pool in the API Publisher.
publisher.keep_alive_time
string
200s
The timeframe after which the publisher thread pool is terminated.
service_url
string Required
https://localhost:${mgt.transport.https.port}${carbon.context}services/
Service URL of the Traffic Manager.
blacklist_condition.start_delay
string
not defined
Define the delay time to get the blacklist conditions from the Keymanager.
jms.destination
string
throttleData
JMS topic name
jms.start_delay
string
not define
Connection delay to read the Traffic Manager at startup.
jms.conn_jndi_name
string
TopicConnectionFactory
custom value
jms.destination_type
string
topic
decision_connection_type
string
andes
Define the JMS type e.g.,: andes
jms.java_naming_factory_initial
string
Define JMS factory initials. If decision_connection_type is andes, this is "org.wso2.andes.jndi.PropertiesFileInitialContextFactory"
throttle_decision_endpoints
string Required
Define array of JMS connection as an array.
API-M Throttling URL group¶
[apim.throttling.blacklist_condition]
start_delay = "5m"
period = "1h"
[apim.throttling.jms]
start_delay = "5m"
[apim.throttling.event_sync]
hostName = "0.0.0.0"
port = 11224
[apim.throttling.event_management]
hostName = "0.0.0.0"
port = 10005
LOADBALANCE CONFIGS
[[apim.throttling.url_group]]
traffic_manager_urls = ["tcp://localhost:9611","tcp://localhost:9611"]
traffic_manager_auth_urls = ["ssl://localhost:9711","ssl://localhost:9711"]
type = "loadbalance"
FAILOVER CONFIGS
[[apim.throttling.url_group]]
traffic_manager_urls = ["tcp://localhost:9611","tcp://localhost:9611"]
traffic_manager_auth_urls = ["ssl://localhost:9711","ssl://localhost:9711"]
type = "failover"[apim.throttling.url_group]
Required
traffic_manager_urls
string Required
TM binary server url
[[apim.throttling.url_group]]traffic_manager_urls = ["tcp://localhost:9611","tcp://localhost:9611"]traffic_manager_auth_urls = ["ssl://localhost:9711","ssl://localhost:9711"]type = "loadbalance"
traffic_manager_auth_urls
string Required
TM binary auth server url
type
string
failover
failover,loadbalance
API-M Workflow configurations¶
[apim.workflow]
enable = false
service_url = "https://localhost:9445/bpmn"
username = "$ref{super_admin.username}"
password = "$ref{super_admin.password}"
callback_endpoint = "https://localhost:${mgt.transport.https.port}/api/am/publisher/v0.15/workflows/update-workflow-status"
token_endpoint = "https://localhost:${https.nio.port}/token"
client_registration_endpoint = "https://localhost:${mgt.transport.https.port}/client-registration/v0.15/register"
client_registration_username = "$ref{super_admin.username}"
client_registration_password = "$ref{super_admin.password}"[apim.workflow]
Required
Configures the workflows in API Manager
enable
string
FALSE
Enable API State Change workflow.
service_url
string
https://localhost:9445/bpmn
The service URL of the workflow engine.
wf_engine_user
string
super username
Workflow username.
wf_engine_pass
string
super user password
Workflow password.
callback_endpoint
string
https://localhost:${mgt.transport.https.port}/api/am/publisher/v0.14/workflows/update-workflow-status
Callback URL for the workflow engine.
token_endpoint
string
https://localhost:${https.nio.port}/token
Token endpoint used for the workflow.
client_registration_endpoint
string
https://localhost:${mgt.transport.https.port}/client-registration/v0.14/register
DCR endpoint
client_registration_username
string
super username
DCR username
API-M SDK configurations¶
[apim.sdk]
group_id = "org.wso2"
artifact_id = "org.wso2.client"
model_package = "org.wso2.client.model"
api_package = "org.wso2.client.api"
supported_languages = ["android", "java", "csharp", "dart", "groovy", "javascript", "jmeter", "perl", "php", "python", "ruby", "swift5", "clojure"]
[apim.sdk]
Required
group_id
string
org.wso2
Group ID of the of the generated project.
artifact_id
string
org.wso2.client.
Artifact ID of the generated project.
model_package
string
org.wso2.client.model.
Model package of the generated project.
api_package
string
org.wso2.client.api.
API package of the generated project.
supported_languages
string
android, java, javascript, jmeter
android, java, csharp, dart, groovy, javascript, jmeter, perl, php, python, ruby, swift5, clojure
Supported programming languages.
API-M Open tracer configurations¶
[apim.open_tracer]
remote_tracer.enable = true
remote_tracer.name = "zipkin"
remote_tracer.properties.hostname = "localhost"
remote_tracer.properties.port = 9411
log_tracer.enable = true
[apim.open_tracer]
Required
Configurations related to tracing.
remote_tracer.enable
string
FALSE
Enable tracing in API Manager. Traces the execution time upto message level.
remote_tracer.name
string
zipkin
Tracer name.
remote_tracer.properties.hostname
string
localhost
Hostname of the zipkin tool (tracer)
remote_tracer.properties.port
string
9411
Port allocated for the tool.
log_tracer.enable
string
FALSE
Define whether to log the tracer values.
API-M token revocation¶
[apim.token.revocation]
notifier_impl = "org.wso2.carbon.apimgt.notification.TokenRevocationNotifierImpl"
enable_realtime_notifier = true
realtime_notifier.ttl = 5000
enable_persistent_notifier = true
persistent_notifier.hostname = "https://localhost:2379/v2/keys/jti/"
persistent_notifier.ttl = 5000
persistent_notifier.username = "root"
persistent_notifier.password = "root"[apim.token.revocation]
Required
Configures the token revocation on KM
notifier_impl
string
org.wso2.carbon.apimgt.notification.TokenRevocationNotifierImpl
This config is required only during a custom implementation. If a token is revoked, the notification will be sent to the JMS topic. Write a custom implementation to change this behaviour.
realtime_notifier.ttl
string
5000
persistent_notifier.hostname
string
https://localhost:2379/v2/keys/jti/
etcd hostname
persistent_notifier.ttl
string
5000
persistent_notifier.username
string
root
persistent_notifier.password
string
root
API-M Event Hub configurations¶
[apim.event_hub]
enabled = true
username = "username"
password = "password"
service_url = "https://control-plane-host/services/"
event_listening_endpoints = ["tcp://control-plane-host:5672"]
event_duplicate_url = ["tcp://control-plane-2-host:5672"]
[apim.event_hub]
Configures the event hub in API Manager
enable
boolean
true
true,false
Enable the event hub.
username
string
Username of the super tenant admin
Username of the super tenant admin.
password
string
Password of the super tenant admin
Password of the super tenant admin.
service_url
string
Internal service URL of the event hub. This configuration is used to pull artifacts from the control plane.
event_listening_endpoints
string array
Array of event listening endpoints which are used to create a JMS connection with the control plane.
event_duplicate_url
string array
Array of endpoints which is used in control plane to communicate with the other in a HA setup (If multiple URLs are added, other URLs will be taken as failover endpoints).
event_waiting_time
integer
The waiting time before the gateway/traffic manager waits before processing JMS events received from the event hub (in Milliseconds).
API-M Event Hub Publish URL group configurations¶
[[apim.event_hub.publish.url_group]]
urls = ["tcp://control-plane-1-host:9611"]
auth_urls = ["ssl://control-plane-1-host:9711"]
[[apim.event_hub.publish.url_group]]
urls = ["tcp://control-plane-2-host:9611"]
auth_urls = ["ssl://control-plane-2-host:9711"]
[apim.event_hub.publish.url_group]
Configures event hub publish URL groups
urls
string array Required
Array of URLs used to publish event streams to the control plane in a HA setup (If multiple URLs are added, other URLs will be taken as failover endpoints).
auth_urls
string array Required
Array of URLs used to create a secure connection for binary data streaming to the control plane in a HA setup (If multiple URLs are added, other URLs will be taken as failover endpoints).
Enable Notifications¶
[apim.notification]
from_address = "[email protected]"
username = "[email protected]"
password = "xxxxxx"
hostname = "smtp.gmail.com"
port = "587"
enable_start_tls = true
enable_authentication = true[apim.notifications]
from_address
string
The email address you use to send emails.
username
string
The email address used to authenticate the mail server. This can be the same email address as the from_address.
password
string
Password used to authenticate the mail server.
hostname
string
The SMTP server to connect to.
signature
string
Signature of the sender account.
port
string
25
The SMTP server port to connect to, if the connect() method does not explicitly specify one. Defaults to 25.
enable_start_tls
string
false
If true, enables the use of the `STARTTLS` command (if supported by the server, before issuing any login commands). Note that an appropriate trust store must be configured so that the client will trust the certificate of the server. Defaults to false.
enable_authentication
string
false
If true, it attempts to authenticate the user using the AUTH command. Defaults to false.
Tenant Management¶
[tenant_mgt]
enable_email_domain = true[tenant_mgt]
enable_email_domain
string
FALSE
Enable email login for tenant users.
Enable Password Recovery¶
[output_adapter.email]
from_address = "[email protected]"
username = "wso2amtest"
password = "Wso2@am70"
signature = "do not reply"
hostname = "smtp.gmail.com"
port = "587"
enable_start_tls = true
enable_authentication = true[output_adapter.email]
from_address
string
The email address you use to send emails.
username
string
The email address used to authenticate the mail server. This can be the same email address as the from_address.
password
string
Password used to authenticate the mail server.
hostname
string
The SMTP server to connect to.
signature
string
Signature of the sender account.
port
string
25
The SMTP server port to connect to, if the connect() method does not explicitly specify one. Defaults to 25.
enable_start_tls
string
false
If true, enables the use of the `STARTTLS` command (if supported by the server, before issuing any login commands). Note that an appropriate trust store must be configured so that the client will trust the certificate of the server. Defaults to false.
enable_authentication
string
false
If true, it attempts to authenticate the user using the AUTH command. Defaults to false.
Multi-tenancy Configurations¶
[multi_tenancy.stratos]
disable_tenant_management_emails = true
email_validation_mandatory_for_login = false
tenant_activation_moderated = false
super_admin_email = "super-admin-email"
skip_summary_generator = false
notification_email = "notification-email"
finance_notification_email = "finance-notification-email"
charge_on_registration = false
public_cloud_setup = true
google_analytics_url = "http://google-analytics.js"
sso_loading_message = "Loading..."[multi_tenancy.stratos]
Configures the multi-tenant Stratos properties.
disable_tenant_management_emails
boolean
TRUE
Disable tenant management emails for tenant users.
email_validation_mandatory_for_login
boolean
FALSE
Enable or disable mandatory email validation when logging in.
tenant_activation_moderated
boolean
FALSE
Enable or disable activation of moderated tenants.
super_admin_email
string
Email of the super admin user.
skip_summary_generator
boolean
FALSE
Skip summary generator for tenants.
notification_email
string
The email address that is used to send event related notifications.
finance_notification_email
string
The email address that is used to send financial information related notifications.
charge_on_registration
boolean
FALSE
The charge applicable for tenant registration.
public_cloud_setup
boolean
TRUE
Enable or disable public cloud setup for tenants.
google_analytics_url
string
URL address of Google Analytics.
sso_loading_message
string
The message that is displayed when SSO is loaded.
[multi_tenancy.stratos.paypal]
url = "Paypal URL"
username = "username"
password = "password"
signature = "signature"
environment = "live"[multi_tenancy.stratos.paypal]
url
string
The URL address of the attached PayPal account.
username
string
The username of the attached PayPal account.
password
string
The password of the attached PayPal account.
signature
string
TThe signature of the attached PayPal account.
environment
string
The environment of the attached PayPal account.
[multi_tenancy.stratos.manager_service]
url = "https://am.cloud.wso2.com/services/"
admin_username = "admin"
admin_password = "admin"[multi_tenancy.stratos.manager_service]
Configures the Stratos manager service.
url
string
The URL of the Stratos manager service.
admin_username
string
The admin username of the Stratos manager service.
admin_password
string
The admin password of the Stratos manager service.
[multi_tenancy.usage_agent.data_persistence_task]
startup_delay_in_ms = "60000"
records_per_execution = "100"
execution_interval_in_ms = "-1"[multi_tenancy.usage_agent.data_persistence_task]
Configures the data presistance for user agents in multi-tenant mode.
startup_delay_in_ms
string
Connection delay to start data presistance at startup.
records_per_execution
string
Number of records to be persisted per execution.
execution_interval_in_ms
string
-1
Time between execution cycles in miliseconds.
Multi-tenancy throttling manager configurations¶
[multi_tenancy.throttling_manager_tasks]
data_providers = [
"org.wso2.carbon.throttling.manager.dataproviders.BillingDataProvider",
"org.wso2.carbon.throttling.manager.dataproviders.UsageDataProvider"
][multi_tenancy.throttling_manager_tasks]
Configures the multi-tenant throttling manager tasks.
data_providers
string array
Data providers for throttling management tasks.
[multi_tenancy.throttling_manager_tasks.parameters]
interval = "10"
delay = "60"[multi_tenancy.throttling_manager_tasks.parameters]
Configures the parameters of multi-tenant throttling manager tasks.
interval
string
Time interval betweeen throttling manager tasks.
delay
string
Time delay to start throttling manager tasks.
Multi-tenancy cloud services configurations¶
[multi_tenancy.cloud_services]
name = "WSO2 API Manager"
default = true
key = "AM"
label = "API Manager"
link = "https://am.cloud.wso2.com"
description = "API Manager in the cloud"[multi_tenancy.cloud_services]
Configures the multi tenant cloud services.
name
string
Name of the cloud service.
default
boolean
TRUE
Use as the default cloud service or not.
key
string
Key-value that represents the cloud service.
label
string
Label value that represents the cloud service.
link
string
URL link to the cloud service.
description
string
Description of the cloud service.
Multi-tenancy monetization configurations¶
[multi_tenancy.billing.package.demo]
name = "Demo"
subscription_charge = 0[multi_tenancy.billing.package.demo]
This includes multi-tenancy monetization configurations related to the "Demo" package.
name
string
Demo
Provides the name of the billing package that is being used.
subscription_charge
int
0
The value of the subscription charge for the billing package.
[multi_tenancy.billing.package.demo.users]
limit= "1"
charge= "0"[multi_tenancy.billing.package.demo.users]
This includes the users' configurations related to the "Demo" billing package.
limit
string
1
Provides the number of users that can be attached to the "Demo" billing package.
charge
string
0
The value of the subscription charge for the "Demo" billing package per user.
[multi_tenancy.billing.package.demo.resource_volume]
limit= "20"
overuse_charge= "0"[multi_tenancy.billing.package.demo.resource_volume]
This includes the resource volume configurations related to the "Demo" billing package.
limit
string
The maximum number of resources that can be charged with the given billing package.
overuse_charge
string
0
The charge for over usage based on the billing package.
[multi_tenancy.billing.package.demo.bandwidth]
limit= "50"
overuse_charge= "0"[multi_tenancy.billing.package.demo.bandwidth]
This includes the bandwidth configurations related to the "Demo" billing package.
limit
string
The highest bandwidth value that can be allocated for the "Demo" billing package.
overuse_charge
string
0
The charge for over usage based on the billing package.
[multi_tenancy.billing.package.smb]
name = "SMB"
subscription_charge = "100"[multi_tenancy.billing.package.smb]
This includes multi-tenancy monetization configurations related to the "SMB" package.
name
string
SMB
Provides the name of the billing package that is being used.
subscription_charge
int
0
The value of the subscription charge for the billing package.
[multi_tenancy.billing.package.smb.users]
limit= "unlimited"
charge= "0"[multi_tenancy.billing.package.smb.users]
This includes the users' configurations related to the "SMB" billing package.
limit
string
1
Provides the number of users that can be attached to the "SMB" billing package.
charge
string
0
Value of the subscription charge for the "SMB" billing package per user.
[multi_tenancy.billing.package.smb.resource_volume]
limit= "50"
overuse_charge= "0"[multi_tenancy.billing.package.smb.resource_volume]
This includes the resource volume configurations related to the "SMB" billing package.
limit
string
The maximum number of resources that can be charged with the given billing package.
overuse_charge
string
0
The charge for over usage based on the billing package.
[multi_tenancy.billing.package.smb.bandwidth]
limit= "150"
overuse_charge= "0"[multi_tenancy.billing.package.smb.bandwidth]
This includes the bandwidth configurations related to the "SMB" billing package.
limit
string
The highest bandwidth value that can be allocated for the "SMB" billing package.
overuse_charge
string
0
The charge for over usage based on the billing package.
[multi_tenancy.billing.package.custom]
name = "Professional"
subscription_charge = "500"[multi_tenancy.billing.package.custom]
This includes multi-tenancy monetization configurations related to the custom package.
name
string
SMB
The name of the custom billing package.
subscription_charge
int
0
The value of the subscription charge for the billing package.
[multi_tenancy.billing.package.custom.users]
limit= "unlimited"
charge= "0"[multi_tenancy.billing.package.custom.users]
This includes the users' configurations related to the custom billing package.
limit
string
1
Provides the number of users that can be attached to the custom billing package.
charge
string
0
Value of the subscription charge for the custom billing package per user.
[multi_tenancy.billing.package.custom.resource_volume]
limit = "1536"
overuse_charge = "0.03"[multi_tenancy.billing.package.custom.resource_volume]
This includes the resource volume configurations related to the custom billing package.
limit
string
The maximum number of resources that can be charged with the given billing package.
overuse_charge
string
0
The charge for over usage based on the billing package.
[multi_tenancy.billing.package.custom.bandwidth]
limit= "50"
overuse_charge= "0"[multi_tenancy.billing.package.custom.bandwidth]
This includes the bandwidth configurations related to the custom billing package.
limit
string
The highest bandwidth value that can be allocated for the custom billing package.
overuse_charge
string
0
The charge for over usage based on the billing package.
Registry indexing configurations¶
[indexing]
enable = true
starting_delay = 35
frequency = 3
bach_size = 40
pool_size = 40
re_indexing = 1[indexing]
Index configurations related to metadata search in registry.
enable
boolean
true
true,false
Enable registry indexing, which indexes the APIs in the registry. Required only to be true on the API Publisher and Developer Portal nodes. WSO2 recommends disabling this on other nodes (Gateways, Traffic Managers, and Key Managers).
starting_delay
string
35
Initial startup delay for indexing (when the server is starting) in seconds.
frequency
string
3
Indexing frequency in seconds.
bach_size
string
40
Number of resources submitted for given indexing thread.
pool_size
string
40
Number of worker threads for indexing.
re_indexing
string
Not defined
Provide a number starting from 1. Increase the value by one during each time you need to reindex. Make sure to backup and delete the <API-M_HOME>/solr directory after changing the configuration and before restarting the server. After a server restart, reindexing might take a considerable amount of time depending on the number of APIs you have in the registry.
HTTP Servlet Transport¶
[transport.http.properties]
port = "9763"
redirectPort = "9443"
bindOnInit = "false"
maxHttpHeaderSize = "8192"
acceptorThreadCount = "2"
maxThreads = "250"
minSpareThreads = "50"
disableUploadTimeout = "false"
connectionUploadTimeout = "120000"
maxKeepAliveRequests = "200"
acceptCount = "200"
server = "WSO2 Carbon Server"
compression = "on"
compressionMinSize = "2048"
noCompressionUserAgents = "gozilla, traviata"
compressibleMimeType = "text/html,text/javascript,application/x-javascript,application/javascript,application/xml,text/css,application/xslt+xml,text/xsl,image/gif,image/jpg,image/jpeg"
URIEncoding = "UTF-8"[transport.http.properties]
This configuration header is required for configuring the parameters that are used for tuning the default HTTP catalina server transport of the API Manager.
port
integer Required
9443
-
bindOnInit
boolean Required
false
"true" or "false"
maxHttpHeaderSize
integer Required
8192
-
acceptorThreadCount
integer Required
2
-
maxThreads
integer Required
250
-
minSpareThreads
integer Required
50
-
disableUploadTimeout
boolean Required
false
"true" or "false"
connectionUploadTimeout
integer Required
120000
-
maxKeepAliveRequests
integer Required
120000
-
keepAliveTimeout
integer Required
60000
3000
acceptCount
integer Required
200
-
server
string Required
WSO2 Carbon Server
-
compression
string Required
on
-
compressionMinSize
integer Required
2048
-
noCompressionUserAgents
string Required
gozilla, traviata
-
compressibleMimeType
string Required
text/html,text/javascript,application/x-javascript,application/javascript,application/xml,text/css,application/xslt+xml,text/xsl,image/gif,image/jpg,image/jpeg
-
URIEncoding
string Required
UTF-8
-
HTTPS Servlet Transport¶
[transport.https.properties]
port = "9763"
redirectPort = "9443"
bindOnInit = "false"
maxHttpHeaderSize = "8192"
acceptorThreadCount = "2"
maxThreads = "250"
minSpareThreads = "50"
disableUploadTimeout = "false"
connectionUploadTimeout = "120000"
maxKeepAliveRequests = "200"
acceptCount = "200"
server = "WSO2 Carbon Server"
compression = "on"
compressionMinSize = "2048"
noCompressionUserAgents = "gozilla, traviata"
compressibleMimeType = "text/html,text/javascript,application/x-javascript,application/javascript,application/xml,text/css,application/xslt+xml,text/xsl,image/gif,image/jpg,image/jpeg"
URIEncoding = "UTF-8"
enableLookups = "false"
scheme = "https"
secure = "true"
SSLEnabled = "true"[transport.https.properties]
This configuration header is required for configuring the parameters that are used for tuning the default HTTPS catalina server transport of the API Manager.
port
integer Required
9443
-
bindOnInit
boolean Required
false
"true" or "false"
maxHttpHeaderSize
integer Required
8192
-
acceptorThreadCount
integer Required
2
-
maxThreads
integer Required
250
-
minSpareThreads
integer Required
50
-
disableUploadTimeout
boolean Required
false
"true" or "false"
connectionUploadTimeout
integer Required
120000
-
maxKeepAliveRequests
integer Required
120000
-
keepAliveTimeout
integer Required
60000
3000
acceptCount
integer Required
200
-
server
string Required
WSO2 Carbon Server
-
compression
string Required
on
-
compressionMinSize
integer Required
2048
-
noCompressionUserAgents
string Required
gozilla, traviata
-
compressibleMimeType
string Required
text/html,text/javascript,application/x-javascript,application/javascript,application/xml,text/css,application/xslt+xml,text/xsl,image/gif,image/jpg,image/jpeg
-
URIEncoding
string Required
UTF-8
-
enableLookups
boolean Required
false
"true" or "false"
scheme
string Required
https
-
secure
boolean Required
true
"true" or "false"
SSLEnabled
boolean Required
true
"true" or "false"
HTTP/S Pass-through Transport (non-blocking mode)¶
[transport.passthru_https]
http.socket.timeout = "3m"
worker_pool_size_core = 300
worker_pool_size_max = 400
worker_pool_queue_length = -1
io_buffer_size = 16384
http.max.connection.per.host.port = 32767
http.user.agent.preserve = false
preserve_http_server_name = true
http.headers.preserve = ["Content-Type"]
disable_connection_keepalive = false
max_open_connections = -1
force_xml_validation = false
force_json_validation = false
listener.parameters.port = 8243 #inferred default: 8280
listener.parameters.WSDLEPRPrefix ="$ref{server.hostname}"
listener.parameters.bind-address = "$ref{server.hostname}"
listener.protocols = "TLSv1,TLSv1.1,TLSv1.2"
listener.parameters.SSLVerifyClient = "require"
listener.ssl_profile.file_path = "repository/resources/security/listenerprofiles.xml"
listener.ssl_profile_interval = "600000"
listener.preferred_ciphers = "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256"
listener.key_store.file_name ="$ref{keystore.tls.file_name}"
listener.key_store.type = "$ref{keystore.tls.type}"
listener.key_store.password = "$ref{keystore.tls.password}"
listener.key_store.key_password = "$ref{keystore.tls.key_password}"
listener.trust_store.file_name = "$ref{truststore.file_name}"
listener.trust_store.type = "$ref{truststore.type}"
listener.trust_store.password = "$ref{truststore.password}"
sender.warnOnHTTP500 = "*"
sender.http.proxyHost = "$ref{server.hostname}"
sender.http.proxyPort = 3128
sender.http.nonProxyHosts = ["$ref{server.hostname}"]
sender.hostname_verifier = "AllowAll"
sender.key_store.file_name ="$ref{keystore.tls.file_name}"
sender.key_store.type = "$ref{keystore.tls.type}"
sender.key_store.password = "$ref{keystore.tls.password}"
sender.key_store.key_password = "$ref{keystore.tls.key_password}"
sender.trust_store.file_name = "$ref{truststore.file_name}"
sender.trust_store.type = "$ref{truststore.type}"
sender.trust_store.password = "$ref{truststore.password}"
sender.ssl_profile.file_path = "repository/resources/security/sslprofiles.xml"
sender.ssl_profile.interval = "600000"[transport.passthru_http]
This configuration header is required for configuring the parameters that are used for tuning the default HTTP/S passthrough transport of the API Manager in non-blocking mode.
http.socket.timeout
integer Required
180000
-
This is the maximum period of inactivity between two consecutive data packets, specified in milliseconds.
worker_pool_size_core
integer Required
400
-
The API Manager uses a thread pool executor to create threads and to handle incoming requests. This parameter controls the number of core threads used by the executor pool. If you increase this parameter value, the number of requests received that can be processed by the gateway increases, hence, the throughput also increases. The nature of the integration scenario and the number of concurrent requests received by the gateway are the main factors that helps to determine this parameter.
worker_pool_size_max
integer Required
400
-
This is the maximum number of threads in the worker thread pool. Specifying a maximum limit avoids performance degradation that can occur due to context switching. If the specified value is reached, you will see the error 'SYSTEM ALERT - HttpServerWorker threads were in BLOCKED state during last minute'. This can occur due to an extraordinarily high number of requests sent at a time when all the threads in the pool are busy, and the maximum number of threads is already reached.
worker_pool_queue_length
integer Required
-1
-
This defines the length of the queue that is used to hold runnable tasks to be executed by the worker pool. The thread pool starts queuing jobs when all the existing threads are busy, and the pool has reached the maximum number of threads. The value for this parameter should be -1 to use an unbound queue. If a bound queue is used and the queue gets filled to its capacity, any further attempts to submit jobs fail causing some messages to be dropped by Synapse.
io_buffer_size
integer Required
16384
-
This is the value of the memory buffer allocated when reading data into the memory from the underlying socket/file channels. You should leave this property set to the default value.
http.max.connection.per.host.port
integer Required
32767
-
This defines the maximum number of connections allowed per host port.
http.user.agent.preserve
boolean Required
"true" or "false"
-
If this parameter is set to true, the user-agent HTTP header of messages passing through the integrator is preserved and printed in the outgoing message.
http.headers.preserve
string Required
Content-Type
-
This parameter allows you to specify the header field/s of messages passing through the EI that need to be preserved and printed in the outgoing message such as Location, CommonsHTTPTransportSenderKeep-Alive, Date, Server, User-Agent, and Host. For example, http.headers.preserve = Location, Date, Server.
disable_connection_keepalive
boolean Required
false
"true" or "false"
If this parameter is set to true, the HTTP connections with the back end service are closed soon after the request is served. It is recommended to set this property to false so that the integrator does not have to create a new connection every time it sends a request to a back-end service. However, you may need to close connections after they are used if the back-end service does not provide sufficient support for keep-alive connections.
listener.parameters.port
integer Required
8290
-
The port on which this transport receiver should listen for incoming messages.
listener.parameters.WSDLEPRPrefix
string Required
-
-
A URL prefix which will be added to all service EPRs and EPRs in WSDLs etc.
listener.parameters.port
integer Required
8253
-
The secured port on which this transport receiver should listen for incoming messages.
listener.key_store.file_name
string Required
API-M_HOME/repository/resources/security/wso2carbon.jks
-
The path to the keystore file that is used for securing the HTTP passthrough connection. By default, the keystore file of the primary keystore is enabled for this purpose.
listener.key_store.type
string Required
JKS
"JKS" or "PKCS12"
The type of the keystore file. By default, the keystore type of the primary keystore is enabled for this purpose.
listener.key_store.password
string Required
wso2carbon
-
The password of the keystore file that is used for securing the HTTP passthrough connection. This keystore password is used when accessing the keys in the keystore. By default, the keystore password of the primary keystore is enabled for this purpose.
listener.key_store.key_password
string Required
wso2carbon
-
The password of the private key that is used for securing the HTTP passthrough connection. This keystore password is used when accessing the keys in the keystore. By default, the keystore password of the primary keystore is enabled for this purpose.
listener.trust_store.file_name
string Required
API-M_HOME/repository/resources/security/wso2truststore.jks
-
The path to the keystore file that is used for storing the trusted digital certificates. By default, the product's trust store is configured for this purpose.
listener.trust_store.type
string Required
JKS
"JKS" or "PKCS12"
The type of the keystore file that is used as the trust store. By default, the product's trust store is configured for this purpose.
listener.trust_store.password
string Required
wso2carbon
-
The password of the keystore file that is used as the trust store. By default, the product's trust store is configured for this purpose.
sender.warnOnHTTP500
string Required
-
-
If the outgoing messages should be sent through an HTTP proxy server, use this parameter to specify the target proxy.
sender.http.proxyHost
string
-
-
If the outgoing messages should be sent through an HTTP proxy server, use this parameter to specify the target proxy.
sender.http.proxyPort
integer
-
-
The port through which the target proxy (specified by the 'sender.proxy_port' parameter) accepts HTTP traffic.
sender.http.nonProxyHosts
string Required
-
-
The list of hosts to which the HTTP traffic should be sent directly without going through the proxy. When trying to add multiple hostnames along with an asterisk in order to define a set of sub-domains for non-proxy hosts, you need to add a period before the asterisk when configuring proxy server.
sender.hostname_verifier
string Required
-
-
The list of hosts to which the HTTP traffic should be sent directly without going through the proxy. When trying to add multiple hostnames along with an asterisk in order to define a set of sub-domains for non-proxy hosts, you need to add a period before the asterisk when configuring proxy server.
sender.key_store.file_name
string Required
API-M_HOME/repository/resources/security/wso2carbon.jks
-
The path to the keystore file that is used for securing the HTTP passthrough connection. By default, the keystore file of the primary keystore is enabled for this purpose.
sender.key_store.type
string Required
JKS
"JKS" or "PKCS12"
The type of the keystore file. By default, the keystore type of the primary keystore is enabled for this purpose.
sender.key_store.password
string Required
wso2carbon
-
The password of the keystore file that is used for securing the HTTP passthrough connection. This keystore password is used when accessing the keys in the keystore. By default, the keystore password of the primary keystore is enabled for this purpose.
sender.key_store.key_password
string Required
wso2carbon
-
The password of the private key that is used for securing the HTTP passthrough connection. This keystore password is used when accessing the keys in the keystore. By default, the keystore password of the primary keystore is enabled for this purpose.
sender.trust_store.file_name
string Required
API-M_HOME/repository/resources/security/wso2truststore.jks
-
The path to the keystore file that is used for storing the trusted digital certificates. By default, the product's trust store is configured for this purpose.
sender.trust_store.type
string Required
JKS
"JKS" or "PKCS12"
The type of the keystore file that is used as the trust store. By default, the product's trust store is configured for this purpose.
sender.trust_store.password
string Required
wso2carbon
-
The password of the keystore file that is used as the trust store. By default, the product's trust store is configured for this purpose.
HTTP/S Pass-through Transport (blocking mode)¶
[transport.passthru_https]
listener.enable = true
listener.parameters.port = 8200
listener.hostname = ""
listener.origin_server = ""
listener.request_timeout = ""
listener.request_tcp_no_delay = ""
listener.request_core_thread_pool_size = ""
listener.request_max_thread_pool_size = ""
listener.thread_keepalive_time = ""
listener.thread_keepalive_time_unit = ""
[transport.blocking_https]
sender.enable = true
sender.parameters.cacheHttpClient = true
sender.parameters.Transfer-Encoding = ""
sender.parameters.defaultMaxConnectionsPerHost = 200
sender.parameters.OmitSOAP12Action = true
sender.parameters.SO_TIMEOUT = 60000[transport.passthru_https]
This configuration header is required for configuring the parameters that are used for configuring the default HTTP/S passthrough transport in blocking mode
listener.enable
boolean Required
true
"true" or "false"
This parameter is used for enabling the HTTP passthrough transport listener in blocking mode.
listener.parameters.port
integer Required
8200
-
The port on which this transport receiver should listen for incoming messages.
listener.hostname
string
-
listener.origin_server
string
-
listener.request_timeout
string
-
listener.request_tcp_no_delay
string
-
listener.request_core_thread_pool_size
string
-
listener.request_max_thread_pool_size
string
-
listener.thread_keepalive_time
string
-
listener.thread_keepalive_time_unit
string
-
sender.enable
boolean Required
true
"true" or "false"
This parameter is used for enabling the HTTP passthrough transport sender in blocking mode.
sender.parameters.cacheHttpClient
boolean Required
-
"true" or "false"
This parameter is used to specify whether the HTTP client should save cache entries and the cached responses in the JVM memory or not.
sender.parameters.Transfer-Encoding
string Required
-
"chunked" or "true"
This parameter enables you to specify whether the data sent should be chunked. It can be used instead of the Content-Length header if you want to upload data without having to know the amount of data to be uploaded in advance.
sender.parameters.defaultMaxConnectionsPerHost
integer Required
-
-
The maximum number of connections that will be created per host server by the client. If the backend server is slow, the connections in use at a given time will take a long time to be released and added back to the connection pool. As a result, connections may not be available for some requests. In such situations, it is recommended to increase the value for this parameter.
sender.parameters.OmitSOAP12Action
boolean Required
-
"true" or "false"
If following is set to 'true', optional action part of the Content-Type will not be added to the SOAP 1.2 messages.
sender.parameters.SO_TIMEOUT
integer Required
-
60000
If following is set to 'true', optional action part of the Content-Type will not be added to the SOAP 1.2 messages.
sender.http.proxyHost
string
-
-
If the outgoing messages should be sent through an HTTP proxy server (in blocking mode), use this parameter to specify the target proxy.
sender.http.proxyPort
integer
-
-
The port through which the target proxy (specified by the 'sender.proxy_host' parameter) accepts HTTP traffic (in blocking mode).
sender.http.proxyHost
string
-
-
If the outgoing messages should be sent through an HTTPS proxy server (in blocking mode), use this parameter to specify the target proxy.
sender.http.proxyPort
integer
-
-
The port through which the target proxy (specified by the 'sender.secured_proxy_host' parameter) accepts HTTPS traffic (in blocking mode).
HTTP proxy profile¶
#You can use one of the two options listed below for the configuration
#Option 1
[transport.passthru_http.sender.parameters]
proxyProfiles = "<targetHosts>example.one.com,example.two.com</targetHosts>
<proxyHost>example.proxy.com</proxyHost>
<proxyPort>8080</proxyPort>
<proxyUserName>ProxyUser</proxyUserName>
<proxyPassword>password</proxyPassword></profile>"
#Option 2
[[transport.http.proxy_profile]]
target_hosts = ["example.one.com","example.two.com"]
proxy_host = "example.proxy.com"
proxy_port = "8080"
proxy_username = "ProxyUser"
proxy_password = "password"
bypass_hosts = ["localhost"][[transport.passthru_http.sender.parameters]]
This configuration header is required for configuring HTTP proxy profiles when you need multiple proxy servers to route messages to different endpoints.
proxyProfiles
string Required
-
<profile><targetHosts>example.com</targetHosts><proxyHost>localhost</proxyHost><proxyPort>8080</proxyPort><proxyUserName>squidUser</proxyUserName><proxyPassword>password</proxyPassword></profile>
Attribute to define a full proxy profile. Following fields describes the elements used inside the profile
targetHosts
string Required
-
"*", "example.com", "<any-ip-address>"
A host name or a comma-separated list of host names for a target endpoint. Host names can be specified as regular expressions that match a pattern. When asterisks (*) is specified as the target hostname, it will match all the hosts in the profile.
proxyHost
string Required
-
-
The host name of the proxy server.
proxyPort
integer Required
-
-
The port number of the proxy server.
proxyUserName
string Required
-
-
The username for authenticating the proxy server.
proxyPassword
string Required
-
-
The password for authenticating the proxy server.
HTTP secured proxy profile¶
#You can use one of the two options listed below for the configuration
#Option 1
[transport. passthru_https.sender.parameters]
proxyProfiles = "<targetHosts>example.one.com,example.two.com</targetHosts>
<proxyHost>example.proxy.com</proxyHost>
<proxyPort>3128</proxyPort>
<proxyUserName>ProxyUser</proxyUserName>
<proxyPassword>password</proxyPassword></profile>"
#Option 2
[[transport.http. secured_proxy_profile]]
target_hosts = ["example.one.com","example.two.com"]
proxy_host = "example.proxy.com"
proxy_port = "3128"
proxy_username = "ProxyUser"
proxy_password = "password"
bypass_hosts = ["localhost"]
[[transport.passthru_https.sender.parameters]]
This configuration header is required for configuring HTTP proxy profiles when you need multiple proxy servers to route messages to different endpoints.
proxyProfiles
string Required
-
<profile><targetHosts>example.com</targetHosts><proxyHost>localhost</proxyHost><proxyPort>8080</proxyPort><proxyUserName>squidUser</proxyUserName><proxyPassword>password</proxyPassword></profile>
Attribute to define a full proxy profile. Following fields describes the elements used inside the profile
targetHosts
string Required
-
"*", "example.com", "<any-ip-address>"
A host name or a comma-separated list of host names for a target endpoint. Host names can be specified as regular expressions that match a pattern. When asterisks (*) is specified as the target hostname, it will match all the hosts in the profile.
proxyHost
string Required
-
-
The host name of the proxy server.
proxyPort
integer Required
-
-
The port number of the proxy server.
proxyUserName
string Required
-
-
The username for authenticating the proxy server.
proxyPassword
string Required
-
-
The password for authenticating the proxy server.
Websocket Transport¶
[transport.ws]
sender.enable = false
sender.parameters.ws.outflow.dispatch.sequence = "outflowDispatchSeq"
sender.parameters.ws.outflow.dispatch.fault.sequence = "outflowFaultSeq"
sender.parameter.customParameter = ""[transport.ws]
This configuration header groups the parameters that configure the API Manager to communicate through the Websocket transport.
sender.enable
boolean Required
false
"true" or "false"
The parameter for enabling the websocket transport listener.
sender.parameters.ws.outflow.dispatch.sequence
string
outflowDispatchSeq
-
The sequence for the back-end to client mediation.
sender.parameters.ws.outflow.dispatch.fault.sequence
string
outflowFaultSeq
-
The fault sequence for the back-end to client mediation path.
sender.parameter.customParameter
string
-
-
Replace 'customParameter' with required parameter name.
Secure Websocket Transport¶
[transport.wss]
sender.enable = false
sender.parameters.ws.outflow.dispatch.sequence = "outflowDispatchSeq"
sender.parameters.ws.outflow.dispatch.fault.sequence = "outflowFaultSeq"
sender.parameter.customParameter = ""
sender.trust_store.location = "$ref{truststore.file_name}"
sender.trust_store.password = "$ref{truststore.password}"[transport.wss]
This configuration header groups the parameters that configure the API Manager to communicate through the secured Websocket transport.
sender.enable
boolean Required
false
"true" or "false"
The parameter for enabling the websocket secured transport sender.
sender.parameters.ws.outflow.dispatch.sequence
string
outflowDispatchSeq
-
The sequence for the back-end to client mediation.
sender.parameters.ws.outflow.dispatch.fault.sequence
string
outflowFaultSeq
-
The fault sequence for the back-end to client mediation path.
sender.trust_store.location
string Required
API-M_HOME/repository/resources/security/wso2truststore.jks
-
The file path to the truststore that stores the trusted digital certificates for websocket use cases. By default, the product's trust store is configured for this purpose.
sender.trust_store.password
string Required
wso2carbon
-
The password of the keystore file that is used as the trust store.
sender.parameter.customParameter
string
-
-
Replace 'customParameter' with required parameter name.
Message Builders (non-blocking mode)¶
[message_builders]
application_xml = "org.apache.axis2.builder.ApplicationXMLBuilder"
form_urlencoded = "org.apache.synapse.commons.builders.XFormURLEncodedBuilder"
multipart_form_data = "org.apache.axis2.builder.MultipartFormDataBuilder"
text_plain = "org.apache.axis2.format.PlainTextBuilder"
application_json = "org.wso2.micro.integrator.core.json.JsonStreamBuilder"
json_badgerfish = "org.apache.axis2.json.JSONBadgerfishOMBuilder"
text_javascript = "org.apache.axis2.json.JSONBuilder"
octet_stream = "org.wso2.carbon.relay.BinaryRelayBuilder"
application_binary = "org.apache.axis2.format.BinaryBuilder"[message_builders]
This configuration header is required for configuring the implementation that is used to build messages that are received by the API Manager in the default non-blocking mode.
application_xml
string
org.apache.axis2.builder.ApplicationXMLBuilder
-
The message builder implementation that builds messages with the 'application_xml' content type. If required, you can change the default builder class.
form_urlencoded
string
-
org.apache.synapse.commons.builders.XFormURLEncodedBuilder
The message builder implementation that builds messages with the 'form_urlencoded' content type. If required, you can change the default builder class.
multipart_form_data
string
org.apache.axis2.builder.MultipartFormDataBuilder
-
The message builder implementation that builds messages with the 'multipart_form_data' content type. If required, you can change the default builder class.
text_plain
string
org.apache.axis2.format.PlainTextBuilder
-
The message builder implementation that builds messages with the 'text_plain' content type. If required, you can change the default builder class.
application_json
string
org.wso2.micro.integrator.core.json.JsonStreamBuilder
-
The message builder implementation that builds messages with the 'application_json' content type. If required, you can change the default builder class.
json_badgerfish
string
org.apache.axis2.json.JSONBadgerfishOMBuilder
-
The message builder implementation that builds messages with the 'json_badgerfish' content type. If required, you can change the default builder class.
text_javascript
string
org.apache.axis2.json.JSONBuilder
-
The message builder implementation that builds messages with the 'text_javascript' content type. If required, you can change the default builder class.
octet_stream
string
org.wso2.carbon.relay.BinaryRelayBuilder
-
The message builder implementation that builds messages with the 'octet_stream' content type. If required, you can change the default builder class.
application_binary
string
org.apache.axis2.format.BinaryBuilder
-
The message builder implementation that builds messages with the 'application_binary' content type. If required, you can change the default builder class.
Message Builders (blocking mode)¶
[blocking.message_builders]
application_xml = "org.apache.axis2.builder.ApplicationXMLBuilder"
form_urlencoded = "org.apache.synapse.commons.builders.XFormURLEncodedBuilder"
multipart_form_data = "org.apache.axis2.builder.MultipartFormDataBuilder"
text_plain = "org.apache.axis2.format.PlainTextBuilder"
application_json = "org.wso2.micro.integrator.core.json.JsonStreamBuilder"
json_badgerfish = "org.apache.axis2.json.JSONBadgerfishOMBuilder"
text_javascript = "org.apache.axis2.json.JSONBuilder"
octet_stream = "org.wso2.carbon.relay.BinaryRelayBuilder"
application_binary = "org.apache.axis2.format.BinaryBuilder"[blocking.message_builders]
This configuration header is required for configuring the message builder implementation that is used to build messages that are received by the API Manager in blocking mode. You can use the same list of parameters that are available for message builders in non-blocking mode.
Message Formatters (non-blocking mode)¶
[message_formatters]
form_urlencoded = "org.apache.synapse.commons.formatters.XFormURLEncodedFormatter"
multipart_form_data = "org.apache.axis2.transport.http.MultipartFormDataFormatter"
application_xml = "org.apache.axis2.transport.http.ApplicationXMLFormatter"
text_xml = "org.apache.axis2.transport.http.SOAPMessageFormatter"
soap_xml = "org.apache.axis2.transport.http.SOAPMessageFormatter"
text_plain = "org.apache.axis2.format.PlainTextFormatter"
application_json = "org.wso2.micro.integrator.core.json.JsonStreamFormatter"
json_badgerfish = "org.apache.axis2.json.JSONBadgerfishMessageFormatter"
text_javascript = "org.apache.axis2.json.JSONMessageFormatter"
octet_stream = "org.wso2.carbon.relay.ExpandingMessageFormatter"
application_binary = "org.apache.axis2.format.BinaryFormatter"[message_formatters]
This configuration header is required for configuring the message formatting implementation that is used for formatting messages that are sent out of the API Manager in non-blocking mode.
application_xml
string
org.apache.axis2.transport.http.ApplicationXMLFormatter
-
The message formating implementation that formats messages with the 'application_xml' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
form_urlencoded
string
-
org.apache.synapse.commons.formatters.XFormURLEncodedFormatter
The message formating implementation that formats messages with the 'form_urlencoded' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
multipart_form_data
string
org.apache.axis2.transport.http.MultipartFormDataFormatter
-
The message formating implementation that formats messages with the 'multipart_form_data' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
text_plain
string
org.apache.axis2.format.PlainTextFormatter
-
The message formating implementation that formats messages with the 'text_plain' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
application_json
string
org.wso2.micro.integrator.core.json.JsonStreamFormatter
-
The message formating implementation that formats messages with the 'application_json' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
json_badgerfish
string
org.apache.axis2.json.JSONBadgerfishMessageFormatter
-
The message formating implementation that formats messages with the 'json_badgerfish' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
text_javascript
string
org.apache.axis2.json.JSONMessageFormatter
-
The message formating implementation that formats messages with the 'text_javascript' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
octet_stream
string
org.wso2.carbon.relay.ExpandingMessageFormatter
-
The message formatting implementation that formats messages with the 'octet_stream' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
application_binary
string
org.apache.axis2.format.BinaryFormatter
-
The message formating implementation that formats messages with the 'application_binary' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
text_xml
string
org.apache.axis2.transport.http.SOAPMessageFormatter
-
The message formating implementation that formats messages with the 'text_xml' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
soap_xml
string
org.apache.axis2.transport.http.SOAPMessageFormatter
-
The message formating implementation that formats messages with the 'soap_xml' content type before they are sent out of the Micro Integrator. If required, you can change the default formating class.
Message Formatters (blocking mode)¶
[blocking.message_formatters]
form_urlencoded = "org.apache.synapse.commons.formatters.XFormURLEncodedFormatter"
multipart_form_data = "org.apache.axis2.transport.http.MultipartFormDataFormatter"
application_xml = "org.apache.axis2.transport.http.ApplicationXMLFormatter"
text_xml = "org.apache.axis2.transport.http.SOAPMessageFormatter"
soap_xml = "org.apache.axis2.transport.http.SOAPMessageFormatter"
text_plain = "org.apache.axis2.format.PlainTextFormatter"
application_json = "org.wso2.micro.integrator.core.json.JsonStreamFormatter"
json_badgerfish = "org.apache.axis2.json.JSONBadgerfishMessageFormatter"
text_javascript = "org.apache.axis2.json.JSONMessageFormatter"
octet_stream = "org.wso2.carbon.relay.ExpandingMessageFormatter"
application_binary = "org.apache.axis2.format.BinaryFormatter"[blocking.message_formatters]
This configuration header is required for configuring the message formatter implementations that are used to format messages that are sent out from the API Manager in blocking mode. You can use the same list of parameters that are available for message formatters in non-blocking mode.
Custom Message Builders (non-blocking mode)¶
[[custom_message_builders]]
content_type = "application/json/badgerfish"
class = "org.apache.axis2.json.JSONBadgerfishOMBuilder"[[custom_message_builders]]
This configuration header is required for configuring the custom message builder implementation class and the selected content types to which the builder should apply in non-blocking mode.
content_type
string Required
-
-
The content types to which the custom message builder implementation should apply. You can specify the list of content types as follows: application/json/badgerfish.
class
string Required
-
-
The custom message builder implementation that should apply to the given content types.
Custom Message Builders (blocking mode)¶
[[blocking.custom_message_builders]]
content_type = "application/json/badgerfish"
class = "org.apache.axis2.json.JSONBadgerfishOMBuilder"[[blocking.custom_message_builders]]
This configuration header is required for configuring the custom message builder implementation class and the selected content types to which the builder should apply in blocking mode. You can use the same list of parameters that are available for custom message builders in non-blocking mode.
Custom Message Formatters (non-blocking mode)¶
[[custom_message_formatters]]
content_type = "application/json/badgerfish"
class = "org.apache.axis2.json.JSONBadgerfishMessageFormatter"[[custom_message_formatters]]
This configuration header is required for configuring the custom message formatter implementation class and the selected content types to which the formatter should apply in non-blocking mode.
content_type
string Required
-
-
The content types to which the custom message formatter implementation should apply. You can specify the list of content types as follows: application/json/badgerfish.
class
string Required
-
-
The custom message formatter implementation that should apply to the given content types.
Custom Message Formatters (blocking mode)¶
[[blocking.custom_message_formatters]]
content_type = "application/json/badgerfish"
class = "org.apache.axis2.json.JSONBadgerfishMessageFormatter"[[blocking.custom_message_formatters]]
This configuration header is required for configuring the custom message formatter implementation class and the selected content types to which the formatter should apply in blocking mode. You can use the same list of parameters that are available for custom message formatters in non-blocking mode.
Message Mediation¶
[mediation]
synapse.core_threads = 20
synapse.max_threads = 100
synapse.threads_queue_length = 10
synapse.global_timeout_interval = "120000ms"
synapse.enable_xpath_dom_failover=true
synapse.temp_data_chunk_size=3072
synapse.command_debugger_port=9005
synapse.event_debugger_port=9006
synapse.script_mediator_pool_size=15
synapse.enable_xml_nil=false
synapse.disable_auto_primitive_regex = "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?([eE][+-]?[0-9]+)?$"
synapse.disable_custom_replace_regex = "@@@"
synapse.enable_namespace_declaration = false
synapse.build_valid_nc_name = false
synapse.enable_auto_primitive = false
synapse.json_out_auto_array = false
synapse.preserve_namespace_on_xml_to_json=false
flow.statistics.enable=false
flow.statistics.capture_all=false
statistics.enable_clean=true
statistics.clean_interval = "1000ms"
stat.tracer.collect_payloads=false
stat.tracer.collect_mediation_properties=false
inbound.core_threads = 20
inbound.max_threads = 100[mediation]
This configuration header groups the parameters used for tuning the mediation process (Synapse engine) of the API Manager. These parameters are mainly used when mediators such as Iterate and Clone (which uses the internal thread pools) are used.
synapse.core_threads
integer
20
-
The initial number of synapse threads in the pool. This parameter is applicable only if the Iterate and Clone mediators are used to handle a higher load. These mediators use a thread pool to create new threads when processing messages and sending messages in parallal. You can configure the size of the thread pool by this parameter. The number of threads specified via this parameter should be increased as required to balance an increased load. Increasing the value specified for this parameter results in higher performance of the Iterate and Clone mediators.
synapse.max_threads
integer
100
-
The maximum number of synapse threads in the pool. This parameter is applicable only if the Iterate and Clone mediators are used to handle a higher load. The number of threads specified for this parameter should be increased as required to balance an increased load.
synapse.threads_queue_length
integer
10
-
The length of the queue that is used to hold the runnable tasks that are to be executed by the pool. This parameter is applicable only if the Iterate and Clone mediators are used to handle a higher load. You can specify a finite value as the queue length by giving any positive number. If this parameter is set to (-1) it means that the task queue length is infinite. If the queue length is finite, there can be situations where requests are rejected when the task queue is full and all the cores are occupied. If the queue length is infinite, and if some thread locking happens, the server can go out of memory. Therefore, you need to decide on an optimal value based on the actual load.
synapse.global_timeout_interval
integer
120000
-
The maximum number of milliseconds within which a response for the request should be received. A response that arrives after the specified number of seconds cannot be correlated with the request. Hence, a warning will be logged and the request will be dropped. This parameter is also referred to as the time-out handler.
synapse.enable_xpath_dom_failover
boolean
true
"true" or "false"
If this parameter is set to true, the Micro Integrator can switch to XPATH 2.0. This parameter can be set to false if XPATH 2.0 evaluations cause performance degradation. The Micro Integrator uses the Saxon Home Edition when implementing XPATH 2.0 functionalities, and thus supports all the functions that are shipped with it. For more information on the supported functions, see the Saxon Documentation.
synapse.temp_data_chunk_size
integer
3072
-
The message size that can be processed by the Micro Integrator.
synapse.script_mediator_pool_size
integer
15
-
When using externally referenced scripts, this parameter specifies the size of the script engine pool that should be used per script mediator. The script engines from this pool are used for externally referenced script execution where updates to external scripts on an engine currently in use may otherwise not be thread safe. It is recommended to keep this value at a reasonable size since there will be a pool per externally referenced script.
synapse.preserve_namespace_on_xml_to_json
boolean
false
"true" or "false"
Preserves the namespace declarations in the JSON output during XML to JSON message transformations.
flow.statistics.enable
boolean
false
"true" or "false"
Set this property to true and enable statistics for the required integration artifact to record information such as the following: <ul><li>The time spent on each mediator.</li><li>The time spent on processing each message.</li><li>The fault count of a single message flow.</li></ul>
flow.statistics.enable
boolean
false
"true" or "false"
Set this property to 'true' and set the flow.statistics.enable property also to 'true'. This will enable mediation statistics for all the integration artifacts by default. If you set this property to 'false', you need to set the flow.statistics.enable property to 'true' and manually enable statistics for the required integration artifact.
statistics.enable_clean
boolean
true
"true" or "false"
If this parameter is set to true, all the existing statistics would be cleared before processing a request. This is recommended if you want to increase the processing speed.
stat.tracer.collect_payloads
boolean
false
"true" or "false"
Set this property to true and enable tracing for the required integration artifact to record the message payload before and after the message mediation performed by individual mediators.
stat.tracer.collect_mediation_properties
boolean
false
"true" or "false"
Set this property to true and enable tracing for the required integration artifact to record the following information:<ul><li>Message context properties.</li><li>Message transport-scope properties.</li></ul>
Synapse Handlers¶
enabled_global_handlers= ["custom_logger"]
[synapse_handlers]
custom_logger.name= "SynapseLogHandler"
custom_logger.class= "com.wso2.apim.log.handler.SynapseLogHandler"
[[synapse_handlers]]
This configuration header is required for configuring a synapse handler with the name and the implementation class.
name
string Required
-
-
Name of the synapse handler.
class
string Required
-
-
The synapse handler implementation.
Governance Configurations¶
[governance]
life_cycle_checklist_items_enabled = true[governance]
This includes configurations related to underlying governance registry in API-M.
life_cycle_checklist_items_enabled
boolean
true
true,false
Enable lifecycle checklist items.
Qpid broker heartbeat configurations¶
[qpid.heartbeat]
delay = 1
timeout_factor = 3.0[qpid.heartbeat]
This includes configurations related to the frequency of the internal heartbeat sent by the underlying Qpid brocker component of Traffic Manager. You need to to configure a proper delay for the heartbeat value if the connections will stay idle for a long time.
delay
integer
0
This defines an interval (in seconds) between the pings sent to a subscriber to keep the connection alive.
timeoutFactor
float
2.0
The time duration (in seconds) allowed for a subscriber to respond to a heartbeat request. If this time elapses before the response is received, the channel of communication between the server and the subscriber will end.
Health Check API configurations¶
[carbon_health_check]
enable = true[carbon_health_check]
This includes configurations related to carbon health check API.
enable
boolean
false
true,false
Enable carbon health checker.
[carbon_health_check.health_checker.super_tenant_health_checker]
enable = true
order = "98"[carbon_health_check.health_checker.super_tenant_health_checker]
This includes configurations related to super tenant userstore health check.
enable
boolean
true
true,false
Enable user store health checker.
order
integer
98
The execution order.
[carbon_health_check.health_checker.super_tenant_health_checker.properties]
monitored.user.stores = "primary,sec"[carbon_health_check.health_checker.super_tenant_health_checker.properties]
This includes properties related to super tenant userstore health check.
monitored.user.stores
string array
An array of domain names of the userstores to monitor health. If not given, health is monitered on all the super tenant secondary user stores.
[carbon_health_check.health_checker.data_source_health_checker]
enable = true
order = "97"[carbon_health_check.health_checker.data_source_health_checker]
This includes configurations related to the health check of data sources which are configured in master-datasources by checking the connection pool information and by getting a connection from the pool.
enable
boolean
true
true,false
Enable datasource health checker.
order
integer
98
The execution order.
[carbon_health_check.health_checker.data_source_health_checker.properties]
pool_usage_limit_percentage = 80
monitored.datasources = "jdbc/WSO2AM_DB,jdbc/SHARED_DB,jdbc/WSO2CarbonDB"[carbon_health_check.health_checker.data_source_health_checker.properties]
This includes properties related to datastore health check.
pool_usage_limit_percentage
integer
80
Datasource connection pool usage
monitored.datasources
string array
An array of jndiConfig names of datasources to monitor health. If not given, health is monitered on all the datastores.
[health_checker]
name = "CustomHealthChecker"
order = "90"
[health_checker.properties]
first_property = "value"[health_checker]
This includes configurations related to adding custom health checkers.
name
string
-
The custom health checker name.
order
integer
-
The custom health checker execution order.
properties
integer
-
The custom health checker properties. Provide as key value pairs.
OAuth configurations¶
[oauth]
allowed_scopes = ["scope1", "scope2"]
additional_params_from_error_url = true
timestamp_skew = "0"
[oauth.extensions]
token_generator="org.wso2.carbon.identity.oauth2.token.OauthTokenIssuerImpl"
token_context_generator = "org.wso2.carbon.identity.oauth2.authcontext.JWTTokenGenerator"
token_context_claim_retriever = "org.wso2.carbon.identity.oauth2.authcontext.DefaultClaimsRetriever"
token_context_dialect_uri = "http://wso2.org/claims"
[oauth]
This includes OAuth configurations in API-M.
additional_params_from_error_url
boolan
false
true,false
Allow additional parameters in OAuth2 error url.
allowed_scopes
list of strings
Configuration to pass a list of scopes which are allowed without any validation.
timestamp_skew
integer
0
Time stamp skew in seconds.
extensions.token_generator
string
org.wso2.carbon.identity.oauth2.token.OauthTokenIssuerImpl
Token Issuer class.
extensions.token_context_generator
string
org.wso2.carbon.identity.oauth2.authcontext.JWTTokenGenerator
Token Issuer class for Authorization Context.
extensions.token_context_claim_retriever
string
org.wso2.carbon.identity.oauth2.authcontext.DefaultClaimsRetriever
Claim Retriever Implementation class for Authorization Context.
extensions.token_context_dialect_uri
string
http://wso2.org/claims
Consumer Dialect URI for Authorization Context.
[oauth.token_validation]
user_access_token_validity = "3000"
app_access_token_validity = "2000"
refresh_token_validity = "86400"
[oauth.token_validation]
This includes configurations for OAuth token validation.
app_access_token_validity
integer
3600
Default validity period for application access tokens in seconds.
user_access_token_validity
integer
3600
Default validity period for user access tokens in seconds.
refresh_token_validity
integer
86400
Default validity period for refresh tokens in seconds.
[oauth.token_cleanup]
enable = true
retain_access_tokens_for_auditing = true[oauth.token_cleanup]
This includes OAuth configurations for old, invalid token cleanup in API-M.
enable
boolean
true
true,false
Enable token cleanup.
retain_access_tokens_for_auditing
boolean
true
true,false
Set this to true, to move the old, invalid tokens to the Audit table when token cleaning is enabled. Set this to false, if you do not wish to store old tokens in the Audit table.
[oauth.oidc.extensions]
id_token_builder = "org.wso2.carbon.identity.openidconnect.DefaultIDTokenBuilder"
claim_callback_handler = "org.wso2.carbon.identity.openidconnect.SAMLAssertionClaimsCallback"
user_info_claim_retriever = "org.wso2.carbon.identity.oauth.endpoint.user.impl.UserInfoUserStoreClaimRetriever"
[oauth.oidc.user_info]
response_type = "json"
[oauth.oidc.token_validation]
id_token_validity = "3600"
[oauth.oidc.id_token]
issuer = "${carbon.protocol}://${carbon.host}:${carbon.management.port}/oauth2/token"
redirect_error_page = true
[oauth.oidc.claims]
enable_oidc_dialect = true
enable_unmapped_user_attributes = true
[oauth.oidc]
This includes configurations related to OpenID Connect authorization server in API-M.
extensions.id_token_builder
string
org.wso2.carbon.identity.openidconnect.DefaultIDTokenBuilder
IDToken builder implementation class.
extensions.claim_callback_handler
string
org.wso2.carbon.identity.openidconnect.SAMLAssertionClaimsCallback
This can be used to return extra custom claims with the IDToken . You can implement a claims call back handler to push the custom claims to the IDToken implmenting interface CustomClaimsCallbackHandler.
extensions.user_info_claim_retriever
string
org.wso2.carbon.identity.oauth.endpoint.user.impl.UserInfoUserStoreClaimRetriever
Defines the class which builds the claims for the User Info Endpoint's response. This class needs to implement the interface UserInfoClaimRetriever.
user_info.response_type
string
json
The value that is set to get JWT response from user info endpoint.
token_validation.id_token_validity
integer
3600
The expiration value of the IDToken in seconds.
id_token.issuer
string
${carbon.protocol}://${carbon.host}:${carbon.management.port}/oauth2/token (OAuth2 Token Endpoint URL)
The value of issuer of the IDToken. This should be changed according to the deployment values.
id_token.redirect_error_page
boolean
true
true,false
Send the response to OAuth2 error page.
claims.enable_oidc_dialect
boolean
false
true,false
Enable converting original claims from assertions to OIDC Dialect.
claims.enable_unmapped_user_attributes
boolean
false
true,false
Enable adding unmapped user attributes.
[oauth.grant_type.authorization_code]
enable = true
grant_handler = "org.wso2.carbon.identity.oauth2.token.handlers.grant.AuthorizationCodeGrantHandler"
[oauth.grant_type.password]
enable = true
grant_handler = "org.wso2.carbon.identity.oauth2.token.handlers.grant.PasswordGrantHandler"
[oauth.grant_type.refresh_token]
enable = true
grant_handler = "org.wso2.carbon.identity.oauth2.token.handlers.grant.RefreshGrantHandler"
[oauth.grant_type.client_credentials]
enable = true
grant_handler = "org.wso2.carbon.identity.oauth2.token.handlers.grant.ClientCredentialsGrantHandler"
[oauth.grant_type.saml_bearer]
enable = true
grant_handler = "org.wso2.carbon.identity.oauth2.token.handlers.grant.saml.SAML2BearerGrantHandler"
[oauth.grant_type.iwa_ntlm]
enable = true
grant_handler = "org.wso2.carbon.identity.oauth2.token.handlers.grant.iwa.ntlm.NTLMAuthenticationGrantHandlerWithHandshake"
grant_validator = "org.wso2.carbon.identity.oauth.common.NTLMAuthenticationValidator"
[oauth.grant_type.jwt_bearer]
enable = true
grant_handler = "org.wso2.carbon.identity.oauth2.grant.jwt.JWTBearerGrantHandler"
grant_validator = "org.wso2.carbon.identity.oauth2.grant.jwt.JWTGrantValidator"
[oauth.grant_type.kerberos]
enable = true
grant_handler = "org.wso2.carbon.identity.oauth2.grant.kerberos.KerberosGrant"
grant_validator = "org.wso2.carbon.identity.oauth2.grant.kerberos.KerberosGrantValidator"
[oauth.grant_type]
This includes configurations for supported OAuth grant types in API-M.
authorization_code.enable
boolean
true
true,false
Enable Authorization Code grant.
authorization_code.grant_handler
string
org.wso2.carbon.identity.oauth2.token.handlers.grant.AuthorizationCodeGrantHandler
Authorization Code grant implementation class.
password.enable
boolean
true
true,false
Enable Password grant.
password.grant_handler
string
org.wso2.carbon.identity.oauth2.token.handlers.grant.PasswordGrantHandler
Password grant implementation class.
refresh_token.enable
boolean
true
true,false
Enable Refresh Token grant.
refresh_token.grant_handler
string
org.wso2.carbon.identity.oauth2.token.handlers.grant.RefreshGrantHandler
Refresh Token grant implementation class.
client_credentials.enable
boolean
true
true,false
Enable Refresh Token grant.
client_credentials.grant_handler
string
org.wso2.carbon.identity.oauth2.token.handlers.grant.ClientCredentialsGrantHandler
Client Credentials grant implementation class.
client_credentials.allow_refresh_tokens
boolean
false
true,false
Enable to allow refresh tokens for client credentails grant.
client_credentials.allow_id_token
boolean
false
true,false
Enable to allow ID tokens for client credentails grant.
saml_bearer.enable
boolean
true
true,false
Enable SAML2 Bearer grant.
saml_bearer.grant_handler
string
org.wso2.carbon.identity.oauth2.token.handlers.grant.saml.SAML2BearerGrantHandler
SAML2 Bearer grant implementation class.
iwa_ntlm.enable
boolean
true
true,false
Enable NTLM grant.
iwa_ntlm.grant_handler
string
org.wso2.carbon.identity.oauth2.token.handlers.grant.iwa.ntlm.NTLMAuthenticationGrantHandlerWithHandshake
NTLM grant implementation class.
iwa_ntlm.grant_validator
string
org.wso2.carbon.identity.oauth.common.NTLMAuthenticationValidator
NTLM grant validator implementation class.
jwt_bearer.enable
boolean
true
true,false
Enable JWT Bearer grant.
jwt_bearer.grant_handler
string
org.wso2.carbon.identity.oauth2.grant.jwt.JWTBearerGrantHandler
JWT Bearer grant implementation class.
jwt_bearer.grant_validator
string
org.wso2.carbon.identity.oauth2.grant.jwt.JWTGrantValidator
JWT Bearer grant validator implementation class.
kerberos.enable
boolean
false
true,false
Enable Kerberos Bearer grant.
kerberos.grant_handler
string
org.wso2.carbon.identity.oauth2.grant.kerberos.KerberosGrant
Kerberos grant implementation class.
kerberos.grant_validator
string
org.wso2.carbon.identity.oauth2.grant.kerberos.KerberosGrantValidator
Kerberos grant validator implementation class.
Token persistence configurations¶
[session_data.persistence]
persistence_pool_size = 0[session_data.persistence]
This includes configuration for session data persistence of tokens.
persistence_pool_size
integer
0
This value determines the number of threads in the thread pool that are used to consume the token persisting queue. Set the value 0 to enable synchronous token persistence. Set the value higher than 0 to enable asynchronous token persistence.
[oauth.token_generation]
retry_count_on_persistence_failures = 5[oauth.token_generation]
This includes configuration for OAuth2 token persistence.
retry_count_on_persistence_failures
integer
5
This indicates how many times to retry in the event of a CONN_APP_KEY violation when storing the access token.
User Store Properties¶
[user_store.properties]
TenantManager= "org.wso2.carbon.user.core.tenant.CommonHybridLDAPTenantManager"
ConnectionURL="ldap://localhost:10390"
ConnectionName="uid=admin,ou=system"
UserSearchBase="ou=Users,dc=wso2,dc=org"
GroupSearchBase="ou=Groups,dc=wso2,dc=org"
ConnectionPassword="admin"
AnonymousBind= "false"
WriteGroups= "true"
UserEntryObjectClass= "identityPerson"
UserNameAttribute= "uid"
UserNameSearchFilter= "(&(objectClass=person)(uid=?))"
UserNameListFilter= "(objectClass=person)"
DisplayNameAttribute= ""
GroupEntryObjectClass= "groupOfNames"
GroupNameAttribute= "cn"
GroupNameSearchFilter= "(&(objectClass=groupOfNames)(cn=?))"
GroupNameListFilter= "(objectClass=groupOfNames)"
MembershipAttribute= "member"
BackLinksEnabled= "false"
SCIMEnabled= "true"
IsBulkImportSupported= "true"
UsernameJavaRegEx= "[a-zA-Z0-9._\\-|//]{3,30}$"
RolenameJavaRegEx= "[a-zA-Z0-9._\\-|//]{3,30}$"
PasswordHashMethod= "PLAIN_TEXT"
ConnectionPoolingEnabled= "false"
LDAPConnectionTimeout= "5000"
ReplaceEscapeCharactersAtUserLogin= "true"
EmptyRolesAllowed= "true"
kdcEnabled= "false"
defaultRealmName= "WSO2.ORG"
StartTLSEnabled= "false"
UserRolesCacheEnabled= "true"
ConnectionRetryDelay= "2m"
UserCoreCacheTimeOut = 5 [user_store.properties]
TenantManager
string Required
org.wso2.carbon.user.core.tenant.JDBCTenantManager, org.wso2.carbon.user.core.tenant.CommonHybridLDAPTenantManager
MaxUserNameListLength
int
Controls the number of users listed in the user store of a WSO2 product. This is useful when you have a large number of users and don't want to list them all. Setting this property to 0 displays all users.
ConnectionURL
string
Connection URL to the user store server. In the case of default LDAP in Carbon, the port is specified in the carbon.xml file, and a reference to that port is included in this configuration.
ConnectionName
string
The username used to connect to the database and perform various operations. This user does not have to be an administrator in the user store or have an administrator role in the WSO2 product that you are using, but this user MUST have permissions to read the user list and users' attributes and to perform search operations on the user store. The value you specify is used as the DN ( Distinguish Name ) attribute of the user. This property is mandatory.
ConnectionPassword
string
Password for the ConnectionName user.
DisplayNameAttribute
string
This is an optional property. The Display Name Attribute is the name by which users will be listed when you search for users in the management console (Go to Configuration -> Users tab).
PasswordHashMethod
string
Password hash method to use when storing user entries in the user store.
UserNameListFilter
string
SHA SHA-1 SHA-256 MD5 PLAIN_TEXT
Filtering criteria for listing all the user entries in the user store. This query or filter is used when doing search operations on users. In this case, the search operation only provides the objects created from the specified class. This query is the same as listing out all the available users in the management console.
UserEntryObjectClass
string
wso2Person
Object class used to construct user entries. By default, it is a custom object class defined with the name wso2Person .
UserSearchBase
string
DN of the context or object under which the user entries are stored in the user store. In this case, it is the "users" container. When the user store searches for users, it will start from this location of the directory. Different databases have different search bases.
UserNameSearchFilter
string
Filtering criteria used to search for a particular user entry.
UserNameAtribute
string
The attribute used for uniquely identifying a user entry. Users can be authenticated using their email address, UID, etc. The name of the attribute is considered as the username.
PasswordJavaScriptRegEx
string
Policy that defines the password format.
UsernameJavaScriptRegEx
string
The regular expression used by the front-end components for username validation.
UsernameJavaRegEx
string
A regular expression to validate usernames. By default, strings have a length of 5 to 30. Only non-empty characters are allowed. You can provide ranges of alphabets, numbers and also ranges of ASCII values in the RegEx properties.
PasswordJavaRegEx
string
(LDAP and JDBC) A regular expression to validate passwords. By default, strings having a length between 5 to 30 with non-empty characters are allowed.
RolenameJavaRegEx
string
A regular expression to validate role names. By default, strings having a length between 5 to 30 with non-empty characters are allowed.
ReadGroups
boolean
true false
Specifies whether groups should be read from the user store. If this is disabled by setting it to false , none of the groups in the user store can be read, and the following group configurations are NOT mandatory: GroupSearchBase , GroupNameListFilter , or GroupNameAttribute .
WriteGroups
boolean
true false
Specifies whether groups should be written to user store.
GroupSearchBase
string
DN of the context under which user entries are stored in the user store.
GroupNameListFilter
string
Filtering criteria for listing all the group entries in the user store. Groups are created in LDAP using the "groupOfName" class. The group search operation only returns objects created from this class.
GroupEntryObjectClass
string
Object class used to construct group entries.
GroupNameSearchFilter
string
Filtering criteria used to search for a particular group entry.
GroupNameAttribute
string
Attribute used for uniquely identifying a user entry. This attribute is to be treated as the group name.
MembershipAttribute
string
Attribute used to define members of groups.
MembershipAttributeRange
int
1500
Attribute used by Active Directories where they need limit membership attributes. The default value for this is 1500.
UserRoleCacheEnabled
boolean
true
true false
This is to indicate whether to cache the role list of a user. By default this is set to true . Set it to false if the user roles are changed by external means and those changes should be instantly reflected in the Carbon instance.
UserDNPattern
string
(LDAP) The patten for the user's DN, which can be defined to improve the search. When there are many user entries in the LDAP user store, defining a UserDNPattern provides more impact on performances as the LDAP does not have to travel through the entire tree to find users.
ReplaceEscapeCharactersAtUserLogin
string
(LDAP) If the user name has special characters it replaces it to validate the user logging in. Only " \ " and " \\ " are identified as escape characters.
MultiTenantRealmConfigBuilder
string
Tenant Manager specific realm config parameter. Can be used to build different types of realms for the tenant.
LDAPConnectionTimeout
string
If the connection to an LDAP is inactive for the length of time (in milliseconds) specified by this property, the connection will be terminated.
SCIMEnabled
boolean
false
true false
This is to configure whether user store is supported for SCIM provisioning.
kdcEnabled
string
false
true false
If your user store is capable of acting as a Kerberos, Key Distribution Center (KDC) and if you like to enable it, set this property to true.
ConnectionPoolingEnabled
string
false
true false
Define whether LDAP connection pooling is enabled
ReadTimeout
string
The value of this property is the read timeout in milliseconds for LDAP operations. If the LDAP provider cannot get a LDAP response within that period, it aborts the read attempt. The integer should be greater than zero. An integer less than or equal to zero means no read timeout is specified which is equivalent to waiting for the response infinitely until it is received.
RetryAttempts
string
Retry the authentication request if a timeout happened
BackLinksEnabled
string
false
true false
Defines whether the backlink support is enabled. If you are using MemberOfAttribute attributes this should be set to true.
UserCoreCacheTimeOut
string
5
User core cache expiration duration
CaseInsensitiveUsername
string
Set the value to false for case insensitive JDBC user stores
Custom keystore configurations¶
[custom_keystore.APIKeyKeyStore]
file_name = "apikeysigner.jks"
type = "JKS"
password = "wso2carbon"
alias = "apikeysigner"
key_password = "wso2carbon"[custom_keystore.APIKeyKeyStore]
This includes configuration for custom Keystores in WSO2 API Manager
file_name
string
The name of the Keystore (the Keystore file should be placed inside <API-M_HOME>/repository/resources/security directory)
type
string
The Keystore type.
password
string
The Keystore password.
alias
string
Private key alias of the Keystore.
key_password
string
The private key password of the Keystore (WSO2 recommends that you maintain the identical Keystore password and key password due to known limitations).
HTTP Access Logs¶
[http_access_log]
useLogger = true[http_access_log]
This includes configuration for HTTP access log records.
useLogger
boolean
false
true,false
Set this to true to allow logs to get written into the `<APIM_HOME>repository/logs/wso2carbon.log` or any other log file and show up on the console.
Registry Handler properties¶
#### Sample deployment.toml entry
##### Registry handler 1 #####
[[registry_handler]]
class="org.wso2.carbon.registry.extensions.handlers.WSDLMediaTypeHandler"
filter_class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher"
[registry_handler.properties]
disableSymlinkCreation = "true"
myprop1= "true"
### parent property 1: schemaLocationConfiguration
[[registry_handler.nested_property]]
enable = true
name = "schemaLocationConfiguration"
type = "xml"
# nested property 1
[[registry_handler.nested_property.schemaLocationConfiguration]]
tag = 'location'
value = "/trunk/schemas/1"
key = "mykey"
# nested property 2
[[registry_handler.nested_property.schemaLocationConfiguration]]
tag = 'location'
value = "/trunk/schemas/2"
key = "mykey2"
# nested property 3
[[registry_handler.nested_property.schemaLocationConfiguration]]
tag = 'newlocation'
value = "/trunk/schemas/3"
key = "mykey3"
## parent property 2: wsdlLocationConfiguration
[[registry_handler.nested_property]]
enable = true
name = "wsdlLocationConfiguration"
type = "xml"
# nested property 1
[[registry_handler.nested_property.wsdlLocationConfiguration]]
tag = 'location'
value = "/trunk/wsdls/"
## parent property 3: policyLocationConfiguration
[[registry_handler.nested_property]]
enable = true
name = "policyLocationConfiguration"
type = "xml"
# nested property 1
[[registry_handler.nested_property.policyLocationConfiguration]]
tag = 'location'
value = "/trunk/policies/"
[registry_handler.filter_properties]
mediaType = "application/vnd.wso2-service+xml"
##### Registry handler 2 #####
[[registry_handler]]
class="org.wso2.carbon.registry.extensions.handlers.ZipWSDLMediaTypeHandle"
filter_class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher2"
[registry_handler.properties]
wsdlMediaType = "application/wsdl+xml"
schemaMediaType = "application/xsd+xml"
threadPoolSize = 50
disableSymlinkCreation = true
numberOfRetry = 3
## parent property 1: schemaLocationConfiguration
[[registry_handler.nested_property]]
enable = true
name = "schemaLocationConfiguration"
type = "xml"
# nested property 1
[[registry_handler.nested_property.schemaLocationConfiguration]]
tag = 'location'
value = "/trunk/schemas/1"
key = "mykey"
[registry_handler.filter_properties]
mediaType = "application/vnd.wso2-service+xml"
#### Sample registry.xml entry generated will be as follows
<!--Config for custom registry handlers.-->
<handler class="org.wso2.carbon.registry.extensions.handlers.WSDLMediaTypeHandler">
<property name="myprop1">true</property>
<property name="disableSymlinkCreation">true</property>
<property name="schemaLocationConfiguration" type="xml">
<location key="mykey">/trunk/schemas/1</location>
<location key="mykey2">/trunk/schemas/2</location>
<newlocation key="mykey3">/trunk/schemas/3</newlocation>
</property>
<property name="wsdlLocationConfiguration" type="xml">
<location>/trunk/wsdls/</location>
</property>
<property name="policyLocationConfiguration" type="xml">
<location>/trunk/policies/</location>
</property>
<filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
<property name="mediaType">application/vnd.wso2-service+xml</property>
</filter>
</handler>
<handler class="org.wso2.carbon.registry.extensions.handlers.ZipWSDLMediaTypeHandle">
<property name="schemaMediaType">application/xsd+xml</property>
<property name="threadPoolSize">50</property>
<property name="numberOfRetry">3</property>
<property name="wsdlMediaType">application/wsdl+xml</property>
<property name="disableSymlinkCreation">true</property>
<property name="schemaLocationConfiguration" type="xml">
<location key="mykey">/trunk/schemas/1</location>
</property>
<filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher2">
<property name="mediaType">application/vnd.wso2-service+xml</property>
</filter>
</handler>
[[registry_handler]]
Registry Handler configurations.
class
string Required
The class name of the Handler. Provided in the class attribute in the Handler.
filter_class
string Required
The class name of the filter which is associated with the Handler (Ex: org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher, org.wso2.carbon.registry.core.jdbc.handlers.filters.URLMatcher).
[registry_handler.properties]
Registry Handler custom properties which do not have nested elements. Properties are listed as key, value pairs. These custom properties will be used in Handler processing logic.
[[registry_handler.nested_property]]
Registry Handler custom property which has nested elements under it.
enable
boolean
false
true, false
Enables nested properties.
name
string Required
The name of the custom parent property.
type
string
xml
xml, null
The type of the custom parent property.
[[registry_handler.nested_property.<parent_property_name>]]
Nested element which is under a custom Registry Handler property.
tag
string Required
XML element name of the nested property.
value
string Required
Value of the nested property element.
key
string
Value of the additional key attribute of the XML element generated for the nested property.
[registry_handler.filter_properties]
Define registry handler filter element configurations.