Configuration catalog ¶
The configuration model of WSO2 Identity Server is based on the toml format.
The <IS_HOME>/repository/conf/deployment.toml file is the single source used to configure and tune various features.
This document describes all the configuration parameters used in WSO2 Identity Server.
Server [server]
¶
Basic configurations to identify and deploy a WSO2 Identity Server node.
[server]
hostname = "localhost"
node_ip = "127.0.0.1"
base_path = "${carbon.protocol}://${carbon.host}:${carbon.management.port}"
serverDetails = "WSO2 Identity Server"
The hostname of the machine hosting the Identity Server instance.
The IP address of the machine hosting the Identity Server instance.
The base path URL used to access the server.
A description of the server instance.
Super admin [super_admin]
¶
Configurations for the super admin user of the Identity Server.
[super_admin]
username = "admin"
password = "admin"
admin_role = "admin"
create_admin_account = false
The username of the super admin user.
The password of the super admin user. Use environment variables in production environments.
The role name assigned to the super admin user.
Set to true to create the admin account if it does not already exist.
Primary keystore [keystore.primary]
¶
Configurations for the primary keystore used to sign and encrypt tokens.
[keystore.primary]
name = "wso2carbon.jks"
password = "wso2carbon"
The filename of the primary keystore.
The password of the primary keystore file.
TLS keystore [keystore.tls]
¶
Configurations for the keystore used for TLS communication.
[keystore.tls]
alias = "wso2carbon"
key_password = "wso2carbon"
password = "wso2carbon"
The alias of the TLS key entry inside the keystore.
The password for the TLS key entry.
The password for the TLS keystore file.
Truststore [truststore]
¶
Configurations for the truststore, which validates certificates from external systems.
[truststore]
password = "wso2carbon"
The password for the truststore file.
Shared database [database.shared_db]
¶
Configurations for the shared database that stores registry and governance data.
[database.shared_db]
type = "mysql"
hostname = "localhost"
port = 3306
name = "regdb"
username = "regadmin"
password = "regadmin"
The type of the database.
The hostname of the database server.
The port on which the database server listens.
The name of the shared database.
The username for the database connection.
The password for the database connection.
Shared database pool options [database.shared_db.pool_options]
¶
Connection pool settings for the shared database. Tune these based on your database server capacity and load.
[database.shared_db.pool_options]
maxActive = 80
maxWait = 360000
minIdle = 5
testOnBorrow = true
validationInterval = 30000
validationQuery = "SELECT 1"
defaultAutoCommit = false
commitOnReturn = true
The maximum number of active connections in the pool.
The maximum time (in milliseconds) to wait for a connection before throwing an error.
The minimum number of idle connections maintained in the pool.
Set to true to validate a connection before borrowing it from the pool.
The interval (in milliseconds) between successive connection validation runs.
The SQL query used to validate connections.
Set to true to enable auto-commit on borrowed connections.
Set to true to commit any pending transactions when a connection returns to the pool. Required for PostgreSQL.
Identity database [database.identity_db]
¶
Configurations for the identity database that stores user identity and authentication data.
[database.identity_db]
type = "mysql"
hostname = "localhost"
port = 3306
name = "regdb"
username = "regadmin"
password = "regadmin"
url = "jdbc:mysql://DB_HOST:3306/WSO2_IDENTITY_DB"
driver = "com.mysql.cj.jdbc.Driver"
The type of the database.
The hostname of the database server.
The port on which the database server listens.
The name of the identity database.
The username for the database connection.
The password for the database connection.
A full JDBC connection URL. When set, this overrides the individual hostname, port, and name values.
The fully-qualified class name of the JDBC driver.
Identity database pool options [database.identity_db.pool_options]
¶
Connection pool settings for the identity database. Tune these based on your database server capacity and load.
[database.identity_db.pool_options]
maxActive =
maxWait =
maxIdle =
minIdle =
testOnBorrow =
validationInterval =
validationQuery = ""
MaxPermSize = ""
The maximum number of active connections in the pool.
The maximum time (in milliseconds) to wait for a connection.
The maximum number of idle connections to keep in the pool.
The minimum number of idle connections maintained in the pool.
Set to true to validate a connection before borrowing it from the pool.
The interval (in milliseconds) between successive connection validation runs.
The SQL query used to validate connections.
The maximum permanent memory size. Applicable to certain JDBC drivers.
Authorization manager [authorization_manager]
¶
Configures the class that manages authorization checks for the Identity Server.
[authorization_manager]
class = "org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager"
The fully-qualified class name of the authorization manager implementation.
Authorization manager properties [authorization_manager.properties]
¶
Fine-tuning properties for the authorization manager.
[authorization_manager.properties]
AdminRoleManagementPermissions = "permission"
AuthorizationCacheEnabled = true
GetAllRolesOfUserEnabled = true
The permission path assigned to admin role management operations.
Set to true to enable caching of authorization decisions.
Set to true to allow retrieving all roles assigned to a user.
Transport [transport]
¶
Top-level toggles for enabling or disabling the HTTP and HTTPS transports.
[transport]
http.enabled = false
https.enabled = true
Set to false to disable the HTTP transport. Disable in production to enforce HTTPS-only access.
Set to true to enable the HTTPS transport.
HTTP transport [transport.http]
¶
Configurations for the HTTP transport connector.
[transport.http]
enabled = false
Set to false to disable the HTTP connector and enforce all traffic over HTTPS.
HTTPS SSL host configuration [transport.https.sslHostConfig.properties]
¶
SSL/TLS protocol version and cipher suite settings for the HTTPS transport.
[transport.https.sslHostConfig.properties]
protocols = "TLSv1.2+TLSv1.3"
ciphers = ""
The TLS protocol versions to enable. Separate multiple values with +. For example, TLSv1.2+TLSv1.3.
A comma-separated list of cipher suites to enable. Leave empty to use the JVM defaults.
Intermediate certificate validation [intermediate_cert_validation]
¶
Enables validation of intermediate CA certificates in client certificate chains.
[intermediate_cert_validation]
enable = false
cert_cns = []
exempt_contexts = []
Set to true to enable intermediate certificate validation.
A list of common names (CNs) of certificates the server accepts.
A list of API endpoint paths exempt from intermediate certificate validation.
Client certificate-based authentication [client_certificate_based_authentication]
¶
Enables authentication using client certificates for API access.
[client_certificate_based_authentication]
enable = false
trusted_issuer = ""
cert_thumbprint = ""
allowed_username = []
allowed_system_user = "admin"
Set to true to enable client certificate-based authentication.
The distinguished name (DN) of the CA that issues trusted client certificates.
The SHA-256 thumbprint of a trusted client certificate.
A list of usernames permitted to authenticate with client certificates.
The system user granted access when using certificate-based authentication.
OAuth endpoints [oauth.endpoints]
¶
Custom URLs for OAuth 2.0 and OIDC consent pages. Override the defaults if you use a custom authentication endpoint.
[oauth.endpoints]
oauth2_consent_page = "${carbon.protocol}://localhost:${carbon.management.port}/authenticationendpoint/oauth2_authz.do"
oidc_consent_page = "${carbon.protocol}://localhost:${carbon.management.port}/authenticationendpoint/oauth2_consent.do"
The URL of the OAuth 2.0 authorization consent page.
The URL of the OIDC consent page.
JWT-secured authorization response mode (JARM) [oauth.jarm]
¶
Enables JWT-Secured Authorization Response Mode (JARM) for OAuth 2.0 authorization responses.
[oauth.jarm]
enable = false
Set to true to enable JARM for OAuth 2.0 authorization responses.
JWT token renewal without revoking existing tokens [oauth.jwt.renew_token_without_revoking_existing]
¶
Allows generating new JWT access tokens without revoking existing ones. Useful for service-to-service scenarios.
[oauth.jwt.renew_token_without_revoking_existing]
enable = false
allowed_grant_types = []
Set to true to allow issuing new JWT tokens without revoking the current active token.
The list of OAuth grant types for which this behavior applies.
Adaptive authentication [authentication.adaptive]
¶
HTTP connection settings for external function calls made during adaptive authentication script execution.
[authentication.adaptive]
http_connections.connection_timeout = 3000
http_connections.read_timeout = 6000
http_connections.request_timeout = 3000
http_connections.request_retry_count = 2
http_function_allowed_domains = []
The timeout (in milliseconds) when establishing a connection to an external endpoint.
The timeout (in milliseconds) when reading a response from an external endpoint.
The maximum time (in milliseconds) allowed for a full HTTP request.
The number of retries when an HTTP request to an external endpoint fails.
A list of domains that adaptive authentication scripts can call using the httpGet() or httpPost() functions.
Session nonce cookie [session.nonce.cookie]
¶
Configures which authenticators bypass nonce cookie validation during passwordless flows.
[session.nonce.cookie]
default_whitelist_authenticators = []
A list of authenticator names excluded from nonce cookie validation. Used for magic link and similar passwordless flows.
User store properties [user_store.properties]
¶
Additional properties for the primary user store.
[user_store.properties]
StoreUserAttributeValueAsUnicode = false
Set to true to store user attribute values as Unicode. Required for Microsoft SQL Server to support special characters.
User store commons [user_store_commons]
¶
Common resilience and retry configurations applied across all user store connections.
[user_store_commons]
enable_circuit_breaker_for_user_stores = false
maxConnectionRetryCount = 2
minConnectionRetryDelayInMilliSeconds = 60000
Set to true to enable the circuit breaker pattern for user store connections. This prevents cascading failures when a user store is unresponsive.
The maximum number of reconnection attempts before the circuit breaker trips.
The minimum delay (in milliseconds) between reconnection attempts.
Clustering [clustering]
¶
Configures cluster membership for high-availability deployments. Each node must specify its hostname and port for inter-node communication.
[clustering]
membership_scheme = "wka"
domain = "wso2.carbon.domain"
local_member_host = "10.0.21.80"
local_member_port = 5701
members = []
The mechanism nodes use to discover each other. Use kubernetes for containerized deployments and aws-ecs for Amazon ECS.
The Hazelcast cluster domain name. Nodes with the same domain form a cluster.
The IP address or hostname of this node, used for cluster communication.
The port this node listens on for cluster communication.
A list of cluster member addresses in host:port format. Used for well-known address (WKA) membership.
Clustering properties [clustering.properties]
¶
Provider-specific properties for the cluster membership scheme, such as Kubernetes, AWS EC2, or Amazon ECS settings.
[clustering.properties]
KUBERNETES_NAMESPACE = "wso2-is"
KUBERNETES_SERVICES = "wso2is-service"
region = "us-east-1"
accessKey = ""
secretKey = ""
clusterName = "ECS-IS-CLUSTER"
hostHeader = "ec2"
vpcCidrBlock = "10.0.*.*"
securityGroup = "security_group_name"
tagKey = "a_tag_key"
tagValue = "a_tag_value"
The Kubernetes namespace where Identity Server pods run.
The name of the Kubernetes service used for pod discovery.
The AWS region where the EC2 instances or ECS cluster runs.
The AWS access key for EC2 or ECS membership discovery.
The AWS secret key for EC2 or ECS membership discovery.
The name of the Amazon ECS cluster.
The header type for ECS host resolution.
The CIDR block of the VPC used to filter EC2 instances for clustering.
The AWS security group name used to identify cluster member EC2 instances.
An EC2 tag key used to identify cluster member instances.
The value of the EC2 tag used to identify cluster member instances.
Application info cache [cache.app_info_cache]
¶
Cache for OAuth application metadata.
[cache.app_info_cache]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Authentication context cache [cache.authentication_context_cache]
¶
Cache for authentication context objects used during the authentication flow.
[cache.authentication_context_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Authentication request cache [cache.authentication_request_cache]
¶
Cache for incoming authentication requests.
[cache.authentication_request_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Authentication result cache [cache.authentication_result_cache]
¶
Cache for authentication results after a successful login.
[cache.authentication_result_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Authorization grant cache [cache.authorization_grant_cache]
¶
Cache for OAuth 2.0 authorization grants.
[cache.authorization_grant_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Framework session context cache [cache.framework_session_context_cache]
¶
Cache for session context objects used by the authentication framework.
[cache.framework_session_context_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
IdP cache by authentication property [cache.idp_cache_by_auth_property]
¶
Cache for looking up identity providers by their authentication properties.
[cache.idp_cache_by_auth_property]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
IdP cache by home realm identifier [cache.idp_cache_by_hri]
¶
Cache for looking up identity providers by home realm identifier (HRI).
[cache.idp_cache_by_hri]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
IdP cache by name [cache.idp_cache_by_name]
¶
Cache for looking up identity providers by their configured name.
[cache.idp_cache_by_name]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
JWKS cache [cache.jwks_cache]
¶
Cache for JSON Web Key Sets (JWKS) fetched from external identity providers.
[cache.jwks_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
OAuth cache [cache.oauth_cache]
¶
Cache for OAuth 2.0 access tokens and related data.
[cache.oauth_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
OAuth scope cache [cache.oauth_scope_cache]
¶
Cache for OAuth 2.0 scope metadata.
[cache.oauth_scope_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
OAuth session data cache [cache.oauth_session_data_cache]
¶
Cache for OAuth session data used during authorization code flows.
[cache.oauth_session_data_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Provisioning connector cache [cache.provisioning_connector_cache]
¶
Cache for outbound provisioning connector configurations.
[cache.provisioning_connector_cache]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Provisioning entity cache [cache.provisioning_entity_cache]
¶
Cache for provisioned entity data during outbound provisioning.
[cache.provisioning_entity_cache]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
SAML SSO participant cache [cache.saml_sso_participant_cache]
¶
Cache for SAML SSO service provider (SP) participant data.
[cache.saml_sso_participant_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
SAML SSO session data cache [cache.saml_sso_session_data_cache]
¶
Cache for SAML SSO session data.
[cache.saml_sso_session_data_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
SAML SSO session index cache [cache.saml_sso_session_index_cache]
¶
Cache for SAML SSO session index mappings.
[cache.saml_sso_session_index_cache]
enable = true
timeout = 300
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Service provider cache [cache.service_provider_cache]
¶
Cache for service provider (application) configurations.
[cache.service_provider_cache]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Service provider cache by ID [cache.service_provider_cache_id]
¶
Cache for looking up service providers by their unique identifier.
[cache.service_provider_cache_id]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Service provider cache by inbound auth [cache.service_provider_cache_inbound_auth]
¶
Cache for looking up service providers by their inbound authentication configuration.
[cache.service_provider_cache_inbound_auth]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Service provider provisioning connector cache [cache.service_provider_provisioning_connector_cache]
¶
Cache for service provider outbound provisioning connector configurations.
[cache.service_provider_provisioning_connector_cache]
enable = true
timeout = 900
capacity = 5000
Set to false to disable this cache.
The time (in seconds) before a cache entry expires.
The maximum number of entries the cache holds.
Pagination [pagination]
¶
Controls the maximum number of users returned per role in list operations.
[pagination]
max_users_list_per_role = 1000
The maximum number of users listed per role in paginated responses.
Carbon health check [carbon_health_check]
¶
Enables the built-in health check endpoint (/api/health-check/v1.0/health) to monitor server and data source health.
[carbon_health_check]
enable = true
Set to true to enable the health check API.
Data source health checker [carbon_health_check.health_checker.data_source_health_checker]
¶
Checks whether configured data sources are reachable and functional.
[carbon_health_check.health_checker.data_source_health_checker]
enable = false
order = "97"
pool_usage_limit_percentage = "20"
Set to true to enable the data source health checker.
The execution order of this checker relative to others. Lower values run first.
The maximum percentage of the connection pool that can be in use before this checker reports an unhealthy status.
Super tenant health checker [carbon_health_check.health_checker.super_tenant_health_checker]
¶
Checks the health of the super tenant's user store connection.
[carbon_health_check.health_checker.super_tenant_health_checker]
enable = false
order = "98"
Set to true to enable the super tenant health checker.
The execution order of this checker relative to others.
JMX monitoring [monitoring.jmx]
¶
Enables JMX (Java Management Extensions) for runtime monitoring and management of server components.
[monitoring.jmx]
rmi_server_start = false
Set to true to start the JMX RMI server, allowing external JMX clients to connect and monitor the server.
OpenTelemetry tracing [tracing.opentelemetry]
¶
Configures OpenTelemetry distributed tracing for monitoring request flows across services.
[tracing.opentelemetry]
ldap.enabled = false
ldap.scope_name = "wso2isldap"
Set to true to enable tracing of LDAP operations.
The tracing scope name used for LDAP spans.
Log management [log_mgt]
¶
Controls log file behavior and formatting for the Identity Server.
[log_mgt]
audit_log.truncate_to_microseconds = false
Set to true to truncate audit log timestamps to microsecond precision.
Log masking [masking_logs]
¶
Enables masking of sensitive data (such as passwords and tokens) in log output.
[masking_logs]
enabled = false
Set to true to enable log masking. Define the patterns to mask under [masking_pattern.properties].
HTTP access log valve [catalina.valves.valve.properties]
¶
Configures the Tomcat extended access log valve for logging HTTP requests.
[catalina.valves.valve.properties]
className = "org.apache.catalina.valves.ExtendedAccessLogValve"
directory = "${carbon.home}/repository/logs"
prefix = "localhost_access_log."
suffix = ".log"
pattern = "%h %l %u %t \"%r\" %s %b"
The fully-qualified class name of the Tomcat access log valve.
The directory where access log files are written.
The filename prefix for access log files.
The filename suffix for access log files.
The log pattern defining which HTTP request attributes to record.
Audit log user claims [audit.log.loggable_user_claim]
¶
Specifies user attribute claims to include in audit log entries for each operation.
[audit.log.loggable_user_claim]
claim1 = "http://wso2.org/claims/identity/accountLocked"
claim2 = "http://wso2.org/claims/role"
The URI of a claim to include in audit log entries. Replace with any valid WSO2 claim URI.
The URI of a second claim to include in audit log entries.
Email sending module [output_adapter.email]
¶
Configures the SMTP settings for outbound email notifications such as account verification and password reset emails.
[output_adapter.email]
hostname = "smtp.gmail.com"
port = 587
from_address = ""
username = ""
password = ""
auth_type = "BASIC"
enable_authentication = true
enable_start_tls = true
signature = ""
The hostname of the SMTP server.
The port of the SMTP server. Common values are 25, 465 (SMTPS), and 587 (STARTTLS).
The email address that appears in the From field of outgoing messages.
The username used to authenticate with the SMTP server.
The password used to authenticate with the SMTP server.
The authentication method for the SMTP connection.
Set to true to require SMTP authentication.
Set to true to upgrade the SMTP connection to TLS using the STARTTLS command.
A signature line appended at the bottom of outgoing email messages.
FIDO [fido]
¶
Configures general FIDO/WebAuthn settings such as the user response timeout for FIDO2 device registration.
[fido]
user_response_timeout = "300000"
The time in milliseconds sent as a hint to the browser for how long to wait for the user to interact with their FIDO2 authenticator during device registration. This timeout is enforced by the browser, not the server, and applies only to FIDO2 device registration (not authentication).
FIDO metadata service [fido.metadata_service]
¶
Enables FIDO2 attestation verification using the FIDO Metadata Service (MDS). Required for enforcing strong authenticator policies.
[fido.metadata_service]
enable = false
mds_endpoints = []
Set to true to fetch and use the FIDO Alliance Metadata Service for attestation validation.
A list of URLs from which the server downloads FIDO MDS metadata blobs.
AI services [ai_services]
¶
Configures the API key for WSO2 AI-powered features such as AI-assisted login flow design.
[ai_services]
key = ""
The subscription key that authenticates requests to the WSO2 AI services API.
Actions [actions]
¶
HTTP connection pool settings for external action endpoints invoked during authentication and provisioning flows.
[actions]
http_client.connection_pool_size = 10
http_client.connection_timeout = 3000
http_client.read_timeout = 6000
http_client.request_timeout = 3000
http_client.retry_count = 1
The maximum number of connections the HTTP client maintains across all external action endpoints.
The timeout (in milliseconds) for establishing a connection to an action endpoint.
The timeout (in milliseconds) for reading a response from an action endpoint.
The maximum time (in milliseconds) allowed for a complete HTTP request to an action endpoint.
The number of times the HTTP client retries a failed request to an action endpoint.
User self-registration [identity_mgt.user_self_registration]
¶
Controls behavior of the user self-registration flow for preferred channel verification.
[identity_mgt.user_self_registration]
enable_account_lock_for_verified_preferred_channel = false
Set to false to skip account locking when a user self-registers with a verified preferred communication channel.
Resource access control [resource.access_control]
¶
Configures access control rules for specific API endpoints, such as requiring authentication or specific scopes.
[resource.access_control]
context = "/api/identity/*"
secured = true
http_method = "all"
permissions = []
scope = []
allowed_auth_handlers = []
The URL context pattern this access control rule applies to.
Set to true to require authentication for requests matching the context.
The HTTP method this rule applies to. Use all to match any method.
A list of permission strings a caller must have to access this resource.
A list of OAuth scopes required to access this resource.
A list of authentication handler names permitted to authenticate requests to this resource.
Security token service (STS) [sts]
¶
Configures the WS-Federation Security Token Service (STS), which issues SAML tokens for WS-Federation web applications.
[sts]
signature_algorithm = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
digest_algorithm = "http://www.w3.org/2001/04/xmlenc#sha256"
The XML signature algorithm used to sign issued SAML tokens.
The digest algorithm used when signing SAML tokens.