////
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-usage]]
== Usage

[NOTE]
====
Configuring your CAS server is beyond the scope of this document. There are many different approaches and this will most likely be done by IT staff. It's assumed here that you already have a running CAS server.
====

https://apereo.github.io/cas[CAS] is a popular single sign-on implementation. It's open source and has an Apache-like license, and is easy to get started with but is also highly configurable. In addition it has clients written in Java, .Net, PHP, Perl, and other languages.

=== Installation

There isn't much that you need to do in your application to be a CAS client. Add a dependency in `build.gradle` for this plugin:

[source,groovy]
[subs="attributes"]
.build.gradle
----
dependencies {
   ...
   implementation 'org.apache.grails:grails-spring-security-cas'
   ...
----

then configure any required parameters and whatever optional parameters you want in application.yml or application.groovy. These are described in detail in the <<configuration>> section but typically you only need to set these properties:

[source,yaml]
.grails-app/conf/application.yml
----
grails:
    plugin:
        springsecurity:
            cas:
                loginUri: /login
                serviceUrl: http://localhost:8080/login/cas
                serverUrlPrefix: https://your-cas-server/cas
                proxyCallbackUrl: http://localhost:8080/secure/receptor
                proxyReceptorUrl: /secure/receptor
----

=== Single Signout

Single signout enables signing out of all CAS-managed applications with one logout. It is opt-in, because enabling it disables session fixation prevention - CAS maps the service ticket to the HTTP session id, so a logout request cannot be matched to a session that was replaced when the user authenticated:

[source,java]
----
grails:
   plugin:
      springsecurity:
         cas:
            useSingleSignout: true
----

The plugin prints and logs a warning at startup when it is enabled, so the trade-off is visible.

It works best when combined with the `afterLogoutUrl` parameter, for example:

[source,java]
----
grails:
   plugin:
      springsecurity:
         logout:
            afterLogoutUrl: https://your-cas-server/cas/logout?url=http://localhost:8080/
----

With this configuration, when a user logs out locally by navigating to `/logout/` they'll then be redirected to the CAS server's logout URL. This request includes a local URL to redirect back afterwards. When the whole process is finished they'll be logged out locally and at the CAS server, so subsequent secure URLs at the local server or other CAS-managed servers will require a new login.

To go back to the default and leave the single signout filter unregistered, keeping session fixation
prevention in place, set it to `false` or remove the setting:

[source,java]
----
grails:
   plugin:
      springsecurity:
         cas:
            useSingleSignout: false
----
