org.springframework.security.cas.authentication.StatelessTicketCache.java Source code

Introduction

Here is the source code for org.springframework.security.cas.authentication.StatelessTicketCache.java

Source

/*
 * Copyright 2004 Acegi Technology Pty Limited
 *
 * Licensed 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.
 */

package org.springframework.security.cas.authentication;

/**
 * Caches CAS service tickets and CAS proxy tickets for stateless connections.
 *
 * <p>
 * When a service ticket or proxy ticket is validated against the CAS server, it is unable
 * to be used again. Most types of callers are stateful and are associated with a given
 * <code>HttpSession</code>. This allows the affirmative CAS validation outcome to be
 * stored in the <code>HttpSession</code>, meaning the removal of the ticket from the CAS
 * server is not an issue.
 * </p>
 *
 * <P>
 * Stateless callers, such as remoting protocols, cannot take advantage of
 * <code>HttpSession</code>. If the stateless caller is located a significant network
 * distance from the CAS server, acquiring a fresh service ticket or proxy ticket for each
 * invocation would be expensive.
 * </p>
 *
 * <P>
 * To avoid this issue with stateless callers, it is expected stateless callers will
 * obtain a single service ticket or proxy ticket, and then present this same ticket to
 * the Spring Security secured application on each occasion. As no
 * <code>HttpSession</code> is available for such callers, the affirmative CAS validation
 * outcome cannot be stored in this location.
 * </p>
 *
 * <P>
 * The <code>StatelessTicketCache</code> enables the service tickets and proxy tickets
 * belonging to stateless callers to be placed in a cache. This in-memory cache stores the
 * <code>CasAuthenticationToken</code>, effectively providing the same capability as a
 * <code>HttpSession</code> with the ticket identifier being the key rather than a session
 * identifier.
 * </p>
 *
 * <P>
 * Implementations should provide a reasonable timeout on stored entries, such that the
 * stateless caller are not required to unnecessarily acquire fresh CAS service tickets or
 * proxy tickets.
 * </p>
 *
 * @author Ben Alex
 */
public interface StatelessTicketCache {
    // ~ Methods ================================================================

    /**
     * Retrieves the <code>CasAuthenticationToken</code> associated with the specified
     * ticket.
     *
     * <P>
     * If not found, returns a <code>null</code><code>CasAuthenticationToken</code>.
     * </p>
     *
     * @return the fully populated authentication token
     */
    CasAuthenticationToken getByTicketId(String serviceTicket);

    /**
     * Adds the specified <code>CasAuthenticationToken</code> to the cache.
     *
     * <P>
     * The {@link CasAuthenticationToken#getCredentials()} method is used to retrieve the
     * service ticket number.
     * </p>
     *
     * @param token to be added to the cache
     */
    void putTicketInCache(CasAuthenticationToken token);

    /**
     * Removes the specified ticket from the cache, as per
     * {@link #removeTicketFromCache(String)}.
     *
     * <P>
     * Implementations should use {@link CasAuthenticationToken#getCredentials()} to
     * obtain the ticket and then delegate to the
     * {@link #removeTicketFromCache(String)} method.
     * </p>
     *
     * @param token to be removed
     */
    void removeTicketFromCache(CasAuthenticationToken token);

    /**
     * Removes the specified ticket from the cache, meaning that future calls will require
     * a new service ticket.
     *
     * <P>
     * This is in case applications wish to provide a session termination capability for
     * their stateless clients.
     * </p>
     *
     * @param serviceTicket to be removed
     */
    void removeTicketFromCache(String serviceTicket);
}