a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * The contents of this file are subject to the terms
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * of the Common Development and Distribution License
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * (the License). You may not use this file except in
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * compliance with the License.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * You can obtain a copy of the License at
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * https://opensso.dev.java.net/public/CDDLv1.0.html or
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * See the License for the specific language governing
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * permission and limitations under the License.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * When distributing Covered Code, include this CDDL
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Header Notice in each file and include the License file
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * If applicable, add the following below the CDDL Header,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * with the fields enclosed by brackets [] replaced by
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * your own identifying information:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * "Portions Copyrighted [year] [name of copyright owner]"
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * $Id: SessionProvider.java,v 1.7 2008/06/25 05:47:28 qcheng Exp $
6cf99bcf5206a0fcc9dd9296fc46ac28c3fe8adePeter Major * Portions Copyrighted 2014-2016 ForgeRock AS.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Interface used for creating sessions, and for accessing session
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * information.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @supported.all.api
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This constant string is used in the implementation and calling
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * of the first method for passing a realm name in a map.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This constant string is used in the implementation and calling
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * of the first method for passing a principal name in a map.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This constant string is used in the implementation and calling
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * of the first method for passing an authentication level in a map.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This constant string is used as a property name to indicate
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * the authentication method. Typically it is used as the second
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * name parameter in the <code>getProperty</code> method.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This constant string is used as a property name to indicate
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * the authentication instant. Typically it is used as the second
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * name parameter in the <code>getProperty</code> method.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This constant string is used as a property name to indicate
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * the client host.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This constant string is used as a property name to indicate
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * the client hostname.
5782a5801b205a5f4225dde7fd580923431fa8b3Peter Major * The name of the request attribute under which the user attributes shall be stored. This is used by the
5782a5801b205a5f4225dde7fd580923431fa8b3Peter Major * Federation authentication module (hosted SP scenario) when dynamic account creation is enabled.
5782a5801b205a5f4225dde7fd580923431fa8b3Peter Major String ATTR_MAP = "org.forgerock.openam.authentication.userAttrMap";
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Meaningful only for Service Provider side, the implementation of this
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * method will create a local session for the local user identified by
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * the information in the map. The underline mechanism of the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * session creation and management is application specific.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * For example, it could be cookie setting or URL rewriting, which
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * is expected to be done by the implementation of this method.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Note that only the first input parameter is mandatory. Normally,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * at least one of the last two parameters should not be null
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param info a Map with keys and values being of type String; The
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * keys will include <code>SessionProvider.PRINCIPAL_NAME</code>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * (returned from <code>SPAccountMapper</code>),
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * <code>SessionProvider.REALM</code>,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * <code>SessionProvider.AUTH_LEVEL</code>,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * <code>SessionProvider.AUTH_INSTANT</code>, and may include
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * <code>"resourceOffering"</code> and/or <code>"idpEntityID"</code>;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * The implementation of this method could choose to set some of
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * the information contained in the map into the newly created
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Session by calling <code>setProperty()</code>, later the target
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * application may consume the information.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param request the <code>HttpServletRequesa</code>t the user made to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * initiate the Single Sign On; Note that it should be the initial
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * request coming from the browser as opposed to the possible
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * subsequent back-channel HTTP request for delivering
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * SOAP message.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param response the <code>HttpServletResponse</code> that will be sent
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * to the user (for example it could be used to set a cookie).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param targetApplication the original resource that was requested
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * as the target of the Single Sign On by the end user; If needed,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * this String could be modified, e.g., by appending query
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * string(s) or by URL rewriting, hence this is an in/out parameter.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return the newly created local user session.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws SessionException if an error occurred during session creation.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns the corresponding session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * May be used by both SP and IDP side for getting an existing
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * session given an session ID.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param sessionID the unique session handle.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return the corresponding session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws SessionException if an error occurred during session
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * retrieval.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns the corresponding session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * May be used by both SP and IDP side for getting an existing
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * session given a browser initiated HTTP request.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param request the browser initiated HTTP request.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return the corresponding session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws SessionException if an error occurred during session
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * retrieval.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public Object getSession(HttpServletRequest request)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * May be used by both SP and IDP side to invalidate a session.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * In case of SLO with SOAP, the last two input parameters
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * would have to be null
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param session the session to be invalidated
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param request the browser initiated HTTP request.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param response the HTTP response going back to browser.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws SessionException if an error occurred during session
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * retrieval.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns <code>true</code> if the session is valid.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This is useful for toolkit clean-up thread.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param session Session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return <code>true</code> if the session is valid.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns session ID.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * The returned session ID should be unique and not
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * change during the lifetime of this session
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return session ID.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns princiapl name, or user name given the session
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param session Session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return principal name, or user name.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws SessionException if getting the principal name
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * causes an error.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Stores a property in the session object. This is an
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * optional method.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param session the session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param name the property name.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param values the property values.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws UnsupportedOperationException if this method
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * is not supported.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws SessionException if setting the property in
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * the session causes an error.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster ) throws UnsupportedOperationException, SessionException;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns property value of a session object. This
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * is an optional method.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param session the session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param name the property name.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return the property values.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws UnsupportedOperationException if this method
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * is not supported.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws SessionException if getting the property from
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * the session causes an error.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public String[] getProperty(Object session, String name)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster throws UnsupportedOperationException, SessionException;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns rewritten URL.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Rewrites an URL with session information in case
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * cookie setting is not supported.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param session the session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param URL the URL to be rewritten.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return the rewritten URL.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws SessionException if rewritting the URL
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * causes an error.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public String rewriteURL(Object session, String URL)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Registers a listener for the session. This is an optional
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param session the session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param listener listener for the session invalidation event.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws UnsupportedOperationException if this method
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * is not supported.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @throws SessionException if adding the listener in the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * session causes an error.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public void addListener(Object session, SessionListener listener)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster throws UnsupportedOperationException, SessionException;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Sets a load balancer cookie in the suppled HTTP response. The load
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * balancer cookie's value is set per server instance and is used to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * support sticky load balancing.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param response the <code>HttpServletResponse</code> that will be sent
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * to the user.
6cf99bcf5206a0fcc9dd9296fc46ac28c3fe8adePeter Major public void setLoadBalancerCookie(HttpServletRequest request, HttpServletResponse response);
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns the time left for this session in seconds.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param session Session object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return The time left for this session.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @exception A SessionException is thrown if the session reached its maximum
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * session time, or the session was destroyed, or there was an error during
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * communication with session service.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public long getTimeLeft(Object session) throws SessionException;