

Choreo Connect Enforcer Configuration Catalog¶

This document describes all the configuration parameters that are used in ESB Choreo Connect Enforcer.

Instructions for use¶

Open the Choreo Connect configuration file according to the deployment type you are using.

Click here to see the configuration file location for your Choreo Connect deployment.

Navigate to the correct folder path and open the config.toml or config-toml-configmap.yaml file based on your Choreo Connect deployment.

Deployment	Mode	File name	Directory
Docker Compose	Choreo Connect as a Standalone Gateway	`config.toml`	`<CHOREO-CONNECT_HOME>/docker-compose/choreo-connect/conf/`
Docker Compose	Choreo Connect with MWARE ESB as a Control Plane	`config.toml`	`<CHOREO-CONNECT_HOME>/docker-compose/choreo-connect-with-apim/conf/`
Kubernetes	Choreo Connect as a Standalone Gateway	`config-toml-configmap.yaml`	`<CHOREO-CONNECT_HOME>/k8s-artifacts/choreo-connect/`
Kubernetes	Choreo Connect with MWARE ESB as a Control Plane	`config-toml-configmap.yaml`	`<CHOREO-CONNECT_HOME>/k8s-artifacts/choreo-connect-with-apim/`

Select the configuration sections, parameters, and values that are required for your use and add them as required. You can click view sample in each of the sections in this page to get the toml format. See the example .toml file given below.

# This is an example .toml file.
[enforcer.authService]
  port = 8081
  maxMessageSize = 1000000000
  maxHeaderLimit = 8192
  keepAliveTime = 600

[enforcer.authService.threadPool]
  coreSize = 400
  maxSize = 500
  keepAliveTime = 600
  queueSize = 1000

Auth Service¶

[enforcer.authService]
  port = 8081
  maxMessageSize = 1000000000
  maxHeaderLimit = 8192
  keepAliveTime = 600

[enforcer.authService] Required

The configurations of gRPC netty based server in Enforcer that handles the incoming requests in the Choreo Connect.

port

integer Required

Default: 8081

Port of the Enforcer auth service.

maxMessageSize

integer

Default: 1000000000

Maximum message size in bytes

maxHeaderLimit

integer

Default: 8192

Maximum header size in bytes

keepAliveTime

integer

Default: 600

Keep alive time in seconds for connection with the router via external auth service

tokenPrivateKeyPath

string

Default: /home/wso2/security/keystore/mg.key

Private key path to use for the token generation

Auth Service thread pool¶

[enforcer.authService.threadPool]
  coreSize = 400
  maxSize = 500
  keepAliveTime = 600
  queueSize = 1000

[enforcer.authService.threadPool] Required

The thread pool configurations of gRPC netty based server in Enforcer that handles the incoming requests in the Choreo Connect.

coreSize

integer Required

Default: 400

Minimum number of workers to keep alive

maxSize

integer

Default: 500

Maximum pool size

keepAliveTime

integer

Default: 600

Timeout in seconds for idle threads waiting for work

queueSize

integer

Default: 1000

Queue size of the worker threads

Filters¶

[[enforcer.filters]]
    className = "org.wso2.choreo.connect.custom.CCCustomFilter"
    position = 3
    [enforcer.filters.configProperties]
        testConfig1 = "testValue1"

[enforcer.filters]

The configurations for engaging custom filters in the Enforcer.

className

string Required

Default:

Fully qualified class name of the custom filter implementation.

position

integer Required

Default:

Position should be the final position (including already available filters) after all the filters are engaged. Position starts from 1.

configProperties

string

Default:

Filter specific custom configurations. Only `(string, string)` key-value pairs are accepted.

Cache¶

[enforcer.cache]
  enabled = true
  maximumSize = 10000
  expiryTime = 15

[enforcer.cache] Required

The configurations of token caching in the Choreo Connect.

enabled

boolean Required

Default: true

Enable/Disable token cache.

maximumSize

integer Required

Default: 10000

Maximum cache size.

expiryTime

integer Required

Default: 15

Expiry time in seconds

Management¶

[enforcer.management]
username = "admin"
password = "admin"

[enforcer.management] Required

The configurations for the Enforcer REST API credentials.

username

string Required

Default: admin

Username

password

string Required

Default: admin

Password

REST Server¶

[enforcer.restserver]
enabled = true

[enforcer.restserver] Required

The configuration of the Enforcer Admin REST server.

boolean Required

Default: true

Enable/Disable Enforcer Admin REST server.

JWT Generator¶

[enforcer.jwtGenerator]
  enabled = false
  encoding = "base64"
  claimDialect = "http://wso2.org/claims"
  convertDialect = false
  header = "X-JWT-Assertion"
  signingAlgorithm = "SHA256withRSA"
  enableUserClaims = false
  gatewayGeneratorImpl = "org.wso2.carbon.apimgt.common.gateway.jwtgenerator.APIMgtGatewayJWTGeneratorImpl"
  claimsExtractorImpl = "org.wso2.carbon.apimgt.impl.token.ExtendedDefaultClaimsRetriever"
  publicCertificatePath = "/home/wso2/security/truststore/mg.pem"
  privateKeyPath = "/home/wso2/security/keystore/mg.key"

[enforcer.jwtGenerator]

The configuration of the backend jwt generation in the Choreo Connect.

enabled

boolean Required

Default:

Enable/Disable backend JWT generation

encoding

string

Default: base64

Possible Values: base64, base64url

Encoding of the JWT

claimDialect

string Required

Default: http://wso2.org/claims

The JWT access token contains all claims that are defined in the enforcer.jwtGenerator.claimDialect element. The default value of this element is http://wso2.org/claims. To get the list of a specific user's claims that need to be included in the JWT, uncomment this element after enabling the JWT. It will include all claims in http://wso2.org/claims to the JWT access token.

convertDialect

boolean

Default: false

Remap the OIDC claims into the configured dialect

header

string Required

Default: X-JWT-Assertion

The name of the HTTP header to which the JWT is attached.

signingAlgorithm

string

Default: SHA256withRSA

Possible Values: SHA256withRSA, NONE

The signing algorithm is used to sign the JWT.

enableUserClaims

boolean

Default: false

Enable/Disable user claims.

gatewayGeneratorImpl

string

Default: org.wso2.carbon.apimgt.common.gateway.jwtgenerator.APIMgtGatewayJWTGeneratorImpl

Custom JWT generator

claimsExtractorImpl

string

Default: org.wso2.carbon.apimgt.impl.token.ExtendedDefaultClaimsRetriever

Custom Claim Retriever to add custom claims into JWT

publicCertificatePath

string

Default: /home/wso2/security/truststore/mg.pem

Public certificate for generated JWT

privateKeyPath

string

Default: /home/wso2/security/keystore/mg.key

Private key path used for JWT generation

JWT Issuer¶

[enforcer.jwtIssuer]
  enabled = true
  issuer = "https://localhost:9095/testkey"
  encoding = "base64"
  claimDialect = ""
  signingAlgorithm = "SHA256withRSA"
  publicCertificatePath = "/home/wso2/security/truststore/mg.pem"
  privateKeyPath = "/home/wso2/security/keystore/mg.key"
  validityPeriod = 3600

[enforcer.jwtIssuer]

The issuer configuration required to generate token at Choreo Connect.

enabled

boolean Required

Default: true

Enable/Disable JWT generation.

issuer

string Required

Default: https://localhost:9095/testkey

Issuer value for the JWT under iss claim.

encoding

integer

Default: base64

Possible Values: base64,base64url

Encoding of the JWT

claimDialect

string

Default: 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.

signingAlgorithm

string

Default: SHA256withRSA

Possible Values: SHA256withRSA, NONE

The signing algorithm is used to sign the JWT.

publicCertificatePath

string

Default: /home/wso2/security/truststore/mg.pem

Public certificate for generated JWT.

privateKeyPath

string

Default: /home/wso2/security/keystore/mg.key

Private key path used for JWT generation.

validityPeriod

integer

Default: 3600

Validity period of the JWT in seconds.

JWT Issuer User¶

[[enforcer.jwtIssuer.jwtUser]]
  username = "admin"
  password = "$env{enforcer_admin_pwd}"

[enforcer.jwtIssuer.jwtUser] Required

Configure allowed users to use the JWT generated by the Choreo Connect. You can provide multiple users.

username

string Required

Default: admin

Username

password

string Required

Default: $env{enforcer_admin_pwd}

Password

Auth Header¶

[enforcer.security.authHeader]
  enableOutboundAuthHeader = false
  authorizationHeader = "authorization"

[enforcer.security.authHeader]

Configurations related to Authorization header

enableOutboundAuthHeader

boolean Required

Default: false

Remove authorization header from backend request

authorizationHeader

string Required

Default: authorization

Header name which authorization token coming from the downstream client

Mutual SSL¶

[enforcer.security.mutualSSL]
  certificateHeader = "X-WSO2-CLIENT-CERTIFICATE"
  enableClientValidation = true
  clientCertificateEncode = false
  enableOutboundCertificateHeader = false

[enforcer.security.mutualSSL]

Configurations related to Mutual SSL

certificateHeader

string Required

Default: X-WSO2-CLIENT-CERTIFICATE

Header name which client certificate coming from the downstream client

enableClientValidation

boolean Required

Default: true

Select between directly sending client certificate and sending client certificate within a header

clientCertificateEncode

boolean Required

Default: false

Enable/Disable client certificate decode process in Choreo Connect when the certificate is passed in a header.

enableOutboundAuthHeader

boolean Required

Default: false

Remove client certificate header from backend request.

Token Service¶

[[enforcer.security.tokenService]]
  name="Resident Key Manager"
  issuer = "https://localhost:9443/oauth2/token"
  certificateAlias = "wso2carbon"
  jwksURL = ""
  validateSubscription = false
  consumerKeyClaim = "azp"
  certificateFilePath = "/home/wso2/security/truststore/wso2carbon.pem"

[enforcer.security.tokenService]

Configuration required to JWT token authorization. You can provide multiple JWT issuers.

name

string Required

Default:

Provide unique name for the JWT issuer

issuer

string Required

Default:

Issuer of the token. The issuer to validate a token is picked based on the iss value in the JWT

certificateAlias

string

Default:

Alias name given in Enforcer truststore for the public certificate of the JWT issuer.

jwksURL

integer

Default:

JWKS endpoint of the issuer.

validateSubscription

boolean

Default: false

Enable/Disable subscription validation.

consumerKeyClaim

string

Default:

The claim in which the consumer key of the application is coming.

certificateFilePath

string

Default:

Certificate Filepath within Enforcer

Throttling¶

[enforcer.throttling]
  enableGlobalEventPublishing = false
  enableHeaderConditions = false
  enableQueryParamConditions = false
  enableJwtClaimConditions = false
  jmsConnectionInitialContextFactory = "org.wso2.andes.jndi.PropertiesFileInitialContextFactory"
  jmsConnectionProviderURL = "amqp://admin:$env{tm_admin_pwd}@carbon/carbon?brokerlist='tcp://localhost:5672'"

[enforcer.throttling]

Configurations related to Throttling

enableGlobalEventPublishing

boolean Required

Default: false

Connect with the central traffic manager.

enableHeaderConditions

boolean Required

Default: false

Enable global advanced throttling based on request header conditions.

enableQueryParamConditions

boolean Required

Default: false

Enable global advanced throttling based on request query parameter conditions.

enableJwtClaimConditions

boolean Required

Default: false

Enable global advanced throttling based on jwt claim conditions.

jmsConnectionInitialContextFactory

string Required

Default: org.wso2.andes.jndi.PropertiesFileInitialContextFactory

The message broker context factory.

jmsConnectionProviderURL

string Required

Default: amqp://admin:$env{tm_admin_pwd}@carbon/carbon?brokerlist='tcp://apim:5672'

The message broker connection URL.

Binary Throttle publishing configurations¶

[enforcer.throttling.publisher]
  username = "admin"
  password = "$env{tm_admin_pwd}"

[enforcer.throttling.publisher] Required

Throttling configurations related to event publishing using a binary connection. The following are credentials required to establish connection between Traffic Manager

username

string Required

Default: admin

Username

password

string Required

Default: $env{tm_admin_pwd}

Password

Binary Throttle publishing URL group configurations¶

[[enforcer.throttling.publisher.URLGroup]]
  receiverURLs = ["tcp://localhost:9611"]
  authURLs = ["ssl://localhost:9711"]

[enforcer.throttling.publisher.URLGroup] Required

Throttling configurations related to event publishing using a binary connection. The following are Receiver URL and the authentication URL of the Traffic manager node/nodes. You can provide multiple URL groups

receiverURLs

string Required

Default: tcp://localhost:9611

Receiver URLs

authURLs

string Required

Default: ssl://localhost:9711

Auth URLs

Binary Throttle publishing pool configurations¶

[enforcer.throttling.publisher.pool]
  maxIdleDataPublishingAgents = 1000
  initIdleObjectDataPublishingAgents = 200
  publisherThreadPoolCoreSize = 200
  publisherThreadPoolMaximumSize = 1000
  publisherThreadPoolKeepAliveTime = 200

[enforcer.throttling.publisher.pool]

Throttling configurations related to event publishing using a binary connection. The following are data publisher object pool configurations

maxIdleDataPublishingAgents

integer

Default: 1000

Maximum idle number of connections

initIdleObjectDataPublishingAgents

integer

Default: 200

Minimum idle number of connections

publisherThreadPoolCoreSize

integer

Default: 200

Thread pool core size

publisherThreadPoolMaximumSize

integer

Default: 1000

The maximum size of the thread pool

publisherThreadPoolKeepAliveTime

integer

Default: 200

The timeframe after which the publisher thread pool is terminated in seconds

Binary Throttle publishing agent configurations¶

[enforcer.throttling.publisher.agent]
  sslEnabledProtocols = "TLSv1.2"
  ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_DSS_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256  ,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_DSS_WITH_AES_128_GCM_SHA256  ,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA,TLS_EMPTY_RENEGOTIATION_INFO_SCSV"
  queueSize = 32768
  batchSize = 200
  corePoolSize = 1
  socketTimeoutMS = 30000
  maxPoolSize = 1
  keepAliveTimeInPool = 20
  reconnectionInterval = 30
  # TCP connection pool configurations (for data publishing)
  maxTransportPoolSize = 250
  maxIdleConnections = 250
  evictionTimePeriod = 5500
  minIdleTimeInPool = 5000
  # SSL connection pool configurations (for authentication)
  secureMaxTransportPoolSize = 250
  secureMaxIdleConnections = 250
  secureEvictionTimePeriod = 5500
  secureMinIdleTimeInPool = 5000

[enforcer.throttling.publisher.agent] Required

Throttling configurations related to event publishing using a binary connection. The following are data publisher agent configurations

sslEnabledProtocols

string Required

Default: TLSv1.2

SSL Protocols

ciphers

string Required

Default:

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_DSS_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256  ,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_DSS_WITH_AES_128_GCM_SHA256  ,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA,TLS_EMPTY_RENEGOTIATION_INFO_SCSV

ciphers

queueSize

integer Required

Default: 32768

The size of the queue event disruptor which handles events before they are published. The value specified should always be the result of an exponent with 2 as the base.

batchSize

integer Required

Default: 200

The maximum number of events in a batch sent to the queue event disruptor at a given time.

corePoolSize

integer Required

Default: 1

The number of threads that will be reserved to handle events at the time you start.

socketTimeoutMS

integer Required

Default: 30000

Socket timeout in milliseconds.

maxPoolSize

integer Required

Default: 1

The maximum number of threads that should be reserved at any given time to handle events.

keepAliveTimeInPool

integer Required

Default: 20

The amount of time which threads in excess of the core pool size may remain idle before being terminated.

reconnectionInterval

integer Required

Default: 30

The time interval between reconnection in seconds.

maxTransportPoolSize

integer Required

Default: 250

Maximum pool size for TCP connection pool configurations (for data publishing).

maxIdleConnections

integer Required

Default: 250

Maximum idle connections for TCP connection pool configurations (for data publishing).

evictionTimePeriod

integer Required

Default: 5500

Eviction time period for TCP connection pool configurations (for data publishing).

minIdleTimeInPool

integer Required

Default: 5000

Minimum idle time in pool for TCP connection pool configurations (for data publishing).

secureMaxTransportPoolSize

integer Required

Default: 250

Maximum pool size for SSL connection pool configurations (for authentication).

secureMaxIdleConnections

integer Required

Default: 250

Maximum number of idle connections for SSL connection pool configurations (for authentication).

secureEvictionTimePeriod

integer Required

Default: 250

Eviction time period for SSL connection pool configurations (for authentication).

secureMinIdleTimeInPool

integer Required

Default: 250

Minimum idle time in pool for SSL connection pool configurations (for authentication).

Metrics¶

[enforcer.metrics]
  enabled = false
  type = "azure"

[enforcer.metrics]

Metrics Configurations for Choreo Connect.

enabled

boolean Required

Default: false

Enable/Disable Metrics.

type

string Required

Default: azure

Type of the metrics server.

Enviroment variable configs¶

Enviroment variable name	Values	Default value	Description
TRUST_DEFAULT_CERTS	true / false	true	When set to true, this loads the trusted root certificates in the `<JAVA_HOME>/lib/security/cacerts` location to the Enforcer truststore. Set this to false to avoid loading them.

Top