001    /** 
002     * Copyright (C) 2009 "Darwin V. Felix" <darwinfelix@users.sourceforge.net>
003     * 
004     * This library is free software; you can redistribute it and/or
005     * modify it under the terms of the GNU Lesser General Public
006     * License as published by the Free Software Foundation; either
007     * version 2.1 of the License, or (at your option) any later version.
008     * 
009     * This library is distributed in the hope that it will be useful,
010     * but WITHOUT ANY WARRANTY; without even the implied warranty of
011     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
012     * Lesser General Public License for more details.
013     * 
014     * You should have received a copy of the GNU Lesser General Public
015     * License along with this library; if not, write to the Free Software
016     * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017     */
018    
019    package net.sourceforge.spnego;
020    
021    import javax.servlet.ServletRequest;
022    
023    import org.ietf.jgss.GSSCredential;
024    
025    /**
026     * The default installation of Internet Explorer and Active Directory 
027     * allow the user's/requester's credential to be delegated.
028     *
029     * <p>
030     * By default, {@link SpnegoHttpURLConnection} has delegation set 
031     * to false. To allow delegation, call the <code>requestCredDeleg</code> 
032     * method on the <code>SpnegoHttpURLConnection</code> instance.
033     * </p>
034     * 
035     * <p>
036     * Also, the server/service's pre-authentication account must be specified as 
037     * "Account is trusted for delegation" in Active Directory.
038     * </p>
039     * 
040     * <p>
041     * Finally, the server/service's spnego servlet init params must be specified 
042     * to allow credential delegation by setting the property 
043     * <code>spnego.allow.delegation</code> to true (false by default).
044     * </p>
045     * 
046     * <p>
047     * Custom client programs may request their credential to be delegated 
048     * by calling the <code>requestCredDeleg</code> on their instance of GSSContext.
049     * </p>
050     * 
051     * <p>
052     * Java Application Servers can obtain the delegated credential by casting 
053     * the HTTP request.
054     * </p>
055     * 
056     * <p>
057     * <b>Example usage:</b>
058     * <pre>
059     *     if (request instanceof DelegateServletRequest) {
060     *         DelegateServletRequest dsr = (DelegateServletRequest) request;
061     *         GSSCredential creds = dsr.getDelegatedCredential();
062     *         ...
063     *     }
064     * </pre>
065     * </p>
066     * 
067     * <p>
068     * To see a working example and instructions, take a look at the 
069     * <a href="http://spnego.sourceforge.net/credential_delegation.html" 
070     * target="_blank">credential delegation example</a>. 
071     * </p>
072     * 
073     * @author Darwin V. Felix
074     *
075     */
076    public interface DelegateServletRequest extends ServletRequest {
077    
078        /**
079         * Returns the requester's delegated credential.
080         * 
081         * <p>
082         * Returns null if request has no delegated credential 
083         * or if delegated credentials are not supported.
084         * </p>
085         * 
086         * @return delegated credential or null
087         */
088        GSSCredential getDelegatedCredential();
089    }