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
019package net.sourceforge.spnego;
020
021import javax.servlet.ServletRequest;
022
023import 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</a> example. 
071 * </p>
072 * 
073 * @author Darwin V. Felix
074 *
075 */
076public 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}