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 */ 028 029package com.sun.identity.plugin.session; 030 031import java.util.Map; 032import javax.servlet.http.HttpServletRequest; 033import javax.servlet.http.HttpServletResponse; 034 035/** 036 * Interface used for creating sessions, and for accessing session 037 * information. 038 * 039 * @supported.all.api 040 */ 041public interface SessionProvider { 042 043 /** 044 * This constant string is used in the implementation and calling 045 * of the first method for passing a realm name in a map. 046 */ 047 String REALM = "realm"; 048 049 /** 050 * This constant string is used in the implementation and calling 051 * of the first method for passing a principal name in a map. 052 */ 053 String PRINCIPAL_NAME = "principalName"; 054 055 /** 056 * This constant string is used in the implementation and calling 057 * of the first method for passing an authentication level in a map. 058 */ 059 String AUTH_LEVEL = "AuthLevel"; 060 061 /** 062 * This constant string is used as a property name to indicate 063 * the authentication method. Typically it is used as the second 064 * name parameter in the <code>getProperty</code> method. 065 */ 066 String AUTH_METHOD = "authMethod"; 067 068 /** 069 * This constant string is used as a property name to indicate 070 * the authentication instant. Typically it is used as the second 071 * name parameter in the <code>getProperty</code> method. 072 */ 073 String AUTH_INSTANT = "authInstant"; 074 075 /** 076 * This constant string is used as a property name to indicate 077 * the client host. 078 */ 079 String HOST = "Host"; 080 081 /** 082 * This constant string is used as a property name to indicate 083 * the client hostname. 084 */ 085 String HOST_NAME = "HostName"; 086 087 /** 088 * Meaningful only for Service Provider side, the implementation of this 089 * method will create a local session for the local user identified by 090 * the information in the map. The underline mechanism of the 091 * session creation and management is application specific. 092 * For example, it could be cookie setting or URL rewriting, which 093 * is expected to be done by the implementation of this method. 094 * Note that only the first input parameter is mandatory. Normally, 095 * at least one of the last two parameters should not be null 096 * 097 * @param info a Map with keys and values being of type String; The 098 * keys will include <code>SessionProvider.PRINCIPAL_NAME</code> 099 * (returned from <code>SPAccountMapper</code>), 100 * <code>SessionProvider.REALM</code>, 101 * <code>SessionProvider.AUTH_LEVEL</code>, 102 * <code>SessionProvider.AUTH_INSTANT</code>, and may include 103 * <code>"resourceOffering"</code> and/or <code>"idpEntityID"</code>; 104 * The implementation of this method could choose to set some of 105 * the information contained in the map into the newly created 106 * Session by calling <code>setProperty()</code>, later the target 107 * application may consume the information. 108 * @param request the <code>HttpServletRequesa</code>t the user made to 109 * initiate the Single Sign On; Note that it should be the initial 110 * request coming from the browser as opposed to the possible 111 * subsequent back-channel HTTP request for delivering 112 * SOAP message. 113 * @param response the <code>HttpServletResponse</code> that will be sent 114 * to the user (for example it could be used to set a cookie). 115 * @param targetApplication the original resource that was requested 116 * as the target of the Single Sign On by the end user; If needed, 117 * this String could be modified, e.g., by appending query 118 * string(s) or by URL rewriting, hence this is an in/out parameter. 119 * @return the newly created local user session. 120 * @throws SessionException if an error occurred during session creation. 121 */ 122 public Object createSession( 123 Map info, // in 124 HttpServletRequest request, // in 125 HttpServletResponse response, // in/out 126 StringBuffer targetApplication // in/out 127 ) throws SessionException; 128 129 /** 130 * Returns the corresponding session object. 131 * May be used by both SP and IDP side for getting an existing 132 * session given an session ID. 133 * @param sessionID the unique session handle. 134 * @return the corresponding session object. 135 * @throws SessionException if an error occurred during session 136 * retrieval. 137 */ 138 public Object getSession(String sessionID) 139 throws SessionException; 140 141 /** 142 * Returns the corresponding session object. 143 * May be used by both SP and IDP side for getting an existing 144 * session given a browser initiated HTTP request. 145 * @param request the browser initiated HTTP request. 146 * @return the corresponding session object. 147 * @throws SessionException if an error occurred during session 148 * retrieval. 149 */ 150 public Object getSession(HttpServletRequest request) 151 throws SessionException; 152 153 /** 154 * May be used by both SP and IDP side to invalidate a session. 155 * In case of SLO with SOAP, the last two input parameters 156 * would have to be null 157 * @param session the session to be invalidated 158 * @param request the browser initiated HTTP request. 159 * @param response the HTTP response going back to browser. 160 * @throws SessionException if an error occurred during session 161 * retrieval. 162 */ 163 public void invalidateSession( 164 Object session, 165 HttpServletRequest request, // optional input 166 HttpServletResponse response // optional input 167 ) throws SessionException; 168 169 /** 170 * Returns <code>true</code> if the session is valid. 171 * This is useful for toolkit clean-up thread. 172 * 173 * @param session Session object. 174 * @return <code>true</code> if the session is valid. 175 */ 176 public boolean isValid(Object session) 177 throws SessionException; 178 179 /** 180 * Returns session ID. 181 * The returned session ID should be unique and not 182 * change during the lifetime of this session 183 * 184 * @return session ID. 185 */ 186 public String getSessionID(Object session); 187 188 /** 189 * Returns princiapl name, or user name given the session 190 * object. 191 * @param session Session object. 192 * @return principal name, or user name. 193 * @throws SessionException if getting the principal name 194 * causes an error. 195 */ 196 public String getPrincipalName(Object session) 197 throws SessionException; 198 199 /** 200 * Stores a property in the session object. This is an 201 * optional method. 202 * 203 * @param session the session object. 204 * @param name the property name. 205 * @param values the property values. 206 * @throws UnsupportedOperationException if this method 207 * is not supported. 208 * @throws SessionException if setting the property in 209 * the session causes an error. 210 */ 211 public void setProperty( 212 Object session, 213 String name, 214 String[] values 215 ) throws UnsupportedOperationException, SessionException; 216 217 /** 218 * Returns property value of a session object. This 219 * is an optional method. 220 * 221 * @param session the session object. 222 * @param name the property name. 223 * @return the property values. 224 * @throws UnsupportedOperationException if this method 225 * is not supported. 226 * @throws SessionException if getting the property from 227 * the session causes an error. 228 */ 229 public String[] getProperty(Object session, String name) 230 throws UnsupportedOperationException, SessionException; 231 232 /** 233 * Returns rewritten URL. 234 * Rewrites an URL with session information in case 235 * cookie setting is not supported. 236 * 237 * @param session the session object. 238 * @param URL the URL to be rewritten. 239 * @return the rewritten URL. 240 * @throws SessionException if rewritting the URL 241 * causes an error. 242 */ 243 public String rewriteURL(Object session, String URL) 244 throws SessionException; 245 246 /** 247 * Registers a listener for the session. This is an optional 248 * method. 249 * @param session the session object. 250 * @param listener listener for the session invalidation event. 251 * @throws UnsupportedOperationException if this method 252 * is not supported. 253 * @throws SessionException if adding the listener in the 254 * session causes an error. 255 */ 256 public void addListener(Object session, SessionListener listener) 257 throws UnsupportedOperationException, SessionException; 258 259 /** 260 * Sets a load balancer cookie in the suppled HTTP response. The load 261 * balancer cookie's value is set per server instance and is used to 262 * support sticky load balancing. 263 * 264 * @param response the <code>HttpServletResponse</code> that will be sent 265 * to the user. 266 */ 267 public void setLoadBalancerCookie(HttpServletResponse response); 268 269 /** 270 * Returns the time left for this session in seconds. 271 * @param session Session object. 272 * @return The time left for this session. 273 * @exception A SessionException is thrown if the session reached its maximum 274 * session time, or the session was destroyed, or there was an error during 275 * communication with session service. 276 */ 277 public long getTimeLeft(Object session) throws SessionException; 278} 279