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

[[cas-configuration]]
== Configuration

There are a few configuration options for the CAS plugin.

[NOTE]
====
All of these property overrides must be specified in `grails-app/conf/application.yml` (or `application.groovy`) using the `grails.plugin.springsecurity` suffix, for example

[source,java]
----
grails:
   plugin:
      springsecurity:
         cas:
            serverUrlPrefix: https://cas-server/cas
----
====

[width="100%",options="header"]
|====================
| *Name* | *Default* | *Meaning*
| cas.active | `true` | whether the plugin is enabled (e.g. to disable per-environment)
| cas.serverUrlPrefix | `null`, must be set | the 'root' of all CAS server URLs, e.g. `https://cas-server/cas`
| cas.serverUrlEncoding | 'UTF-8' | encoding for the server URL
| cas.loginUri | `null`, must be set | the login URI, relative to `cas.serverUrlPrefix`, e.g. `/login`
| cas.sendRenew | `false` | if true, ticket validation will only succeed if it was issued from a login form, but will fail if it was issued from a single sign-on session. Analogous to `IS_AUTHENTICATED_FULLY` in Spring Security
| cas.serviceUrl | `null`, must be set | the local application login URL, e.g. `http://localhost:8080/login/cas`
| cas.key | 'grails-spring-security-cas', should be changed | used by `CasAuthenticationProvider` to identify tokens it previously authenticated
| cas.artifactParameter | `'ticket'` | the ticket login url parameter
| cas.serviceParameter | `'service'` | the service login url parameter
| cas.filterProcessesUrl | '/login/cas' | the URL that the filter intercepts for login
| cas.proxyCallbackUrl | `null` | proxy callback url, e.g. 'http://localhost:8080/secure/receptor'. Only needed for proxy tickets, and only meaningful together with `cas.proxyReceptorUrl`
| cas.proxyReceptorUrl | `null` | proxy receptor url, e.g. '/secure/receptor'. Only needed for proxy tickets, and only meaningful together with `cas.proxyCallbackUrl`. When unset, no request is treated as a proxy receptor request
| cas.useSingleSignout | `false` | if `true` a `org.apereo.cas.client.session. SingleSignOutFilter` is registered, and session fixation prevention is disabled (see below)
|====================

[WARNING]
====
Single sign-out and session fixation prevention cannot both be active. CAS maps the service ticket
to the HTTP session id, so if the session is replaced when the user authenticates, the session CAS
later asks the application to invalidate no longer exists and the logout request has no effect.

`cas.useSingleSignout` is therefore opt-in. Enabling it makes the plugin set
`grails.plugin.springsecurity.useSessionFixationPrevention` to `false` and define
`sessionAuthenticationStrategy` accordingly, overriding whatever the core plugin configured, and log
a warning at startup so the trade-off is visible:

[source,groovy]
.grails-app/conf/application.groovy
----
grails.plugin.springsecurity.cas.useSingleSignout = true
----

Leave it off to keep session fixation prevention and handle logout in the application instead.
====
