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.

Sample configuration
[server]
hostname = "localhost"
node_ip = "127.0.0.1"
base_path = "${carbon.protocol}://${carbon.host}:${carbon.management.port}"
serverDetails = "WSO2 Identity Server"
internal_hostname = "localhost"
clock_skew = "5m"
hostname string Required
Default: localhost
Possible values: localhost, 127.0.0.1, <any-ip-address>, <any-hostname>

The hostname of the machine hosting the Identity Server instance.

node_ip string Required
Default: 127.0.0.1

The IP address of the machine hosting the Identity Server instance.

base_path string
Default: ${carbon.protocol}://${carbon.host}:${carbon.management.port}

The base path URL used to access the server.

serverDetails string
Default: WSO2 Identity Server

A description of the server instance.

internal_hostname string
Default: localhost

The internal hostname used for service-to-service communication within the deployment. Defaults to the value of hostname when not set.

clock_skew string
Default: 5m

The maximum allowed clock skew when validating timestamps in tokens and assertions. Accepts duration values such as 5m or 30s.

Super admin [super_admin]

Configurations for the super admin user of the Identity Server.

Sample configuration
[super_admin]
username = "admin"
password = "admin"
admin_role = "admin"
create_admin_account = False
username string Required
Default: admin

The username of the super admin user.

password string Required
Default: admin

The password of the super admin user. Use environment variables in production environments.

admin_role string
Default: admin

The role name assigned to the super admin user.

create_admin_account boolean
Default: False
Possible values: True, False

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.

Sample configuration
[keystore.primary]
name = "wso2carbon.jks"
password = "wso2carbon"
name string Required
Default: wso2carbon.jks

The filename of the primary keystore.

password string Required
Default: wso2carbon

The password of the primary keystore file.

TLS keystore [keystore.tls]

Configurations for the keystore used for TLS communication.

Sample configuration
[keystore.tls]
alias = "wso2carbon"
key_password = "wso2carbon"
password = "wso2carbon"
alias string Required
Default: wso2carbon

The alias of the TLS key entry inside the keystore.

key_password string Required
Default: wso2carbon

The password for the TLS key entry.

password string Required
Default: wso2carbon

The password for the TLS keystore file.

Truststore [truststore]

Configurations for the truststore, which validates certificates from external systems.

Sample configuration
[truststore]
password = "wso2carbon"
password string Required
Default: wso2carbon

The password for the truststore file.

Shared database [database.shared_db]

Configurations for the shared database that stores registry and governance data.

Sample configuration
[database.shared_db]
type = "mysql"
hostname = "localhost"
port = 3306
name = "regdb"
username = "regadmin"
password = "regadmin"
type string Required
Default: mysql
Possible values: mysql, mssql, oracle, postgresql, db2, h2

The type of the database.

hostname string Required
Default: localhost

The hostname of the database server.

port integer Required
Default: 3306

The port on which the database server listens.

name string Required
Default: regdb

The name of the shared database.

username string Required
Default: regadmin

The username for the database connection.

password string Required
Default: regadmin

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.

Sample configuration
[database.shared_db.pool_options]
maxActive = 80
maxWait = 360000
minIdle = 5
testOnBorrow = True
validationInterval = 30000
validationQuery = "SELECT 1"
defaultAutoCommit = False
commitOnReturn = True
maxActive integer
Default: 80

The maximum number of active connections in the pool.

maxWait integer
Default: 360000

The maximum time (in milliseconds) to wait for a connection before throwing an error.

minIdle integer
Default: 5

The minimum number of idle connections maintained in the pool.

testOnBorrow boolean
Default: True
Possible values: True, False

Set to true to validate a connection before borrowing it from the pool.

validationInterval integer
Default: 30000

The interval (in milliseconds) between successive connection validation runs.

validationQuery string
Default: SELECT 1

The SQL query used to validate connections.

defaultAutoCommit boolean
Default: False
Possible values: True, False

Set to true to enable auto-commit on borrowed connections.

commitOnReturn boolean
Default: True
Possible values: True, False

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.

Sample configuration
[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"
type string Required
Default: mysql
Possible values: mysql, mssql, oracle, postgresql, db2, h2

The type of the database.

hostname string Required
Default: localhost

The hostname of the database server.

port integer Required
Default: 3306

The port on which the database server listens.

name string Required
Default: regdb

The name of the identity database.

username string Required
Default: regadmin

The username for the database connection.

password string Required
Default: regadmin

The password for the database connection.

url string
Default: jdbc:mysql://DB_HOST:3306/WSO2_IDENTITY_DB

A full JDBC connection URL. When set, this overrides the individual hostname, port, and name values.

driver string
Default: com.mysql.cj.jdbc.Driver

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.

Sample configuration
[database.identity_db.pool_options]
maxActive = 50
maxWait = 60000
maxIdle = 8
minIdle = 0
testOnBorrow = True
validationInterval = 30000
validationQuery = "SELECT 1"
defaultAutoCommit = True
maxActive integer
Default: 50

The maximum number of active connections in the pool.

maxWait integer
Default: 60000

The maximum time (in milliseconds) to wait for a connection.

maxIdle integer
Default: 8

The maximum number of idle connections to keep in the pool.

minIdle integer
Default: 0

The minimum number of idle connections maintained in the pool.

testOnBorrow boolean
Default: True
Possible values: True, False

Set to true to validate a connection before borrowing it from the pool.

validationInterval integer
Default: 30000

The interval (in milliseconds) between successive connection validation runs.

validationQuery string
Default: SELECT 1

The SQL query used to validate connections.

defaultAutoCommit boolean
Default: True
Possible values: True, False

Set to true to enable auto-commit for connections borrowed from the pool.

Session timeout [session.timeout]

Controls how long user sessions remain valid before the server requires re-authentication.

Sample configuration
[session.timeout]
idle_session_timeout = "15m"
remember_me_session_timeout = "14d"
extend_remember_me_session_timeout_on_auth = True
enable_maximum_session_timeout = False
maximum_session_timeout = "30d"
idle_session_timeout string
Default: 15m

The duration after which an inactive session expires. Accepts duration values such as 15m or 1h.

remember_me_session_timeout string
Default: 14d

The duration a Remember Me session remains valid. Accepts duration values such as 14d or 30d.

extend_remember_me_session_timeout_on_auth boolean
Default: True
Possible values: True, False

Set to true to reset the Remember Me session expiry each time the user authenticates.

enable_maximum_session_timeout boolean
Default: False
Possible values: True, False

Set to true to enforce an absolute maximum session lifetime, regardless of activity.

maximum_session_timeout string
Default: 30d

The absolute maximum duration a session can remain active. Takes effect only when enable_maximum_session_timeout is true.

Session data persistence [session_data.persistence]

Controls whether authentication session data is persisted to the database, enabling session recovery after server restarts.

Sample configuration
[session_data.persistence]
enable_persistence = True
persistence_pool_size = 0
persist_temporary_data = True
enable_user_session_mapping = True
enable_persistence boolean
Default: True
Possible values: True, False

Set to true to persist session data to the database.

persistence_pool_size integer
Default: 0

The number of threads used for asynchronous session data persistence. Set to 0 to use synchronous persistence.

persist_temporary_data boolean
Default: True
Possible values: True, False

Set to true to persist temporary session data used during intermediate authentication steps.

enable_user_session_mapping boolean
Default: True
Possible values: True, False

Set to true to store a mapping between users and their active sessions, enabling per-user session management.

Session data cleanup [session_data.cleanup]

Controls the scheduled cleanup of expired and unused session data from the database.

Sample configuration
[session_data.cleanup]
enable_expired_data_cleanup = False
expire_session_data_after = "14d"
clean_expired_session_data_every = "1d"
clean_expired_session_data_in_chunks_of = 8192
clean_logged_out_sessions_at_immediate_cycle = False
enable_pre_session_data_cleanup = True
enable_periodic_pre_session_data_cleanup = True
expire_pre_session_data_after = "40m"
pre_session_data_cleanup_thread_pool_size = 20
enable_expired_data_cleanup boolean
Default: False
Possible values: True, False

Set to true to enable periodic deletion of expired session records from the database.

expire_session_data_after string
Default: 14d

The age after which expired session data becomes eligible for deletion. Defaults to the Remember Me session timeout.

clean_expired_session_data_every string
Default: 1d

How often the cleanup task runs to remove expired session records.

clean_expired_session_data_in_chunks_of integer
Default: 8192

The number of session records deleted per cleanup batch. Tune this value to reduce database load during peak hours.

clean_logged_out_sessions_at_immediate_cycle boolean
Default: False
Possible values: True, False

Set to true to delete session data immediately on logout, rather than waiting for the next scheduled cleanup cycle.

enable_pre_session_data_cleanup boolean
Default: True
Possible values: True, False

Set to true to enable cleanup of session data generated before the final authentication step completes.

enable_periodic_pre_session_data_cleanup boolean
Default: True
Possible values: True, False

Set to true to run pre-session data cleanup on a scheduled basis.

expire_pre_session_data_after string
Default: 40m

The age after which incomplete pre-session data is eligible for cleanup.

pre_session_data_cleanup_thread_pool_size integer
Default: 20

The number of threads used for pre-session data cleanup.

Authorization manager [authorization_manager]

Configures the class that manages authorization checks for the Identity Server.

Sample configuration
[authorization_manager]
class = "org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager"
class string Required
Default: 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.

Sample configuration
[authorization_manager.properties]
AdminRoleManagementPermissions = "permission"
AuthorizationCacheEnabled = True
GetAllRolesOfUserEnabled = True
AdminRoleManagementPermissions string
Default: permission

The permission path assigned to admin role management operations.

AuthorizationCacheEnabled boolean
Default: True
Possible values: True, False

Set to true to enable caching of authorization decisions.

GetAllRolesOfUserEnabled boolean
Default: True
Possible values: True, False

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.

Sample configuration
[transport]
http.enabled = False
https.enabled = True
http.enabled boolean
Default: False
Possible values: True, False

Set to false to disable the HTTP transport. Disable in production to enforce HTTPS-only access.

https.enabled boolean
Default: True
Possible values: True, False

Set to true to enable the HTTPS transport.

HTTP transport [transport.http]

Configurations for the HTTP transport connector.

Sample configuration
[transport.http]
enabled = False
enabled boolean
Default: False
Possible values: True, 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.

Sample configuration
[transport.https.sslHostConfig.properties]
protocols = "TLSv1.2+TLSv1.3"
ciphers = ""
protocols string
Default: TLSv1.2+TLSv1.3

The TLS protocol versions to enable. Separate multiple values with +. For example, TLSv1.2+TLSv1.3.

ciphers string
Default:

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.

Sample configuration
[intermediate_cert_validation]
enable = False
cert_cns = []
exempt_contexts = []
enable boolean
Default: False
Possible values: True, False

Set to true to enable intermediate certificate validation.

cert_cns array
Default: []

A list of common names (CNs) of certificates the server accepts.

exempt_contexts array
Default: []

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.

Sample configuration
[client_certificate_based_authentication]
enable = False
trusted_issuer = ""
cert_thumbprint = ""
allowed_username = []
allowed_system_user = "admin"
enable boolean
Default: False
Possible values: True, False

Set to true to enable client certificate-based authentication.

trusted_issuer string
Default:

The distinguished name (DN) of the CA that issues trusted client certificates.

cert_thumbprint string
Default:

The SHA-256 thumbprint of a trusted client certificate.

allowed_username array
Default: []

A list of usernames permitted to authenticate with client certificates.

allowed_system_user string
Default: admin

The system user granted access when using certificate-based authentication.

OAuth endpoints [oauth.endpoints]

Custom URLs for OAuth 2.0 and OIDC endpoints. Override these defaults when the Identity Server is deployed behind a reverse proxy or when custom paths are required.

Sample configuration
[oauth.endpoints]
oauth2_authz_url = "${server.base_path}/oauth2/authorize"
oauth2_token_url = "${server.base_path}/oauth2/token"
oauth2_revoke_url = "${server.base_path}/oauth2/revoke"
oauth2_introspect_url = "${server.base_path}/oauth2/introspect"
oauth2_user_info_url = "${server.base_path}/oauth2/userinfo"
oauth2_jwks_url = "${server.base_path}/oauth2/jwks"
oauth2_par_url = "${server.base_path}/oauth2/par"
oauth2_device_authz_url = "${server.base_path}/oauth2/device_authorize"
oauth2_dcr_url = "${server.base_path}/api/identity/oauth2/dcr/v1.1/register"
oidc_check_session_url = "${server.base_path}/oidc/checksession"
oidc_logout_url = "${server.base_path}/oidc/logout"
oidc_discovery_url = "${server.base_path}/oauth2/oidcdiscovery"
oauth2_consent_page = "${server.base_path}/authenticationendpoint/oauth2_authz.do"
oidc_consent_page = "${server.base_path}/authenticationendpoint/oauth2_consent.do"
oidc_logout_consent_page = "${server.base_path}/authenticationendpoint/oauth2_logout_consent.do"
oauth2_authz_url string
Default: ${server.base_path}/oauth2/authorize

The OAuth 2.0 authorization endpoint URL.

oauth2_token_url string
Default: ${server.base_path}/oauth2/token

The OAuth 2.0 token endpoint URL.

oauth2_revoke_url string
Default: ${server.base_path}/oauth2/revoke

The OAuth 2.0 token revocation endpoint URL.

oauth2_introspect_url string
Default: ${server.base_path}/oauth2/introspect

The OAuth 2.0 token introspection endpoint URL.

oauth2_user_info_url string
Default: ${server.base_path}/oauth2/userinfo

The OIDC UserInfo endpoint URL.

oauth2_jwks_url string
Default: ${server.base_path}/oauth2/jwks

The JSON Web Key Set (JWKS) endpoint URL. Clients use this to retrieve public keys for token verification.

oauth2_par_url string
Default: ${server.base_path}/oauth2/par

The Pushed Authorization Request (PAR) endpoint URL.

oauth2_device_authz_url string
Default: ${server.base_path}/oauth2/device_authorize

The Device Authorization endpoint URL for the OAuth 2.0 device flow.

oauth2_dcr_url string
Default: ${server.base_path}/api/identity/oauth2/dcr/v1.1/register

The Dynamic Client Registration (DCR) endpoint URL.

oidc_check_session_url string
Default: ${server.base_path}/oidc/checksession

The OIDC session management check session endpoint URL.

oidc_logout_url string
Default: ${server.base_path}/oidc/logout

The OIDC RP-initiated logout endpoint URL.

oidc_discovery_url string
Default: ${server.base_path}/oauth2/oidcdiscovery

The OIDC discovery endpoint URL. Returns the OpenID Provider configuration document.

oauth2_consent_page string
Default: ${server.base_path}/authenticationendpoint/oauth2_authz.do

The URL of the OAuth 2.0 authorization consent page.

oidc_consent_page string
Default: ${server.base_path}/authenticationendpoint/oauth2_consent.do

The URL of the OIDC consent page.

oidc_logout_consent_page string
Default: ${server.base_path}/authenticationendpoint/oauth2_logout_consent.do

The URL of the OIDC logout consent page displayed before completing single logout.

JWT-secured authorization response mode (JARM) [oauth.jarm]

Enables JWT-Secured Authorization Response Mode (JARM) for OAuth 2.0 authorization responses. JARM wraps the authorization response parameters in a signed JWT.

Sample configuration
[oauth.jarm]
enable = True
jwt.enable = True
query_jwt.enable = True
fragment_jwt.enable = True
form_post_jwt.enable = True
jarm_response_jwt_validity = 600
enable boolean
Default: True
Possible values: True, False

Set to true to enable JARM for OAuth 2.0 authorization responses.

jwt.enable boolean
Default: True
Possible values: True, False

Set to true to enable the jwt response mode.

query_jwt.enable boolean
Default: True
Possible values: True, False

Set to true to enable the query.jwt response mode.

fragment_jwt.enable boolean
Default: True
Possible values: True, False

Set to true to enable the fragment.jwt response mode.

form_post_jwt.enable boolean
Default: True
Possible values: True, False

Set to true to enable the form_post.jwt response mode.

jarm_response_jwt_validity integer
Default: 600

The validity period (in seconds) of the JARM response JWT.

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.

Sample configuration
[oauth.jwt.renew_token_without_revoking_existing]
enable = False
allowed_grant_types = []
enable boolean
Default: False
Possible values: True, False

Set to true to allow issuing new JWT tokens without revoking the current active token.

allowed_grant_types array
Default: []

The list of OAuth grant types for which this behavior applies.

OAuth token validation [oauth.token_validation]

Configures the default validity periods for OAuth 2.0 tokens and authorization codes. Applications can override these per-application in the Console.

Sample configuration
[oauth.token_validation]
authorization_code_validity = "5m"
app_access_token_validity = "1h"
user_access_token_validity = "1h"
refresh_token_validity = "1d"
authorization_code_validity string
Default: 5m

The validity period of an OAuth 2.0 authorization code. Accepts duration values such as 5m or 10m.

app_access_token_validity string
Default: 1h

The default validity period for application-level (client credentials) access tokens.

user_access_token_validity string
Default: 1h

The default validity period for user-level access tokens.

refresh_token_validity string
Default: 1d

The default validity period for refresh tokens.

OAuth token cleanup [oauth.token_cleanup]

Configures scheduled cleanup of expired and revoked OAuth tokens from the database.

Sample configuration
[oauth.token_cleanup]
enable = True
retain_access_tokens_for_auditing = False
enable boolean
Default: True
Possible values: True, False

Set to true to enable periodic deletion of expired OAuth tokens.

retain_access_tokens_for_auditing boolean
Default: False
Possible values: True, False

Set to true to retain expired access tokens for audit purposes instead of deleting them.

OAuth token renewal [oauth.token_renewal]

Controls how the server handles token renewal for refresh grants and access token reuse.

Sample configuration
[oauth.token_renewal]
renew_refresh_token = True
extend_refresh_token_expiry_time_on_renewal = True
renew_access_token_per_request = False
validate_authenticated_user_for_refresh_grant = False
renew_refresh_token boolean
Default: True
Possible values: True, False

Set to true to issue a new refresh token each time the refresh grant is used.

extend_refresh_token_expiry_time_on_renewal boolean
Default: True
Possible values: True, False

Set to true to reset the refresh token expiry each time the refresh token is renewed.

renew_access_token_per_request boolean
Default: False
Possible values: True, False

Set to true to issue a new access token for every token request, even if a valid token exists. Disable this to allow token reuse within the validity window.

validate_authenticated_user_for_refresh_grant boolean
Default: False
Possible values: True, False

Set to true to verify that the user associated with a refresh token still exists and is active before issuing a new access token.

OAuth token persistence [oauth.token_persistence]

Controls whether OAuth tokens are persisted to the database.

Sample configuration
[oauth.token_persistence]
enable = True
enable boolean
Default: True
Possible values: True, False

Set to false to disable token persistence. Only suitable for deployments using stateless JWT tokens.

OAuth token and secret hashing [oauth.hash_tokens_and_secrets]

Configures whether OAuth access tokens and client secrets are stored as hashed values in the database.

Sample configuration
[oauth.hash_tokens_and_secrets]
enable = False
algorithm = "SHA-256"
enable boolean
Default: False
Possible values: True, False

Set to true to store tokens and client secrets as hashed values. Once enabled, existing plain-text tokens become invalid.

algorithm string
Default: SHA-256

The hash algorithm used when hashing tokens and secrets.

OAuth token introspection [oauth.introspect]

Configures cross-tenant and cross-sub-organization behavior for the token introspection endpoint.

Sample configuration
[oauth.introspect]
allow_cross_tenant = False
allow_cross_sub_org = False
allow_cross_tenant boolean
Default: False
Possible values: True, False

Set to true to allow introspection of tokens issued by other tenants.

allow_cross_sub_org boolean
Default: False
Possible values: True, False

Set to true to allow introspection of tokens issued by sub-organizations.

Pushed authorization requests (PAR) [oauth.par]

Configures the Pushed Authorization Request (PAR) endpoint. PAR allows clients to push authorization parameters to the server before initiating the authorization flow, improving security by keeping parameters out of browser URLs.

Sample configuration
[oauth.par]
expiry_time = "60s"
expiry_time string
Default: 60s

The validity period of a pushed authorization request URI. After this period, the request_uri can no longer be used to initiate an authorization flow.

JWKS endpoint [oauth.jwks_endpoint]

Configures the behavior of the JWKS endpoint used to publish public keys for token verification.

Sample configuration
[oauth.jwks_endpoint]
enable = True
enforce_certificate_expiry_time_validity = True
connection_timeout = "1s"
read_timeout = "1s"
size_limit_bytes = 51200
enable boolean
Default: True
Possible values: True, False

Set to false to disable the JWKS endpoint.

enforce_certificate_expiry_time_validity boolean
Default: True
Possible values: True, False

Set to true to exclude expired certificates from the JWKS response.

connection_timeout string
Default: 1s

The timeout for establishing a connection when fetching a remote JWKS document.

read_timeout string
Default: 1s

The timeout for reading the response when fetching a remote JWKS document.

size_limit_bytes integer
Default: 51200

The maximum size (in bytes) of a remote JWKS response the server accepts.

MTLS alias endpoints [oauth.mtls_aliases]

Configures Mutual TLS (MTLS) alias endpoints. When enabled, the OIDC discovery document includes separate MTLS-bound endpoint URLs for token binding.

Sample configuration
[oauth.mtls_aliases]
enabled = False
hostname = "$ref{server.hostname}"
enabled boolean
Default: False
Possible values: True, False

Set to true to enable MTLS token endpoint aliases.

hostname string
Default: $ref{server.hostname}

The hostname exposed as the MTLS token endpoint alias in the OIDC discovery document.

Dynamic Client Registration (DCR) [oauth.dcr]

Configures the behavior of the OAuth 2.0 Dynamic Client Registration endpoint.

Sample configuration
[oauth.dcr]
authentication_required = True
mandate_ssa = False
enable_fapi_enforcement = False
authentication_required boolean
Default: True
Possible values: True, False

Set to false to allow unauthenticated client registration requests. Authentication is required by default to prevent unauthorized registrations.

mandate_ssa boolean
Default: False
Possible values: True, False

Set to true to require a Software Statement Assertion (SSA) in all client registration requests.

enable_fapi_enforcement boolean
Default: False
Possible values: True, False

Set to true to enforce FAPI 1.0 Advanced profile requirements for dynamic client registration.

Authorization code grant [oauth.grant_type.authorization_code]

Configures the OAuth 2.0 authorization code grant type.

Sample configuration
[oauth.grant_type.authorization_code]
enable = True
allow_public_client = True
enable boolean
Default: True
Possible values: True, False

Set to false to disable the authorization code grant type.

allow_public_client boolean
Default: True
Possible values: True, False

Set to true to allow public clients (without client secrets) to use the authorization code grant.

Password grant [oauth.grant_type.password]

Configures the OAuth 2.0 resource owner password credentials grant type. This grant type is deprecated in OAuth 2.1 and should not be enabled for new integrations.

Sample configuration
[oauth.grant_type.password]
enable = True
allow_public_client = True
enable boolean
Default: True
Possible values: True, False

Set to false to disable the password grant type.

allow_public_client boolean
Default: True
Possible values: True, False

Set to true to allow public clients to use the password grant.

Client credentials grant [oauth.grant_type.client_credentials]

Configures the OAuth 2.0 client credentials grant type, used for machine-to-machine authentication.

Sample configuration
[oauth.grant_type.client_credentials]
enable = True
allow_refresh_tokens = False
allow_id_token = False
skip_oidc_claims = True
enable boolean
Default: True
Possible values: True, False

Set to false to disable the client credentials grant type.

allow_refresh_tokens boolean
Default: False
Possible values: True, False

Set to true to allow issuing refresh tokens for client credentials grants.

allow_id_token boolean
Default: False
Possible values: True, False

Set to true to include an ID token in the client credentials grant response.

skip_oidc_claims boolean
Default: True
Possible values: True, False

Set to false to include OIDC claims in client credentials grant responses. OIDC claims are skipped by default for client credentials grants.

Refresh token grant [oauth.grant_type.refresh_token]

Configures the OAuth 2.0 refresh token grant type.

Sample configuration
[oauth.grant_type.refresh_token]
enable = True
allow_public_client = True
enable boolean
Default: True
Possible values: True, False

Set to false to disable the refresh token grant type.

allow_public_client boolean
Default: True
Possible values: True, False

Set to true to allow public clients to use the refresh token grant.

Device authorization grant [oauth.grant_type.device_code]

Configures the OAuth 2.0 device authorization grant for devices that cannot display a browser, such as smart TVs and CLI tools.

Sample configuration
[oauth.grant_type.device_code]
enable = True
key_length = 6
expiry_time = "10m"
polling_interval = "5s"
enable boolean
Default: True
Possible values: True, False

Set to false to disable the device authorization grant type.

key_length integer
Default: 6

The number of characters in the user code generated during device authorization.

expiry_time string
Default: 10m

The validity period of a device code before it expires.

polling_interval string
Default: 5s

The minimum interval the device client must wait between polling requests to the token endpoint.

JWT bearer grant [oauth.grant_type.jwt_bearer]

Configures the JWT Bearer grant type used to exchange a third-party JWT assertion for an access token.

Sample configuration
[oauth.grant_type.jwt_bearer]
enable = True
enable_iat_validation = True
iat_validity_period = 30
enable boolean
Default: True
Possible values: True, False

Set to false to disable the JWT bearer grant type.

enable_iat_validation boolean
Default: True
Possible values: True, False

Set to true to validate the iat (issued at) claim in the JWT assertion.

iat_validity_period integer
Default: 30

The maximum age (in minutes) of a JWT assertion, measured from the iat claim. Assertions older than this period are rejected.

OIDC ID token [oauth.oidc.id_token]

Configures the ID token issued during OIDC authentication flows.

Sample configuration
[oauth.oidc.id_token]
signature_algorithm = "SHA256withRSA"
validity = "1h"
use_entityid_as_issuer = False
signature_algorithm string
Default: SHA256withRSA

The algorithm used to sign ID tokens. Use SHA256withRSA (RS256) or PS256 for FAPI-compliant deployments.

validity string
Default: 1h

The validity period of the ID token.

use_entityid_as_issuer boolean
Default: False
Possible values: True, False

Set to true to use the entity ID as the iss claim in ID tokens instead of the token endpoint URL.

OIDC FAPI profile [oauth.oidc.fapi]

Configures Financial-grade API (FAPI) security profiles for OIDC authorization flows.

Sample configuration
[oauth.oidc.fapi]
enable_security_profile = False
enable_ciba_profile = False
allowed_client_authentication_methods = [private_key_jwt, tls_client_auth]
allowed_signature_algorithms = [PS256, ES256]
enable_security_profile boolean
Default: False
Possible values: True, False

Set to true to enforce FAPI 1.0 Advanced security requirements for all authorization flows.

enable_ciba_profile boolean
Default: False
Possible values: True, False

Set to true to enforce FAPI CIBA profile requirements.

allowed_client_authentication_methods array
Default: [private_key_jwt, tls_client_auth]

The client authentication methods allowed for FAPI-compliant applications.

allowed_signature_algorithms array
Default: [PS256, ES256]

The JWT signature algorithms allowed for FAPI-compliant applications.

OIDC back-channel logout sender [oauth.oidc.logout_request_sender]

Configures the thread pool used to send back-channel logout notifications to registered applications when a user logs out.

Sample configuration
[oauth.oidc.logout_request_sender]
pool_size = 20
work_queue_size = 1000
keep_alive_time = 60000
http_connect_timeout = 10000
http_socket_timeout = 20000
pool_size integer
Default: 20

The number of threads handling back-channel logout notifications.

work_queue_size integer
Default: 1000

The maximum number of pending logout notifications queued before new requests are rejected.

keep_alive_time integer
Default: 60000

The time (in milliseconds) idle threads are kept alive before being terminated.

http_connect_timeout integer
Default: 10000

The HTTP connection timeout (in milliseconds) for back-channel logout requests.

http_socket_timeout integer
Default: 20000

The HTTP socket read timeout (in milliseconds) when waiting for back-channel logout responses.

Adaptive authentication [authentication.adaptive]

HTTP connection settings for external function calls made during adaptive authentication script execution.

Sample configuration
[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 = []
http_connections.connection_timeout integer
Default: 3000

The timeout (in milliseconds) when establishing a connection to an external endpoint.

http_connections.read_timeout integer
Default: 6000

The timeout (in milliseconds) when reading a response from an external endpoint.

http_connections.request_timeout integer
Default: 3000

The maximum time (in milliseconds) allowed for a full HTTP request.

http_connections.request_retry_count integer
Default: 2

The number of retries when an HTTP request to an external endpoint fails.

http_function_allowed_domains array
Default: []

A list of domains that adaptive authentication scripts can call using the httpGet() or httpPost() functions.

Configures which authenticators bypass nonce cookie validation during passwordless flows.

Sample configuration
[session.nonce.cookie]
default_whitelist_authenticators = []
default_whitelist_authenticators array
Default: []

A list of authenticator names excluded from nonce cookie validation. Used for magic link and similar passwordless flows.

Controls whether users are prompted to consent to attribute sharing during the login flow.

Sample configuration
[authentication.consent]
prompt = True
subject.prompt = True
prompt boolean
Default: True
Possible values: True, False

Set to true to display an attribute consent screen during authentication when claims are shared with applications.

subject.prompt boolean
Default: True
Possible values: True, False

Set to true to prompt the user to approve the subject identifier when logging in for the first time.

Just-in-time (JIT) provisioning [authentication.jit_provisioning]

Configures just-in-time user provisioning for federated identity providers. When enabled, users authenticating through a federated IdP are provisioned locally on first login.

Sample configuration
[authentication.jit_provisioning]
fail_authn_on_provision_failure = False
skip_username_pattern_validation = False
autofill_username_field_with_subject_attribute = True
fail_authn_on_provision_failure boolean
Default: False
Possible values: True, False

Set to true to block authentication if JIT provisioning fails.

skip_username_pattern_validation boolean
Default: False
Possible values: True, False

Set to true to skip username validation against the configured regex pattern during JIT provisioning.

autofill_username_field_with_subject_attribute boolean
Default: True
Possible values: True, False

Set to true to pre-fill the username field with the subject attribute received from the federated IdP.

User store properties [user_store.properties]

Additional properties for the primary user store.

Sample configuration
[user_store.properties]
StoreUserAttributeValueAsUnicode = False
StoreUserAttributeValueAsUnicode boolean
Default: False
Possible values: True, 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.

Sample configuration
[user_store_commons]
enable_circuit_breaker_for_user_stores = False
maxConnectionRetryCount = 2
minConnectionRetryDelayInMilliSeconds = 60000
enable_circuit_breaker_for_user_stores boolean
Default: False
Possible values: True, False

Set to true to enable the circuit breaker pattern for user store connections. This prevents cascading failures when a user store is unresponsive.

maxConnectionRetryCount integer
Default: 2

The maximum number of reconnection attempts before the circuit breaker trips.

minConnectionRetryDelayInMilliSeconds integer
Default: 60000

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.

Sample configuration
[clustering]
membership_scheme = "wka"
domain = "wso2.carbon.domain"
local_member_host = "10.0.21.80"
local_member_port = 5701
members = []
membership_scheme string Required
Default: wka
Possible values: wka, multicast, kubernetes, aws, aws-ecs

The mechanism nodes use to discover each other. Use kubernetes for containerized deployments and aws-ecs for Amazon ECS.

domain string
Default: wso2.carbon.domain

The Hazelcast cluster domain name. Nodes with the same domain form a cluster.

local_member_host string Required
Default: 10.0.21.80

The IP address or hostname of this node, used for cluster communication.

local_member_port integer Required
Default: 5701

The port this node listens on for cluster communication.

members array
Default: []

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.

Sample configuration
[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"
KUBERNETES_NAMESPACE string
Default: wso2-is

The Kubernetes namespace where Identity Server pods run.

KUBERNETES_SERVICES string
Default: wso2is-service

The name of the Kubernetes service used for pod discovery.

region string
Default: us-east-1

The AWS region where the EC2 instances or ECS cluster runs.

accessKey string
Default:

The AWS access key for EC2 or ECS membership discovery.

secretKey string
Default:

The AWS secret key for EC2 or ECS membership discovery.

clusterName string
Default: ECS-IS-CLUSTER

The name of the Amazon ECS cluster.

hostHeader string
Default: ec2

The header type for ECS host resolution.

vpcCidrBlock string
Default: 10.0.*.*

The CIDR block of the VPC used to filter EC2 instances for clustering.

securityGroup string
Default: security_group_name

The AWS security group name used to identify cluster member EC2 instances.

tagKey string
Default: a_tag_key

An EC2 tag key used to identify cluster member instances.

tagValue string
Default: a_tag_value

The value of the EC2 tag used to identify cluster member instances.

Application info cache [cache.app_info_cache]

Cache for OAuth application metadata.

Sample configuration
[cache.app_info_cache]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.authentication_context_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

Authentication request cache [cache.authentication_request_cache]

Cache for incoming authentication requests.

Sample configuration
[cache.authentication_request_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

Authentication result cache [cache.authentication_result_cache]

Cache for authentication results after a successful login.

Sample configuration
[cache.authentication_result_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

Authorization grant cache [cache.authorization_grant_cache]

Cache for OAuth 2.0 authorization grants.

Sample configuration
[cache.authorization_grant_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.framework_session_context_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.idp_cache_by_auth_property]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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).

Sample configuration
[cache.idp_cache_by_hri]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.idp_cache_by_name]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.jwks_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

OAuth cache [cache.oauth_cache]

Cache for OAuth 2.0 access tokens and related data.

Sample configuration
[cache.oauth_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

OAuth scope cache [cache.oauth_scope_cache]

Cache for OAuth 2.0 scope metadata.

Sample configuration
[cache.oauth_scope_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.oauth_session_data_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

Provisioning connector cache [cache.provisioning_connector_cache]

Cache for outbound provisioning connector configurations.

Sample configuration
[cache.provisioning_connector_cache]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

Provisioning entity cache [cache.provisioning_entity_cache]

Cache for provisioned entity data during outbound provisioning.

Sample configuration
[cache.provisioning_entity_cache]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.saml_sso_participant_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.saml_sso_session_data_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.saml_sso_session_index_cache]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

Service provider cache [cache.service_provider_cache]

Cache for service provider (application) configurations.

Sample configuration
[cache.service_provider_cache]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.service_provider_cache_id]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.service_provider_cache_inbound_auth]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

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.

Sample configuration
[cache.service_provider_provisioning_connector_cache]
enable = True
timeout = 900
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

Private key JWT cache [cache.private_key_jwt]

Cache used to prevent replay attacks by storing recently seen private key JWT assertions.

Sample configuration
[cache.private_key_jwt]
enable = True
timeout = 300
capacity = 5000
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 300

The time (in seconds) before a cache entry expires.

capacity integer
Default: 5000

The maximum number of entries the cache holds.

SAML certificate cache [cache.saml_cert_cache]

Cache for SAML service provider signing certificates.

Sample configuration
[cache.saml_cert_cache]
enable = True
timeout = 900
capacity = 100
enable boolean
Default: True
Possible values: True, False

Set to false to disable this cache.

timeout integer
Default: 900

The time (in seconds) before a cache entry expires.

capacity integer
Default: 100

The maximum number of entries the cache holds.

Pagination [pagination]

Controls the default and maximum number of items returned per page in list operations.

Sample configuration
[pagination]
max_items_per_page = 100
default_items_per_page = 15
max_users_list_per_role = 1000
max_items_per_page integer
Default: 100

The maximum number of items returned per page in any paginated API response. Requests for a larger page size are capped at this value.

default_items_per_page integer
Default: 15

The default number of items per page when no page size is specified in the request.

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

Sample configuration
[carbon_health_check]
enable = True
enable boolean
Default: True
Possible values: True, False

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.

Sample configuration
[carbon_health_check.health_checker.data_source_health_checker]
enable = False
order = "97"
pool_usage_limit_percentage = "20"
enable boolean
Default: False
Possible values: True, False

Set to true to enable the data source health checker.

order string
Default: 97

The execution order of this checker relative to others. Lower values run first.

pool_usage_limit_percentage string
Default: 20

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.

Sample configuration
[carbon_health_check.health_checker.super_tenant_health_checker]
enable = False
order = "98"
enable boolean
Default: False
Possible values: True, False

Set to true to enable the super tenant health checker.

order string
Default: 98

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.

Sample configuration
[monitoring.jmx]
rmi_server_start = False
rmi_server_start boolean
Default: False
Possible values: True, 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.

Sample configuration
[tracing.opentelemetry]
ldap.enabled = False
ldap.scope_name = "wso2isldap"
ldap.enabled boolean
Default: False
Possible values: True, False

Set to true to enable tracing of LDAP operations.

ldap.scope_name string
Default: wso2isldap

The tracing scope name used for LDAP spans.

Log management [log_mgt]

Controls log file behavior and formatting for the Identity Server.

Sample configuration
[log_mgt]
audit_log.truncate_to_microseconds = False
audit_log.truncate_to_microseconds boolean
Default: False
Possible values: True, 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.

Sample configuration
[masking_logs]
enabled = False
enabled boolean
Default: False
Possible values: True, 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.

Sample configuration
[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"
className string Required
Default: org.apache.catalina.valves.ExtendedAccessLogValve

The fully-qualified class name of the Tomcat access log valve.

directory string
Default: ${carbon.home}/repository/logs

The directory where access log files are written.

prefix string
Default: localhost_access_log.

The filename prefix for access log files.

suffix string
Default: .log

The filename suffix for access log files.

pattern string
Default: %h %l %u %t "%r" %s %b

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.

Sample configuration
[audit.log.loggable_user_claim]
claim1 = "http://wso2.org/claims/identity/accountLocked"
claim2 = "http://wso2.org/claims/role"
claim1 string
Default: http://wso2.org/claims/identity/accountLocked

The URI of a claim to include in audit log entries. Replace with any valid WSO2 claim URI.

claim2 string
Default: http://wso2.org/claims/role

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.

Sample configuration
[output_adapter.email]
hostname = "smtp.gmail.com"
port = 587
from_address = ""
username = ""
password = ""
auth_type = "BASIC"
enable_authentication = True
enable_start_tls = True
signature = ""
hostname string Required
Default: smtp.gmail.com

The hostname of the SMTP server.

port integer Required
Default: 587

The port of the SMTP server. Common values are 25, 465 (SMTPS), and 587 (STARTTLS).

from_address string Required
Default:

The email address that appears in the From field of outgoing messages.

username string
Default:

The username used to authenticate with the SMTP server.

password string
Default:

The password used to authenticate with the SMTP server.

auth_type string
Default: BASIC
Possible values: BASIC, NTLM

The authentication method for the SMTP connection.

enable_authentication boolean
Default: True
Possible values: True, False

Set to true to require SMTP authentication.

enable_start_tls boolean
Default: True
Possible values: True, False

Set to true to upgrade the SMTP connection to TLS using the STARTTLS command.

signature string
Default:

A signature line appended at the bottom of outgoing email messages.

FIDO metadata service [fido.metadata_service]

Enables FIDO2 attestation verification using the FIDO Metadata Service (MDS). Required for enforcing strong authenticator policies.

Sample configuration
[fido.metadata_service]
enable = False
mds_endpoints = []
enable boolean
Default: False
Possible values: True, False

Set to true to fetch and use the FIDO Alliance Metadata Service for attestation validation.

mds_endpoints array
Default: []

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.

Sample configuration
[ai_services]
key = ""
key string Required
Default:

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.

Sample configuration
[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
http_client.connection_pool_size integer
Default: 10

The maximum number of connections the HTTP client maintains across all external action endpoints.

http_client.connection_timeout integer
Default: 3000

The timeout (in milliseconds) for establishing a connection to an action endpoint.

http_client.read_timeout integer
Default: 6000

The timeout (in milliseconds) for reading a response from an action endpoint.

http_client.request_timeout integer
Default: 3000

The maximum time (in milliseconds) allowed for a complete HTTP request to an action endpoint.

http_client.retry_count integer
Default: 1

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.

Sample configuration
[identity_mgt.user_self_registration]
enable_account_lock_for_verified_preferred_channel = False
enable_account_lock_for_verified_preferred_channel boolean
Default: False
Possible values: True, 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.

Sample configuration
[resource.access_control]
context = "/api/identity/*"
secured = True
http_method = "all"
permissions = []
scope = []
allowed_auth_handlers = []
context string Required
Default: /api/identity/*

The URL context pattern this access control rule applies to.

secured boolean
Default: True
Possible values: True, False

Set to true to require authentication for requests matching the context.

http_method string
Default: all

The HTTP method this rule applies to. Use all to match any method.

permissions array
Default: []

A list of permission strings a caller must have to access this resource.

scope array
Default: []

A list of OAuth scopes required to access this resource.

allowed_auth_handlers array
Default: []

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.

Sample configuration
[sts]
signature_algorithm = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
digest_algorithm = "http://www.w3.org/2001/04/xmlenc#sha256"
signature_algorithm string
Default: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

The XML signature algorithm used to sign issued SAML tokens.

digest_algorithm string
Default: http://www.w3.org/2001/04/xmlenc#sha256

The digest algorithm used when signing SAML tokens.

CORS [cors]

Configures Cross-Origin Resource Sharing (CORS) for the Identity Server APIs. CORS allows browsers to make requests to Identity Server APIs from different origins.

Sample configuration
[cors]
allow_generic_http_requests = True
allow_any_origin = False
allowed_origins = []
allow_subdomains = False
supported_methods = [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS]
support_any_header = True
supported_headers = []
exposed_headers = []
supports_credentials = True
max_age = -1
allow_generic_http_requests boolean
Default: True
Possible values: True, False

Set to true to allow ordinary HTTP requests without CORS headers to pass through.

allow_any_origin boolean
Default: False
Possible values: True, False

Set to true to allow requests from any origin. Not recommended for production environments.

allowed_origins array
Default: []

A list of origins permitted to make cross-origin requests. For example, https://app.example.com. Only used when allow_any_origin is false.

allow_subdomains boolean
Default: False
Possible values: True, False

Set to true to allow requests from subdomains of the entries in allowed_origins.

supported_methods array
Default: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS]

The HTTP methods permitted in cross-origin requests.

support_any_header boolean
Default: True
Possible values: True, False

Set to true to allow any HTTP request header in cross-origin requests.

supported_headers array
Default: []

A list of HTTP request headers allowed in cross-origin requests. Only used when support_any_header is false.

exposed_headers array
Default: []

A list of HTTP response headers that browsers are allowed to access.

supports_credentials boolean
Default: True
Possible values: True, False

Set to true to allow cross-origin requests to include credentials such as cookies and authorization headers.

max_age integer
Default: -1

The duration (in seconds) browsers may cache the preflight response. Set to -1 to disable preflight caching.

SAML 2.0 configuration [saml]

General SAML 2.0 settings for the Identity Server acting as a SAML identity provider.

Sample configuration
[saml]
signing_alg = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
digest_alg = "http://www.w3.org/2001/04/xmlenc#sha256"
assertion_encryption_alg = "http://www.w3.org/2001/04/xmlenc#aes256-cbc"
key_encryption_alg = "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"
response.validity = "5m"
artifact.validity = "4m"
slo.retry_attempts = 5
slo.retry_interval = "1m"
slo.host_name_verification = True
enable_request_validity_period = False
request_validity_period = "5m"
signing_alg string
Default: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

The XML signature algorithm used to sign SAML assertions and responses.

digest_alg string
Default: http://www.w3.org/2001/04/xmlenc#sha256

The digest algorithm used in SAML assertion signatures.

assertion_encryption_alg string
Default: http://www.w3.org/2001/04/xmlenc#aes256-cbc

The symmetric encryption algorithm used to encrypt SAML assertions.

key_encryption_alg string
Default: http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

The algorithm used to encrypt the symmetric key during SAML assertion encryption.

response.validity string
Default: 5m

The validity period of a SAML response. Responses older than this period are rejected.

artifact.validity string
Default: 4m

The validity period of a SAML artifact used in the SAML artifact binding flow.

slo.retry_attempts integer
Default: 5

The number of retry attempts for back-channel SAML single logout (SLO) requests.

slo.retry_interval string
Default: 1m

The delay between SAML SLO retry attempts.

slo.host_name_verification boolean
Default: True
Possible values: True, False

Set to true to enforce hostname verification for back-channel SAML SLO requests.

enable_request_validity_period boolean
Default: False
Possible values: True, False

Set to true to enforce a validity window on incoming SAML authentication requests.

request_validity_period string
Default: 5m

The validity window for SAML authentication requests. Only evaluated when enable_request_validity_period is true.

SAML endpoints [saml.endpoints]

Custom URLs for SAML 2.0 endpoints. Override the defaults when the Identity Server is deployed behind a reverse proxy or when custom paths are required.

Sample configuration
[saml.endpoints]
idp_url = "${server.base_path}/samlsso"
artifact_resolution = "${server.base_path}/samlartresolve"
logout = "${server.base_path}/authenticationendpoint/samlsso_logout.do"
idp_url string
Default: ${server.base_path}/samlsso

The SAML 2.0 SSO service URL. Applications send authentication requests to this URL.

artifact_resolution string
Default: ${server.base_path}/samlartresolve

The URL of the SAML 2.0 artifact resolution service.

logout string
Default: ${server.base_path}/authenticationendpoint/samlsso_logout.do

The URL of the SAML SLO logout page.

SAML metadata [saml.metadata]

Configures the SAML IdP metadata document published by the Identity Server for service provider discovery and configuration.

Sample configuration
[saml.metadata]
validity_period = "1h"
enable_signing = False
enable_authentication_requests_signing = False
validity_period string
Default: 1h

The validity period of the published SAML metadata document.

enable_signing boolean
Default: False
Possible values: True, False

Set to true to sign the SAML metadata document using the primary keystore.

enable_authentication_requests_signing boolean
Default: False
Possible values: True, False

Set to true to include signing certificate information in the metadata for authentication requests.

SCIM 2.0 [scim2]

Configures the behavior of the SCIM 2.0 provisioning endpoints for user and group management.

Sample configuration
[scim2]
enable_filtering_enhancements = False
enable_group_based_user_filter_improvements = True
filter_users_and_groups_from_primary_domain = False
mandate_domain_for_uesrnames_and_group_names_in_response = False
return_updated_group_in_group_patch_response = True
notify_userstore_status = False
consider_max_limit_for_total_results = False
return_conflict_on_claim_uniqueness_violation = True
enable_spec_compliant_email_handling = True
enable_filtering_enhancements boolean
Default: False
Possible values: True, False

Set to true to enable enhanced filter query support for SCIM 2.0 user and group endpoints.

enable_group_based_user_filter_improvements boolean
Default: True
Possible values: True, False

Set to true to use optimized SQL queries when filtering users by group membership.

filter_users_and_groups_from_primary_domain boolean
Default: False
Possible values: True, False

Set to true to restrict user and group list operations to the PRIMARY user store domain.

mandate_domain_for_uesrnames_and_group_names_in_response boolean
Default: False
Possible values: True, False

Set to true to always prefix usernames and group names with the domain name in SCIM responses.

return_updated_group_in_group_patch_response boolean
Default: True
Possible values: True, False

Set to true to return the updated group representation in PATCH response payloads.

notify_userstore_status boolean
Default: False
Possible values: True, False

Set to true to include user store availability status in SCIM error responses.

consider_max_limit_for_total_results boolean
Default: False
Possible values: True, False

Set to true to use the server-wide maximum page size when calculating totalResults in list responses.

return_conflict_on_claim_uniqueness_violation boolean
Default: True
Possible values: True, False

Set to true to return a 409 Conflict error when a uniqueness constraint is violated on a SCIM attribute.

enable_spec_compliant_email_handling boolean
Default: True
Possible values: True, False

Set to true to handle email addresses in compliance with the SCIM 2.0 specification.

Account recovery [identity_mgt.recovery]

Controls the self-service account recovery flow, including password and username recovery.

Sample configuration
[identity_mgt.recovery]
notification.manage_internally = True
enable_detailed_error_messages = False
hide_user_existence = False
notify_user_existence = False
callback_url = "${carbon.protocol}://${carbon.host}:${carbon.management.port}/.*"
enable_v1_api = False
notification.manage_internally boolean
Default: True
Possible values: True, False

Set to true to handle recovery email notifications using the server's internal email module.

enable_detailed_error_messages boolean
Default: False
Possible values: True, False

Set to true to return detailed error messages during recovery flows. Disable in production environments to prevent user enumeration.

hide_user_existence boolean
Default: False
Possible values: True, False

Set to true to return a generic response when a user account is not found during recovery, reducing user enumeration risk.

notify_user_existence boolean
Default: False
Possible values: True, False

Set to true to notify a user if their account does not exist when they attempt to initiate recovery.

callback_url string
Default: ${carbon.protocol}://${carbon.host}:${carbon.management.port}/.*

A regex pattern the recovery callback URL must match. Restricts where users can be redirected after completing the recovery flow.

enable_v1_api boolean
Default: False
Possible values: True, False

Set to true to enable the deprecated v1 account recovery API.

User onboarding [identity_mgt.user_onboarding]

Controls the admin-initiated user onboarding flow, including email verification and Ask Password flows.

Sample configuration
[identity_mgt.user_onboarding]
enable_email_verification = False
ask_password_from_user = True
lock_on_creation = True
verification_email_validity = "1d"
notification.manage_internally = True
enable_email_verification boolean
Default: False
Possible values: True, False

Set to true to send a verification email when an admin creates a new user account.

ask_password_from_user boolean
Default: True
Possible values: True, False

Set to true to send an Ask Password email when an admin creates a user without specifying a password.

lock_on_creation boolean
Default: True
Possible values: True, False

Set to true to lock a newly created user account until the user completes the onboarding flow.

verification_email_validity string
Default: 1d

The validity period of the email verification link sent during onboarding.

notification.manage_internally boolean
Default: True
Possible values: True, False

Set to true to handle onboarding notifications through the server's internal email module.

User claim update verification [identity_mgt.user_claim_update]

Controls whether changes to user attributes such as email address and mobile number require verification before they take effect.

Sample configuration
[identity_mgt.user_claim_update]
email.enable_verification = False
email.verification_email_validity = "1d"
email.enable_notify_existing_email = False
mobile.enable_verification = False
mobile.verification_sms_otp_validity = 5
email.enable_verification boolean
Default: False
Possible values: True, False

Set to true to require email address verification when a user changes their email.

email.verification_email_validity string
Default: 1d

The validity period of the verification link sent when an email address is updated.

email.enable_notify_existing_email boolean
Default: False
Possible values: True, False

Set to true to notify the previous email address when a user requests an email change.

mobile.enable_verification boolean
Default: False
Possible values: True, False

Set to true to require mobile number verification via OTP when a user changes their mobile number.

mobile.verification_sms_otp_validity integer
Default: 5

The validity period (in minutes) of the SMS OTP sent for mobile number verification.

Password reset by email [identity_mgt.password_reset_email]

Configures the email-based password reset flow for self-service account recovery.

Sample configuration
[identity_mgt.password_reset_email]
enable_password_reset_email = False
reset_mail_validity = "1d"
enable_recaptcha = False
notify_on_reset = False
otp.send_otp_in_email = False
otp.otp_length = 6
enable_password_reset_email boolean
Default: False
Possible values: True, False

Set to true to enable the email link-based password reset flow.

reset_mail_validity string
Default: 1d

The validity period of the password reset link sent by email.

enable_recaptcha boolean
Default: False
Possible values: True, False

Set to true to require reCAPTCHA verification before a password reset email is sent.

notify_on_reset boolean
Default: False
Possible values: True, False

Set to true to send a confirmation email to the user after a successful password reset.

otp.send_otp_in_email boolean
Default: False
Possible values: True, False

Set to true to send a one-time password (OTP) in the reset email instead of a clickable link.

otp.otp_length integer
Default: 6

The number of characters in the OTP sent for email-based password reset.

Notification channel [identity_mgt.notification]

Configures the default notification channel and channel resolution behavior for identity management notifications such as verification emails and SMS OTPs.

Sample configuration
[identity_mgt.notification]
default_notification_channel = "EMAIL"
resolve_notification_channel = False
default_notification_channel string
Default: EMAIL
Possible values: EMAIL, SMS

The default notification channel used when a preferred channel cannot be determined.

resolve_notification_channel boolean
Default: False
Possible values: True, False

Set to true to dynamically resolve the notification channel based on user profile attributes rather than always using the default channel.

Password policy [identity_mgt.password_policy]

Configures server-wide password policy constraints.

Sample configuration
[identity_mgt.password_policy]
max_password_allowed_length = 64
max_password_allowed_length integer
Default: 64

The maximum number of characters allowed in a user password.

Login identifiers [identity_mgt.login_identifiers]

Configures alternative login identifiers that users can use instead of a username to authenticate. For example, email address or mobile number.

Sample configuration
[identity_mgt.login_identifiers]
enable = False
primary_claim = "http://wso2.org/claims/username"
enable boolean
Default: False
Possible values: True, False

Set to true to allow users to authenticate using alternative identifiers such as email address.

primary_claim string
Default: http://wso2.org/claims/username

The claim URI used as the primary login identifier.

Outbound provisioning [outbound_provisioning_management]

Configures the behavior of outbound provisioning, where user lifecycle events in the Identity Server are propagated to external systems such as SCIM-enabled directories or HR systems.

Sample configuration
[outbound_provisioning_management]
reset_provisioning_entities_on_config_update = True
enable_application_based_outbound_provisioning = False
fail_on_blocking_outbound_provision_failure = False
enable_scim_patch_for_updates = True
scim2_client.http_retry_count = 1
scim2_client.http_read_timeout = 5000
scim2_client.http_connection_timeout = 5000
reset_provisioning_entities_on_config_update boolean
Default: True
Possible values: True, False

Set to true to re-provision all entities when the outbound provisioning connector configuration changes.

enable_application_based_outbound_provisioning boolean
Default: False
Possible values: True, False

Set to true to trigger outbound provisioning only for users associated with specific applications.

fail_on_blocking_outbound_provision_failure boolean
Default: False
Possible values: True, False

Set to true to block the operation that triggered outbound provisioning if the provisioning request fails.

enable_scim_patch_for_updates boolean
Default: True
Possible values: True, False

Set to true to use SCIM PATCH operations for user attribute updates instead of replacing the entire resource with PUT.

scim2_client.http_retry_count integer
Default: 1

The number of retry attempts for failed SCIM 2.0 outbound provisioning requests.

scim2_client.http_read_timeout integer
Default: 5000

The read timeout (in milliseconds) for SCIM 2.0 outbound provisioning HTTP requests.

scim2_client.http_connection_timeout integer
Default: 5000

The connection timeout (in milliseconds) for SCIM 2.0 outbound provisioning HTTP requests.

Tenant context [tenant_context]

Controls how tenant-qualified URLs and per-tenant sessions are handled. Configure this section for multi-tenant deployments.

Sample configuration
[tenant_context]
enable_tenant_qualified_urls = True
enable_tenanted_sessions = True
require_super_tenant_in_urls = False
enable_tenant_qualified_urls boolean
Default: True
Possible values: True, False

Set to true to include the tenant domain in API endpoint URLs. For example, /t/{tenant-domain}/oauth2/token.

enable_tenanted_sessions boolean
Default: True
Possible values: True, False

Set to true to isolate sessions per tenant, preventing cross-tenant session sharing.

require_super_tenant_in_urls boolean
Default: False
Possible values: True, False

Set to true to require the super tenant domain in URLs for super tenant API calls.

Passive STS (WS-Federation) [passive_sts]

Configures the WS-Federation passive requestor profile endpoint for browser-based federated authentication.

Sample configuration
[passive_sts]
slo.host_name_verification = True
enable_logout_wreply_validation = True
disable_applies_to_in_response = False
soap_enabled = False
slo.host_name_verification boolean
Default: True
Possible values: True, False

Set to true to enforce hostname verification for back-channel logout requests from WS-Federation service providers.

enable_logout_wreply_validation boolean
Default: True
Possible values: True, False

Set to true to validate the wreply parameter against registered service provider URLs on logout.

disable_applies_to_in_response boolean
Default: False
Possible values: True, False

Set to true to omit the AppliesTo element from the WS-Federation response.

soap_enabled boolean
Default: False
Possible values: True, False

Set to true to enable SOAP-based WS-Federation requests in addition to the passive requestor profile.