diff --git a/grails-doc/src/en/ref/Configuration/Application Properties.adoc b/grails-doc/src/en/ref/Configuration/Application Properties.adoc new file mode 100644 index 00000000000..4a45e9708f2 --- /dev/null +++ b/grails-doc/src/en/ref/Configuration/Application Properties.adoc @@ -0,0 +1,1357 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +//// + +== Application Properties + +A comprehensive reference of all configuration properties specific to Grails and its bundled plugins. These properties are set in `grails-app/conf/application.yml` (or `application.groovy`). + +Since Grails is built on Spring Boot, all https://docs.spring.io/spring-boot/{springBootVersion}/appendix/application-properties/index.html[Spring Boot Common Application Properties] are also available (for example `server.port`, `logging.*`, `spring.datasource.hikari.*`, and `management.*`). This reference covers only Grails-specific properties. + +=== Core Properties + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.profile` +| The active Grails application profile (e.g., `web`, `rest-api`, `plugin`). +| Set by project template + +| `grails.codegen.defaultPackage` +| The default package used when generating artefacts with `grails create-*` commands. +| Set by project template + +| `grails.serverURL` +| The server URL used to generate absolute links (e.g., `\https://my.app.com`). Also used by redirects. +| _(derived from request)_ + +| `grails.enable.native2ascii` +| Whether to perform native2ascii conversion of i18n properties files. +| `true` + +| `grails.bootstrap.skip` +| Whether to skip execution of `BootStrap.groovy` classes on startup. +| `false` + +| `grails.spring.bean.packages` +| List of packages to scan for Spring beans. +| `[]` + +| `grails.spring.disable.aspectj.autoweaving` +| Whether to disable AspectJ auto-weaving. +| `false` + +| `grails.spring.placeholder.prefix` +| The prefix for property placeholder resolution. +| `${` + +| `grails.spring.transactionManagement.proxies` +| Whether to enable Spring proxy-based transaction management. Since `@Transactional` uses an AST transform, proxies are typically redundant. +| `false` + +| `grails.plugin.includes` +| List of plugin names to include in the plugin manager (all others excluded). +| `[]` _(all plugins)_ + +| `grails.plugin.excludes` +| List of plugin names to exclude from the plugin manager. +| `[]` +|=== + +=== Web & Controllers + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.controllers.defaultScope` +| The default scope for controllers (`singleton`, `prototype`, `session`). +| `singleton` + +| `grails.controllers.upload.location` +| The directory for temporary file uploads. +| `System.getProperty('java.io.tmpdir')` + +| `grails.controllers.upload.maxFileSize` +| Maximum file size for uploads (in bytes). +| `1048576` (1 MB) + +| `grails.controllers.upload.maxRequestSize` +| Maximum request size for multipart uploads (in bytes). +| `10485760` (10 MB) + +| `grails.controllers.upload.fileSizeThreshold` +| File size threshold (in bytes) above which uploads are written to disk. +| `0` + +| `grails.web.url.converter` +| The URL token converter strategy. Use `hyphenated` for hyphen-separated URLs. +| `camelCase` + +| `grails.web.linkGenerator.useCache` +| Whether to cache links generated by the link generator. +| `true` + +| `grails.web.servlet.path` +| The path the Grails dispatcher servlet is mapped to. +| `/+++*+++` + +| `grails.filter.encoding` +| The character encoding for the Grails character encoding filter. +| `UTF-8` + +| `grails.filter.forceEncoding` +| Whether to force the encoding filter to set the encoding on the response. +| `true` + +| `grails.exceptionresolver.logRequestParameters` +| Whether to log request parameters in exception stack traces. +| `true` + +| `grails.exceptionresolver.params.exclude` +| List of parameter names to mask (replace with `[*****]`) in exception stack traces. Typically used for `password`, `creditCard`, etc. +| `[]` + +| `grails.logging.stackTraceFiltererClass` +| Fully qualified class name of a custom `StackTraceFilterer` implementation. +| `org.grails.exceptions.reporting.DefaultStackTraceFilterer` +|=== + +=== CORS + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.cors.enabled` +| Whether CORS support is enabled. +| `false` + +| `grails.cors.filter` +| Whether CORS is handled via a servlet filter (`true`) or an interceptor (`false`). +| `true` + +| `grails.cors.allowedOrigins` +| List of allowed origins (e.g., `\http://localhost:5000`). Only applies when `grails.cors.enabled` is `true`. +| `['*']` + +| `grails.cors.allowedMethods` +| List of allowed HTTP methods. +| `['*']` + +| `grails.cors.allowedHeaders` +| List of allowed request headers. +| `['*']` + +| `grails.cors.exposedHeaders` +| List of response headers to expose to the client. +| `[]` + +| `grails.cors.maxAge` +| How long (in seconds) the preflight response can be cached. +| `1800` + +| `grails.cors.allowCredentials` +| Whether credentials (cookies, authorization headers) are supported. +| `false` + +| `grails.cors.mappings` +| Map of URL patterns to per-path CORS configuration. Defining any mapping disables the global `/**` mapping. +| `{}` _(global `/**` mapping)_ +|=== + +=== Views & GSP + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.views.default.codec` +| The default encoding codec for GSP output. Set to `html` to reduce XSS risk. Options: `none`, `html`, `base64`. +| `none` + +| `grails.views.gsp.encoding` +| The file encoding for GSP source files. +| `UTF-8` + +| `grails.views.gsp.htmlcodec` +| The HTML codec for GSP output (`xml` or `html`). +| `xml` + +| `grails.views.gsp.codecs.expression` +| The codec applied to GSP `${}` expressions. +| `html` + +| `grails.views.gsp.codecs.scriptlet` +| The codec applied to GSP `<% %>` scriptlet output. +| `html` + +| `grails.views.gsp.codecs.taglib` +| The codec applied to tag library output. +| `none` + +| `grails.views.gsp.codecs.staticparts` +| The codec applied to static HTML parts of GSP pages. +| `none` + +| `grails.views.gsp.layout.preprocess` +| Whether GSP layout preprocessing is enabled. Disabling allows Grails to parse rendered HTML but slows rendering. +| `true` + +| `grails.views.enable.jsessionid` +| Whether to include the `jsessionid` in rendered links. +| `false` + +| `grails.views.filteringCodecForContentType` +| Map of content types to encoding codecs. +| `{}` + +| `grails.gsp.disable.caching.resources` +| Whether to disable GSP resource caching. +| `false` + +| `grails.gsp.enable.reload` +| Whether to enable GSP reloading in production. +| `false` + +| `grails.gsp.view.dir` +| Custom directory for GSP view resolution. +| `grails-app/views` +|=== + +=== Content Negotiation & MIME Types + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.mime.types` +| Map of MIME type names to content type strings used for content negotiation. +| _(see web profile `application.yml`)_ + +| `grails.mime.file.extensions` +| Whether to use the file extension to determine the MIME type in content negotiation. +| `true` + +| `grails.mime.use.accept.header` +| Whether to use the `Accept` header for content negotiation. +| `true` + +| `grails.mime.disable.accept.header.userAgents` +| List of user agent substrings (e.g., `Gecko`, `WebKit`) for which `Accept` header processing is disabled. +| `[]` + +| `grails.mime.disable.accept.header.userAgentsXhr` +| When `true`, XHR requests also respect the `grails.mime.disable.accept.header.userAgents` setting. By default, XHR requests ignore user agent filtering. +| `false` + +| `grails.converters.encoding` +| The character encoding for converter output (JSON/XML). +| `UTF-8` +|=== + +=== Data Binding + +These properties configure Grails' data binding behavior. Defined via `@ConfigurationProperties("grails.databinding")`. + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.databinding.trimStrings` +| Whether to trim whitespace from String values during data binding. +| `true` + +| `grails.databinding.convertEmptyStringsToNull` +| Whether empty String values are converted to `null` during data binding. +| `true` + +| `grails.databinding.autoGrowCollectionLimit` +| The maximum size to which indexed collections can auto-grow during data binding. +| `256` + +| `grails.databinding.dateFormats` +| List of date format strings used to parse date values during data binding. +| `["yyyy-MM-dd HH:mm:ss.S", "yyyy-MM-dd'T'HH:mm:ss'Z'", "yyyy-MM-dd HH:mm:ss.S z", "yyyy-MM-dd'T'HH:mm:ssX"]` + +| `grails.databinding.dateParsingLenient` +| Whether date parsing is lenient (accepting invalid dates like Feb 30). +| `false` +|=== + +=== Internationalization + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.i18n.cache.seconds` +| How long (in seconds) to cache resolved message bundles. Set to `-1` to cache indefinitely, `0` to disable caching. +| `-1` + +| `grails.i18n.filecache.seconds` +| How long (in seconds) to cache the message bundle file lookup. Set to `-1` to cache indefinitely. +| `-1` +|=== + +=== Static Resources + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.resources.enabled` +| Whether serving static files from `src/main/resources/public` is enabled. +| `true` + +| `grails.resources.pattern` +| The URL path pattern for serving static resources. +| `/static/**` + +| `grails.resources.cachePeriod` +| The cache period (in seconds) for static resource HTTP responses. +| `0` _(no caching)_ +|=== + +=== URL Mappings + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.urlmapping.cache.maxsize` +| The maximum size of the URL mapping cache. +| `1000` +|=== + +=== Scaffolding + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.scaffolding.templates.domainSuffix` +| The suffix appended to domain class names when generating scaffolding templates. +| `""` +|=== + +=== Development & Reloading + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.reload.includes` +| List of fully qualified class names to include in development reloading. When set, only these classes are reloaded. +| `[]` _(all project classes)_ + +| `grails.reload.excludes` +| List of fully qualified class names to exclude from development reloading. +| `[]` +|=== + +=== Events + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.events.spring` +| Whether to bridge GORM/Grails events to the Spring `ApplicationEventPublisher`, allowing `@EventListener` methods to receive domain events. +| `true` +|=== + +=== JSON & Converters + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.json.legacy.builder` +| Whether to use the legacy JSON builder. +| `false` + +| `grails.converters.json.domain.include.class` +| Whether to include the `class` property when marshalling domain objects to JSON. +| `false` + +| `grails.converters.xml.domain.include.class` +| Whether to include the `class` attribute when marshalling domain objects to XML. +| `false` +|=== + +=== GORM + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.gorm.failOnError` +| When `true`, `save()` throws `ValidationException` on validation failure instead of returning `null`. Can also be a list of package names to apply selectively. +| `false` + +| `grails.gorm.autoFlush` +| Whether to automatically flush the Hibernate session between queries. +| `false` + +| `grails.gorm.flushMode` +| The default Hibernate flush mode (`AUTO`, `COMMIT`, `MANUAL`). +| `AUTO` + +| `grails.gorm.markDirty` +| Whether to mark a domain instance as dirty on an explicit `save()` call. +| `true` + +| `grails.gorm.autowire` +| Whether to autowire Spring beans into domain class instances. +| `true` + +| `grails.gorm.default.mapping` +| A closure applied as the default mapping block for all domain classes. +| `{}` + +| `grails.gorm.default.constraints` +| A closure applied as the default constraints for all domain classes. +| `{}` + +| `grails.gorm.custom.types` +| Map of custom GORM types. +| `{}` + +| `grails.gorm.reactor.events` +| Whether to translate GORM events into Reactor events (disabled by default for performance). +| `false` + +| `grails.gorm.events.autoTimestampInsertOverwrite` +| Whether auto-timestamp (`dateCreated`) overwrites a user-provided value on insert. +| `true` +|=== + +==== Multi-Tenancy + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.gorm.multiTenancy.mode` +| The multi-tenancy mode: `DISCRIMINATOR`, `DATABASE`, `SCHEMA`, or `NONE`. +| `NONE` + +| `grails.gorm.multiTenancy.tenantResolverClass` +| Fully qualified class name of the `TenantResolver` implementation. +| _(required when mode is not NONE)_ +|=== + +=== DataSource + +Spring Boot auto-configures the connection pool. https://github.com/brettwooldridge/HikariCP[HikariCP] is the default and preferred pool. Pool-specific tuning is configured via `spring.datasource.hikari.*` - see the https://docs.spring.io/spring-boot/{springBootVersion}/reference/data/sql.html#data.sql.datasource.connection-pool[Spring Boot Connection Pool documentation]. + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `dataSource.driverClassName` +| The JDBC driver class name. +| `org.h2.Driver` + +| `dataSource.username` +| The database username. +| `sa` + +| `dataSource.password` +| The database password. +| `''` + +| `dataSource.url` +| The JDBC connection URL. +| `jdbc:h2:mem:devDb` (dev) + +| `dataSource.dbCreate` +| The schema generation strategy: `create-drop`, `create`, `update`, `validate`, or `none`. Use `none` in production with a migration tool. +| `create-drop` (dev), `none` (prod) + +| `dataSource.pooled` +| Whether to use a connection pool. +| `true` + +| `dataSource.logSql` +| Whether to log SQL statements to stdout. +| `false` + +| `dataSource.formatSql` +| Whether to format logged SQL for readability. +| `false` + +| `dataSource.dialect` +| The Hibernate dialect class name or class. +| _(auto-detected from driver)_ + +| `dataSource.readOnly` +| Whether the DataSource is read-only (calls `setReadOnly(true)` on connections). +| `false` + +| `dataSource.transactional` +| For additional (non-default) datasources: whether to include in the chained transaction manager. +| `true` + +| `dataSource.persistenceInterceptor` +| For additional datasources: whether to wire up the persistence interceptor (the default datasource is always wired). +| `false` + +| `dataSource.jmxExport` +| Whether to register JMX MBeans for the DataSource. +| `true` + +| `dataSource.type` +| The connection pool implementation class when multiple are on the classpath. +| `com.zaxxer.hikari.HikariDataSource` +|=== + +Additional datasources are configured under the `dataSources` key. Each named datasource supports the same properties as the default `dataSource`. + +[source,yaml] +---- +dataSources: + lookup: + pooled: true + jmxExport: true + driverClassName: org.h2.Driver + url: jdbc:h2:mem:simpleDb +---- + +=== Hibernate + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `hibernate.cache.queries` +| Whether to cache Hibernate queries. +| `false` + +| `hibernate.cache.use_second_level_cache` +| Whether to enable Hibernate's second-level cache. +| `false` + +| `hibernate.cache.use_query_cache` +| Whether to enable Hibernate's query cache. +| `false` +|=== + +NOTE: All standard {hibernate5Reference}#configurations[Hibernate configuration properties] are supported under the `hibernate` key. + +=== Database Migration Plugin + +These properties are read from the `grails.plugin.databasemigration` namespace. For multi-datasource setups, per-datasource configuration uses `grails.plugin.databasemigration.` (e.g., `grails.plugin.databasemigration.analytics.updateOnStart`). + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.databasemigration.updateOnStart` +| Whether to automatically apply pending migrations on application startup. +| `false` + +| `grails.plugin.databasemigration.updateAllOnStart` +| Whether to apply migrations for all datasources on startup (overrides per-datasource `updateOnStart`). +| `false` + +| `grails.plugin.databasemigration.updateOnStartFileName` +| The changelog filename to use when applying migrations on startup. +| `changelog.groovy` (default ds), `changelog-.groovy` (named ds) + +| `grails.plugin.databasemigration.dropOnStart` +| Whether to drop and recreate the schema before applying migrations on startup. +| `false` + +| `grails.plugin.databasemigration.updateOnStartContexts` +| List of Liquibase contexts to apply during startup migration. +| `[]` _(all contexts)_ + +| `grails.plugin.databasemigration.updateOnStartLabels` +| List of Liquibase labels to apply during startup migration. +| `[]` _(all labels)_ + +| `grails.plugin.databasemigration.updateOnStartDefaultSchema` +| The default schema to use when applying migrations on startup. +| _(database default schema)_ + +| `grails.plugin.databasemigration.databaseChangeLogTableName` +| Custom name for the Liquibase changelog tracking table. +| `DATABASECHANGELOG` + +| `grails.plugin.databasemigration.databaseChangeLogLockTableName` +| Custom name for the Liquibase lock table. +| `DATABASECHANGELOGLOCK` + +| `grails.plugin.databasemigration.changelogLocation` +| The directory containing migration changelog files. +| `grails-app/migrations` + +| `grails.plugin.databasemigration.changelogFileName` +| The default changelog filename for CLI commands. +| `changelog.groovy` (default ds), `changelog-.groovy` (named ds) + +| `grails.plugin.databasemigration.contexts` +| List of Liquibase contexts for CLI commands. +| `[]` _(all contexts)_ + +| `grails.plugin.databasemigration.excludeObjects` +| Comma-separated list of database object names to exclude from `dbm-gorm-diff` and `dbm-generate-changelog` output. Cannot be combined with `includeObjects`. +| `''` + +| `grails.plugin.databasemigration.includeObjects` +| Comma-separated list of database object names to include in diff/changelog output (all others excluded). Cannot be combined with `excludeObjects`. +| `''` + +| `grails.plugin.databasemigration.skipUpdateOnStartMainClasses` +| List of main class names that should skip auto-migration on startup (e.g., CLI command runners). +| `['grails.ui.command.GrailsApplicationContextCommandRunner']` +|=== + +=== Cache Plugin + +The Grails Cache plugin provides annotation-driven caching (`@Cacheable`, `@CacheEvict`, `@CachePut`). It is included as a default feature in generated Grails applications. + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.cache.enabled` +| Whether the cache plugin is enabled. +| `true` + +| `grails.cache.cleanAtStartup` +| Whether to clear all caches on application startup. +| `false` + +| `grails.cache.cacheManager` +| Fully qualified class name of the `CacheManager` implementation. +| `grails.plugin.cache.GrailsConcurrentMapCacheManager` + +| `grails.cache.clearAtStartup` +| Alias for `cleanAtStartup` (both are supported). +| `false` +|=== + +When using EHCache as the cache provider, additional properties are available: + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.cache.ehcache.ehcacheXmlLocation` +| Classpath location of the `ehcache.xml` configuration file. +| `classpath:ehcache.xml` + +| `grails.cache.ehcache.lockTimeout` +| Timeout (in milliseconds) for cache lock acquisition. +| `200` +|=== + +=== Asset Pipeline Plugin + +The https://github.com/wondrify/asset-pipeline[Asset Pipeline plugin] manages and processes static assets (JavaScript, CSS, images) in Grails applications. It is included as a default feature in generated web applications. These properties are set under the `grails.assets` namespace. + +NOTE: Build-time properties (minification, digests, gzip) can also be configured in `build.gradle` via the `assets {}` block. The `application.yml` values shown here apply at runtime. + +==== Runtime Behavior + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.assets.mapping` +| The URL path segment for serving assets (e.g., `/assets/+++*+++`). Must be one level deep - `foo` is valid, `foo/bar` is not. +| `assets` + +| `grails.assets.bundle` +| Whether assets are bundled in development mode. When `false`, individual files are loaded separately for easier debugging. +| `false` + +| `grails.assets.url` +| Base URL for assets. Useful for CDN integration (e.g., `\https://cdn.example.com/`). Can also be a `Closure` accepting `HttpServletRequest` for dynamic URL generation in `application.groovy`. +| _(derived from request)_ + +| `grails.assets.storagePath` +| Directory path to copy compiled assets on application startup (e.g., for CDN upload). +| _(none)_ + +| `grails.assets.useManifest` +| Whether to use the `manifest.properties` file for asset resolution in production. +| `true` + +| `grails.assets.skipNotFound` +| If `true`, missing assets pass through to the next filter instead of returning 404. +| `false` + +| `grails.assets.allowDebugParam` +| If `true`, allows `?_debugAssets=y` query parameter to force non-bundled mode in production for debugging. +| `false` + +| `grails.assets.cacheLocation` +| Directory for caching compiled assets during development. +| `build/assetCache` +|=== + +==== Minification & Optimization + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.assets.minifyJs` +| Whether to minify JavaScript using Google Closure Compiler. +| `true` + +| `grails.assets.minifyCss` +| Whether to minify CSS. +| `true` + +| `grails.assets.enableSourceMaps` +| Whether to generate source maps for minified JavaScript files (`.js.map`). +| `true` + +| `grails.assets.enableDigests` +| Whether to generate digest/fingerprinted filenames (e.g., `app-abc123.js`). +| `true` + +| `grails.assets.skipNonDigests` +| If `true`, only digested filenames are generated. Non-digested names are served via manifest mapping. Reduces storage by 50%. +| `true` + +| `grails.assets.enableGzip` +| Whether to generate gzipped versions of assets (`.gz` files). +| `true` + +| `grails.assets.excludesGzip` +| List of GLOB patterns for files to exclude from gzip compression (e.g., `['+++**+++/+++*+++.png', '+++**+++/+++*+++.jpg']`). +| `[]` + +| `grails.assets.minifyOptions` +| Map of options passed to Google Closure Compiler. Keys: `languageMode` (input), `targetLanguage` (output), `optimizationLevel` (`SIMPLE`, `ADVANCED`, `WHITESPACE_ONLY`). +| `{languageMode: 'ES5', targetLanguage: 'ES5', optimizationLevel: 'SIMPLE'}` +|=== + +==== File Inclusion & Exclusion + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.assets.excludes` +| List of GLOB patterns (or `regex:` prefixed) for files to exclude from compilation. Excluded files can still be included via `require` directives. +| `[]` + +| `grails.assets.includes` +| List of GLOB patterns to override excludes. Allows specific files to be compiled even if they match an exclude pattern. +| `[]` +|=== + +==== JavaScript Processing + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.assets.enableES6` +| Enable ES6+ transpilation via Babel/SWC. If not set, auto-detects ES6 syntax. +| _(auto-detect)_ + +| `grails.assets.commonJs` +| Whether to enable CommonJS module support (`require()` / `module.exports`). +| `true` + +| `grails.assets.nodeEnv` +| Value injected as `process.env.NODE_ENV` in JavaScript files (used by libraries like React). +| `development` +|=== + +=== Spring Security Plugin + +The https://grails-plugins.github.io/grails-spring-security-core/[Grails Spring Security plugin] provides comprehensive authentication and authorization support for Grails applications. Detailed documentation is available in the plugin's full reference guide. + +==== General Settings + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.active` +| Whether the security plugin is active. +| `true` + +| `grails.plugin.springsecurity.printStatusMessages` +| Whether to print startup and status messages to the console. +| `true` + +| `grails.plugin.springsecurity.rejectIfNoRule` +| Whether to reject requests if no matching security rule is found. +| `true` + +| `grails.plugin.springsecurity.securityConfigType` +| The security configuration strategy (`Annotation`, `Requestmap`, `InterceptUrlMap`). +| `Annotation` + +| `grails.plugin.springsecurity.roleHierarchy` +| The role hierarchy definition string. +| `''` + +| `grails.plugin.springsecurity.cacheUsers` +| Whether to cache user details in the user details service. +| `false` + +| `grails.plugin.springsecurity.useHttpSessionEventPublisher` +| Whether to register a `HttpSessionEventPublisher` bean. +| `false` + +| `grails.plugin.springsecurity.useSecurityEventListener` +| Whether to publish security events to the Grails event system. +| `false` +|=== + +==== User & Role Configuration + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.userLookup.userDomainClassName` +| The fully qualified name of the user domain class. +| `null` _(must be set)_ + +| `grails.plugin.springsecurity.userLookup.usernamePropertyName` +| The property name for the username in the user domain class. +| `username` + +| `grails.plugin.springsecurity.userLookup.enabledPropertyName` +| The property name for the enabled status in the user domain class. +| `enabled` + +| `grails.plugin.springsecurity.userLookup.passwordPropertyName` +| The property name for the password in the user domain class. +| `password` + +| `grails.plugin.springsecurity.userLookup.authoritiesPropertyName` +| The property name for the authorities collection in the user domain class. +| `authorities` + +| `grails.plugin.springsecurity.userLookup.accountExpiredPropertyName` +| The property name for the account expired status in the user domain class. +| `accountExpired` + +| `grails.plugin.springsecurity.userLookup.accountLockedPropertyName` +| The property name for the account locked status in the user domain class. +| `accountLocked` + +| `grails.plugin.springsecurity.userLookup.passwordExpiredPropertyName` +| The property name for the password expired status in the user domain class. +| `passwordExpired` + +| `grails.plugin.springsecurity.userLookup.authorityJoinClassName` +| The fully qualified name of the user-authority join domain class. +| `null` _(must be set)_ + +| `grails.plugin.springsecurity.userLookup.usernameIgnoreCase` +| Whether to ignore case when looking up users by username. +| `false` + +| `grails.plugin.springsecurity.authority.className` +| The fully qualified name of the authority (role) domain class. +| `null` _(must be set)_ + +| `grails.plugin.springsecurity.authority.nameField` +| The property name for the authority name in the authority domain class. +| `authority` + +| `grails.plugin.springsecurity.useRoleGroups` +| Whether to enable support for role groups. +| `false` +|=== + +==== Authentication + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.apf.filterProcessesUrl` +| The URL the authentication processing filter handles. +| `/login/authenticate` + +| `grails.plugin.springsecurity.apf.usernameParameter` +| The HTTP parameter name for the username in login requests. +| `username` + +| `grails.plugin.springsecurity.apf.passwordParameter` +| The HTTP parameter name for the password in login requests. +| `password` + +| `grails.plugin.springsecurity.apf.postOnly` +| Whether to restrict authentication requests to HTTP POST. +| `true` + +| `grails.plugin.springsecurity.apf.allowSessionCreation` +| Whether to allow the authentication filter to create a new HTTP session. +| `true` + +| `grails.plugin.springsecurity.apf.storeLastUsername` +| Whether to store the last used username in the session after a failed login. +| `false` +|=== + +==== Login & Logout + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.auth.loginFormUrl` +| The URL of the login form page. +| `/login/auth` + +| `grails.plugin.springsecurity.auth.forceHttps` +| Whether to force HTTPS for the login page. +| `false` + +| `grails.plugin.springsecurity.auth.ajaxLoginFormUrl` +| The URL of the AJAX login form. +| `/login/authAjax` + +| `grails.plugin.springsecurity.auth.useForward` +| Whether to use a forward instead of a redirect to the login page. +| `false` + +| `grails.plugin.springsecurity.successHandler.defaultTargetUrl` +| The default URL to redirect to after a successful login. +| `/` + +| `grails.plugin.springsecurity.successHandler.alwaysUseDefault` +| Whether to always redirect to the default target URL after login. +| `false` + +| `grails.plugin.springsecurity.successHandler.ajaxSuccessUrl` +| The URL used for AJAX success responses. +| `/login/ajaxSuccess` + +| `grails.plugin.springsecurity.successHandler.useReferer` +| Whether to redirect to the `Referer` header URL after login. +| `false` + +| `grails.plugin.springsecurity.failureHandler.defaultFailureUrl` +| The default URL to redirect to after a failed login. +| `/login/authfail?login_error=1` + +| `grails.plugin.springsecurity.failureHandler.ajaxAuthFailUrl` +| The URL used for AJAX failure responses. +| `/login/authfail?ajax=true` + +| `grails.plugin.springsecurity.failureHandler.useForward` +| Whether to use a forward for authentication failure. +| `false` + +| `grails.plugin.springsecurity.logout.afterLogoutUrl` +| The URL to redirect to after logging out. +| `/` + +| `grails.plugin.springsecurity.logout.filterProcessesUrl` +| The URL the logout filter handles. +| `/logoff` + +| `grails.plugin.springsecurity.logout.postOnly` +| Whether to restrict logout requests to HTTP POST. +| `true` + +| `grails.plugin.springsecurity.logout.invalidateHttpSession` +| Whether to invalidate the HTTP session on logout. +| `true` + +| `grails.plugin.springsecurity.logout.clearAuthentication` +| Whether to clear the authentication from the security context on logout. +| `true` + +| `grails.plugin.springsecurity.logout.redirectToReferer` +| Whether to redirect to the `Referer` header URL after logout. +| `false` + +| `grails.plugin.springsecurity.adh.errorPage` +| The URL of the access denied page. +| `/login/denied` + +| `grails.plugin.springsecurity.adh.ajaxErrorPage` +| The URL of the AJAX access denied page. +| `/login/ajaxDenied` + +| `grails.plugin.springsecurity.adh.useForward` +| Whether to use a forward for access denied errors. +| `true` +|=== + +==== Password Encoding + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.password.algorithm` +| The password hashing algorithm. +| `bcrypt` + +| `grails.plugin.springsecurity.password.encodeHashAsBase64` +| Whether to encode the hashed password as Base64. +| `false` + +| `grails.plugin.springsecurity.password.bcrypt.logrounds` +| The number of log rounds for the BCrypt algorithm. +| `10` _(4 in test)_ + +| `grails.plugin.springsecurity.password.hash.iterations` +| The number of hash iterations for algorithms that support it. +| `10000` _(1 in test)_ +|=== + +==== Remember Me + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.rememberMe.cookieName` +| The name of the remember-me cookie. +| `grails_remember_me` + +| `grails.plugin.springsecurity.rememberMe.alwaysRemember` +| Whether to always remember the user, even if the checkbox is not checked. +| `false` + +| `grails.plugin.springsecurity.rememberMe.tokenValiditySeconds` +| The validity period (in seconds) of the remember-me token. +| `1209600` _(14 days)_ + +| `grails.plugin.springsecurity.rememberMe.parameter` +| The HTTP parameter name for the remember-me checkbox. +| `remember-me` + +| `grails.plugin.springsecurity.rememberMe.key` +| The secret key used to sign remember-me cookies. +| `grailsRocks` + +| `grails.plugin.springsecurity.rememberMe.persistent` +| Whether to use persistent (database-backed) remember-me tokens. +| `false` + +| `grails.plugin.springsecurity.rememberMe.useSecureCookie` +| Whether to use the `Secure` flag on the remember-me cookie. +| `null` + +| `grails.plugin.springsecurity.rememberMe.persistentToken.domainClassName` +| The fully qualified name of the persistent token domain class. +| `null` +|=== + +==== URL Mapping & Access Control + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.controllerAnnotations.staticRules` +| Map of static URL rules for controller-based security. +| `[]` + +| `grails.plugin.springsecurity.interceptUrlMap` +| Map of URL patterns to security rules. +| `[]` + +| `grails.plugin.springsecurity.requestMap.className` +| The fully qualified name of the `Requestmap` domain class. +| `null` + +| `grails.plugin.springsecurity.requestMap.urlField` +| The property name for the URL in the `Requestmap` domain class. +| `url` + +| `grails.plugin.springsecurity.requestMap.configAttributeField` +| The property name for the config attribute in the `Requestmap` domain class. +| `configAttribute` + +| `grails.plugin.springsecurity.fii.rejectPublicInvocations` +| Whether to reject invocations that do not match any security rule. +| `true` + +| `grails.plugin.springsecurity.fii.alwaysReauthenticate` +| Whether to always re-authenticate on every request. +| `false` + +| `grails.plugin.springsecurity.fii.validateConfigAttributes` +| Whether to validate configuration attributes at startup. +| `true` + +| `grails.plugin.springsecurity.fii.observeOncePerRequest` +| Whether to ensure security checks are performed only once per request. +| `true` +|=== + +==== Session & Security Context + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.useSessionFixationPrevention` +| Whether to enable session fixation prevention. +| `true` + +| `grails.plugin.springsecurity.sessionFixationPrevention.migrate` +| Whether to migrate session attributes to the new session after login. +| `true` + +| `grails.plugin.springsecurity.scr.allowSessionCreation` +| Whether the security context repository is allowed to create a session. +| `true` + +| `grails.plugin.springsecurity.scr.disableUrlRewriting` +| Whether to disable URL rewriting for session IDs. +| `true` + +| `grails.plugin.springsecurity.scpf.forceEagerSessionCreation` +| Whether to force eager creation of the HTTP session. +| `false` + +| `grails.plugin.springsecurity.sch.strategyName` +| The security context holder strategy (`MODE_THREADLOCAL`, `MODE_INHERITABLETHREADLOCAL`). +| `MODE_THREADLOCAL` +|=== + +==== Additional Authentication Methods + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.useBasicAuth` +| Whether to enable HTTP Basic authentication. +| `false` + +| `grails.plugin.springsecurity.basic.realmName` +| The realm name used in HTTP Basic authentication. +| `Grails Realm` + +| `grails.plugin.springsecurity.useSwitchUserFilter` +| Whether to enable the switch user filter for user impersonation. +| `false` + +| `grails.plugin.springsecurity.switchUser.switchUserUrl` +| The URL used to initiate a user switch. +| `/login/impersonate` + +| `grails.plugin.springsecurity.switchUser.exitUserUrl` +| The URL used to exit a user switch and return to the original user. +| `/logout/impersonate` +|=== + +==== GSP Layouts + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.gsp.layoutAuth` +| The Sitemesh layout used for the authentication page. +| `main` + +| `grails.plugin.springsecurity.gsp.layoutDenied` +| The Sitemesh layout used for the access denied page. +| `main` +|=== + +==== Other + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.plugin.springsecurity.ajaxHeader` +| The HTTP header name used to identify AJAX requests. +| `X-Requested-With` + +| `grails.plugin.springsecurity.ipRestrictions` +| List of IP-based restriction rules. +| `[]` + +| `grails.plugin.springsecurity.portMapper.httpPort` +| The standard HTTP port used for redirecting between secure and insecure pages. +| `8080` + +| `grails.plugin.springsecurity.portMapper.httpsPort` +| The standard HTTPS port used for redirecting between secure and insecure pages. +| `8443` + +| `grails.plugin.springsecurity.dao.hideUserNotFoundExceptions` +| Whether to hide `UsernameNotFoundException` and instead throw `BadCredentialsException`. +| `true` + +| `grails.plugin.springsecurity.providerManager.eraseCredentialsAfterAuthentication` +| Whether to erase password credentials from the `Authentication` object after successful authentication. +| `true` + +| `grails.plugin.springsecurity.debug.useFilter` +| Whether to enable the Spring Security debug filter. +| `false` +|=== + +=== MongoDB GORM Plugin + +The MongoDB GORM plugin provides GORM support for the MongoDB document database. Properties under `grails.mongodb.options.*` use reflection to map to the `MongoClientSettings.Builder` class. + +==== Connection + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.mongodb.url` +| The MongoDB connection string. +| `mongodb://localhost/test` + +| `grails.mongodb.host` +| The MongoDB server host. +| `localhost` + +| `grails.mongodb.port` +| The MongoDB server port. +| `27017` + +| `grails.mongodb.databaseName` +| The name of the MongoDB database. +| _(application name)_ + +| `grails.mongodb.username` +| The database username. +| _(none)_ + +| `grails.mongodb.password` +| The database password. +| _(none)_ +|=== + +==== Behavior + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.mongodb.stateless` +| Whether the GORM implementation is stateless (disabling persistence context). +| `false` + +| `grails.mongodb.decimalType` +| Whether to use the `Decimal128` type for `BigDecimal` properties. +| `false` + +| `grails.mongodb.codecs` +| List of custom MongoDB codec classes. +| `[]` + +| `grails.mongodb.default.mapping` +| A closure applied as the default mapping block for MongoDB domain classes. +| `{}` +|=== + +==== Connection Pool + +These properties are set under `grails.mongodb.options.connectionPoolSettings.*`. + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.mongodb.options.connectionPoolSettings.maxSize` +| The maximum number of connections in the pool. +| `100` + +| `grails.mongodb.options.connectionPoolSettings.minSize` +| The minimum number of connections in the pool. +| `0` + +| `grails.mongodb.options.connectionPoolSettings.maxWaitTime` +| The maximum time (in milliseconds) a thread will wait for a connection. +| `120000` + +| `grails.mongodb.options.connectionPoolSettings.maxConnectionLifeTime` +| The maximum life time (in milliseconds) of a pooled connection. +| `0` _(unlimited)_ + +| `grails.mongodb.options.connectionPoolSettings.maxConnectionIdleTime` +| The maximum idle time (in milliseconds) of a pooled connection. +| `0` _(unlimited)_ +|=== + +==== Client Options + +These properties are set under `grails.mongodb.options.*`. + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.mongodb.options.readPreference` +| The read preference strategy. +| _(none)_ + +| `grails.mongodb.options.writeConcern` +| The write concern strategy. +| _(none)_ + +| `grails.mongodb.options.readConcern` +| The read concern strategy. +| _(none)_ + +| `grails.mongodb.options.retryWrites` +| Whether to retry write operations on failure. +| _(none)_ + +| `grails.mongodb.options.retryReads` +| Whether to retry read operations on failure. +| _(none)_ + +| `grails.mongodb.options.applicationName` +| The name of the application (used for logging and monitoring). +| _(none)_ +|=== + +==== SSL + +These properties are set under `grails.mongodb.options.sslSettings.*`. + +[cols="3,5,2", options="header"] +|=== +| Property | Description | Default + +| `grails.mongodb.options.sslSettings.enabled` +| Whether SSL is enabled for connections. +| `false` + +| `grails.mongodb.options.sslSettings.invalidHostNameAllowed` +| Whether invalid hostnames are allowed in SSL certificates. +| `false` +|=== + + +