1. Introduction

The Grails Cookie plugin makes dealing with cookies easy in your Grails application. It provides an injectable CookieService and Groovy extension methods on HttpServletRequest and HttpServletResponse to get, set, and delete cookies with a single line of code.

The plugin is fully RFC 6265 compliant.

1.1. Quick Start

Add the plugin dependency to your build.gradle:

dependencies {
    implementation 'io.github.gpc:grails-cookie:4.0.0-SNAPSHOT'
}
Replace 4.0.0-SNAPSHOT with the latest version available on Maven Central.

1.1.1. Snapshot builds

Snapshot versions are published to Maven Central Snapshots. To use a snapshot, add the repository:

// settings.gradle
dependencyResolutionManagement {
    repositories {
        maven { url = 'https://central.sonatype.com/repository/maven-snapshots/' }
        mavenCentral()
    }
}

Then add the dependency:

dependencies {
    implementation 'io.github.gpc:grails-cookie:4.0.0-SNAPSHOT'
}

1.2. Compatibility

Plugin version Grails version Java Groovy

4.x

8.0.x

21+

5.x

3.x

7.0.x

17+

4.x

2.x

3.0.x

7+

2.x

1.x

2.0.x

7+

2.x

2. Usage

Two equivalent APIs are available everywhere in a Grails application: extension methods on request and response objects, and an injectable CookieService.

2.1. Extension methods on request / response

The plugin adds several convenient methods to HttpServletRequest and HttpServletResponse.

2.1.1. Setting Cookies

// Set a cookie with default settings
// (default age = 30 days, HttpOnly = true, path = context path)
response.setCookie('username', 'cookieUser123')

// Set with explicit age (seconds), path, domain, secure, and httpOnly
response.setCookie('username', 'cookieUser123', 604800, '/', null, false, true)

// Set via named parameters
response.setCookie([
    name: 'username',
    value: 'cookieUser123',
    maxAge: 604800,
    secure: true,
    httpOnly: true
])

2.1.2. Getting Cookies

// Get the value of a cookie
String value = request.getCookie('username') // returns 'cookieUser123' or null

// Find the full Cookie object
Cookie cookie = request.findCookie('username')

2.1.3. Deleting Cookies

// Delete a cookie by name
response.deleteCookie('username')

// Delete with specific path and domain
response.deleteCookie('username', '/path', '.example.com')

// Delete an existing Cookie object
response.deleteCookie(existingCookieObject)

2.2. Injectable CookieService

The CookieService provides the same functionality as the extension methods and can be injected into your services, controllers, or other Spring beans.

class MyService {
    CookieService cookieService

    void doSomething() {
        // Set a cookie
        cookieService.setCookie('username', 'cookieUser123', 604800)

        // Get a cookie value
        String value = cookieService.getCookie('username')

        // Delete a cookie
        cookieService.deleteCookie('username')
    }
}

The CookieService has the same method signatures as the response/request extension methods.

3. Configuration

All configuration keys are optional. Defaults are intentionally safe for most applications. Configuration is typically specified in grails-app/conf/application.yml.

Default Max-Age for cookies in seconds.

  • null or unset → 30 days (2,592,000 seconds)

  • -1 → session cookie (removed when browser closes)

  • 0 is reserved for deletion — do not use as a default

grails:
  plugins:
    cookie:
      cookieage:
        default: 86400   # 1 day

Determines how the cookie Path attribute is set when none is supplied explicitly.

Value Behavior

context

Web application context path (default)

root

/ (Root path)

current

No path set (browser uses the current request path)

 
grails:
  plugins:
    cookie:
      path:
        defaultStrategy: root

Default Secure flag for cookies.

If null or unset, it mirrors request.isSecure() (i.e., cookies are secure when the connection is HTTPS).

Boolean values (true or false)

grails:
  plugins:
    cookie:
      secure:
        default: true

Default HttpOnly flag for cookies. Defaults to true. Accepts boolean and string boolean values.

grails:
  plugins:
    cookie:
      httpOnly:
        default: false