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.