001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: SessionProvider.java,v 1.7 2008/06/25 05:47:28 qcheng Exp $
026 *
027 * Portions Copyrighted 2014 ForgeRock AS
028 */
029
030package com.sun.identity.plugin.session;
031
032import java.util.Map;
033import javax.servlet.http.HttpServletRequest;
034import javax.servlet.http.HttpServletResponse;
035
036/**
037 * Interface used for creating sessions, and for accessing session
038 * information.
039 *
040 * @supported.all.api
041 */
042public interface SessionProvider {
043
044    /**
045     * This constant string is used in the implementation and calling
046     * of the first method for passing a realm name in a map.
047     */
048    String REALM = "realm";
049
050    /**
051     * This constant string is used in the implementation and calling
052     * of the first method for passing a principal name in a map.
053     */
054    String PRINCIPAL_NAME = "principalName";
055
056    /**
057     * This constant string is used in the implementation and calling
058     * of the first method for passing an authentication level in a map.
059     */
060    String AUTH_LEVEL = "AuthLevel";
061
062    /**
063     * This constant string is used as a property name to indicate
064     * the authentication method. Typically it is used as the second
065     * name parameter in the <code>getProperty</code> method.
066     */
067    String AUTH_METHOD = "authMethod";
068
069    /**
070     * This constant string is used as a property name to indicate
071     * the authentication instant. Typically it is used as the second
072     * name parameter in the <code>getProperty</code> method.
073     */
074    String AUTH_INSTANT = "authInstant";
075  
076    /**
077     * This constant string is used as a property name to indicate
078     * the client host.
079     */
080    String HOST = "Host";
081
082    /**
083     * This constant string is used as a property name to indicate
084     * the client hostname.
085     */
086    String HOST_NAME = "HostName";
087
088    /**
089     * The name of the request attribute under which the user attributes shall be stored. This is used by the
090     * Federation authentication module (hosted SP scenario) when dynamic account creation is enabled.
091     */
092    String ATTR_MAP = "org.forgerock.openam.authentication.userAttrMap";
093
094    /** 
095     * Meaningful only for Service Provider side, the implementation of this
096     * method will create a local session for the local user identified by
097     * the information in the map. The underline mechanism of the
098     * session creation and management is application specific.
099     * For example, it could be cookie setting or URL rewriting, which 
100     * is expected to be done by the implementation of this method.
101     * Note that only the first input parameter is mandatory. Normally,
102     * at least one of the last two parameters should not be null
103     * 
104     * @param info a Map with keys and values being of type String; The
105     *        keys will include <code>SessionProvider.PRINCIPAL_NAME</code>
106     *        (returned from <code>SPAccountMapper</code>),
107     *        <code>SessionProvider.REALM</code>, 
108     *        <code>SessionProvider.AUTH_LEVEL</code>, 
109     *        <code>SessionProvider.AUTH_INSTANT</code>, and may include
110     *        <code>"resourceOffering"</code> and/or <code>"idpEntityID"</code>;
111     *        The implementation of this method could choose to set some of
112     *        the information contained in the map into the newly created
113     *        Session by calling <code>setProperty()</code>, later the target
114     *        application may consume the information. 
115     * @param request the <code>HttpServletRequesa</code>t the user made to
116     *        initiate the Single Sign On; Note that it should be the initial
117     *        request coming from the browser as opposed to the possible
118     *        subsequent back-channel HTTP request for delivering
119     *        SOAP message.
120     * @param response the <code>HttpServletResponse</code> that will be sent
121     *        to the user (for example it could be used to set a cookie).
122     * @param targetApplication the original resource that was requested
123     *        as the target of the Single Sign On by the end user; If needed,
124     *        this String could be modified, e.g., by appending query
125     *        string(s) or by URL rewriting, hence this is an in/out parameter.
126     * @return the newly created local user session.
127     * @throws SessionException if an error occurred during session creation.
128     */ 
129    public Object createSession(
130        Map info,                       // in
131        HttpServletRequest request,     // in
132        HttpServletResponse response,   // in/out
133        StringBuffer targetApplication  // in/out
134    ) throws SessionException;
135
136    /**
137     * Returns the corresponding session object.
138     * May be used by both SP and IDP side for getting an existing
139     * session given an session ID.
140     * @param sessionID the unique session handle.
141     * @return the corresponding session object.
142     * @throws SessionException if an error occurred during session
143     * retrieval.
144     */
145    public Object getSession(String sessionID)
146        throws SessionException;
147
148    /**
149     * Returns the corresponding session object.
150     * May be used by both SP and IDP side for getting an existing
151     * session given a browser initiated HTTP request.
152     * @param request the browser initiated HTTP request.
153     * @return the corresponding session object.
154     * @throws SessionException if an error occurred during session
155     * retrieval.
156     */
157    public Object getSession(HttpServletRequest request)
158        throws SessionException;
159
160    /**
161     * May be used by both SP and IDP side to invalidate a session.
162     * In case of SLO with SOAP, the last two input parameters
163     * would have to be null
164     * @param session the session to be invalidated
165     * @param request the browser initiated HTTP request.
166     * @param response the HTTP response going back to browser.
167     * @throws SessionException if an error occurred during session
168     * retrieval.     
169     */
170    public void invalidateSession(
171        Object session,
172        HttpServletRequest request,   // optional input
173        HttpServletResponse response  // optional input
174    ) throws SessionException;
175
176    /**
177     * Returns <code>true</code> if the session is valid.
178     * This is useful for toolkit clean-up thread.
179     *
180     * @param session Session object.
181     * @return <code>true</code> if the session is valid.
182     */
183    public boolean isValid(Object session)
184        throws SessionException;
185
186    /**
187     * Returns session ID.
188     * The returned session ID should be unique and not 
189     * change during the lifetime of this session
190     *
191     * @return session ID.
192     */
193    public String getSessionID(Object session);
194
195    /**
196     * Returns princiapl name, or user name given the session
197     * object. 
198     * @param session Session object.
199     * @return principal name, or user name.
200     * @throws SessionException if getting the principal name
201     * causes an error.
202     */
203    public String getPrincipalName(Object session)
204        throws SessionException;
205        
206    /**
207     * Stores a property in the session object. This is an
208     * optional method.
209     *
210     * @param session the session object.
211     * @param name the property name.
212     * @param values the property values.
213     * @throws UnsupportedOperationException if this method
214     * is not supported.
215     * @throws SessionException if setting the property in
216     * the session causes an error.
217     */
218    public void setProperty(
219        Object session,
220        String name,
221        String[] values
222    ) throws UnsupportedOperationException, SessionException;
223
224    /**
225     * Returns property value of a session object. This
226     * is an optional method.
227     *
228     * @param session the session object.
229     * @param name the property name.
230     * @return the property values.
231     * @throws UnsupportedOperationException if this method
232     * is not supported.
233     * @throws SessionException if getting the property from
234     * the session causes an error.
235     */
236    public String[] getProperty(Object session, String name)
237        throws UnsupportedOperationException, SessionException;
238
239    /**
240     * Returns rewritten URL.
241     * Rewrites an URL with session information in case
242     * cookie setting is not supported.
243     *
244     * @param session the session object.
245     * @param URL the URL to be rewritten.
246     * @return the rewritten URL.
247     * @throws SessionException if rewritting the URL
248     * causes an error.
249     */
250    public String rewriteURL(Object session, String URL)
251        throws SessionException;
252    
253    /**
254     * Registers a listener for the session. This is an optional
255     * method.
256     * @param session the session object.
257     * @param listener listener for the session invalidation event.
258     * @throws UnsupportedOperationException if this method
259     * is not supported.
260     * @throws SessionException if adding the listener in the
261     * session causes an error.
262     */
263    public void addListener(Object session, SessionListener listener)
264        throws UnsupportedOperationException, SessionException;
265    
266    /**
267     * Sets a load balancer cookie in the suppled HTTP response. The load
268     * balancer cookie's value is set per server instance and is used to
269     * support sticky load balancing.
270     * 
271     * @param response the <code>HttpServletResponse</code> that will be sent
272     *        to the user.
273     */
274    public void setLoadBalancerCookie(HttpServletResponse response);
275
276    /**
277     * Returns the time left for this session in seconds.
278     * @param session Session object.
279     * @return The time left for this session.
280     * @exception A SessionException is thrown if the session reached its maximum
281     * session time, or the session was destroyed, or there was an error during
282     * communication with session service.
283     */
284    public long getTimeLeft(Object session) throws SessionException; 
285}
286




























































Copyright © 2010-2017, ForgeRock All Rights Reserved.