001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2007 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: SAML2ServiceProviderAdapter.java,v 1.5 2008/08/19 19:11:15 veiming Exp $
026 *
027 */
028
029package com.sun.identity.saml2.plugins;
030
031import com.sun.identity.saml2.common.SAML2Exception;
032import com.sun.identity.saml2.protocol.AuthnRequest;
033import com.sun.identity.saml2.protocol.LogoutRequest;
034import com.sun.identity.saml2.protocol.LogoutResponse;
035import com.sun.identity.saml2.protocol.ManageNameIDRequest;
036import com.sun.identity.saml2.protocol.ManageNameIDResponse;
037import com.sun.identity.saml2.protocol.Response;
038import javax.servlet.http.HttpServletRequest;
039import javax.servlet.http.HttpServletResponse;
040import java.util.Map;
041
042/**
043 * The <code>SAML2ServiceProviderAdapter</code> abstract class provides methods
044 * that could be extended to perform user specific logics during SAMLv2 
045 * protocol processing on the Service Provider side. The implementation class
046 * could be configured on a per service provider basis in the extended
047 * metadata configuration.   
048 * <p>
049 * A singleton instance of this <code>SAML2ServiceProviderAdapter</code>
050 * class will be used per Service Provider during runtime, so make sure 
051 * implementation of the methods are thread safe. 
052 * @supported.all.api
053 */
054
055public abstract class SAML2ServiceProviderAdapter {
056
057    /**
058     * Status code for Single Sign-on success.
059     */
060    public static final int SUCCESS = 0;
061
062    /**
063     * Status code for invalid response from <code>IDP</code>.
064     */
065    public static final int INVALID_RESPONSE = 1;
066
067    /**
068     * Status code for federation failure due to unable to write account 
069     * federation info.
070     */
071    public static final int FEDERATION_FAILED_WRITING_ACCOUNT_INFO = 3;
072
073    /**
074     * Status code for Single Sign-On failure due to internal session error.
075     */
076    public static final int SSO_FAILED_SESSION_ERROR = 4;
077
078    /**
079     * Status code for Single Sign-On failure due attribute mapping error.
080     */
081    public static final int SSO_FAILED_ATTRIBUTE_MAPPING = 5;
082
083    /**
084     * Status code for Single Sign-On failure due to no user mapping.
085     */
086    public static final int SSO_FAILED_NO_USER_MAPPING = 6;
087
088    /**
089     * Status code for Single Sign-On failure due to inactive user account.
090     */
091    public static final int SSO_FAILED_AUTH_USER_INACTIVE = 7;
092
093    /**
094     * Status code for Single Sign-On failure due to locked user account.
095     */
096    public static final int SSO_FAILED_AUTH_USER_LOCKED = 8;
097
098    /**
099     * Status code for Single Sign-On failure due to expired user account.
100     */
101    public static final int SSO_FAILED_AUTH_ACCOUNT_EXPIRED = 9;
102
103    /**
104     * Status code for Single Sign-On failure due to unable to generate 
105     * user session. 
106     */
107    public static final int SSO_FAILED_SESSION_GENERATION = 10;
108
109    /**
110     * Status code for Single Sign-On failure due to unable to retrieve 
111     * meta data. 
112     */
113    public static final int SSO_FAILED_META_DATA_ERROR = 11;
114
115    /**
116     * Constants for hosted entity id parameter
117     */
118    public static final String HOSTED_ENTITY_ID = "HOSTED_ENTITY_ID";
119    
120    /**
121     * Constants for the realm of the hosted entity parameter.
122     */
123    public static final String REALM = "REALM";
124
125    /**
126     * Initializes the federation adapter, this method will only be executed
127     * once after creation of the adapter instance.
128     * @param initParams  initial set of parameters configured in the service
129     *          provider for this adapter. One of the parameters named
130     *          <code>HOSTED_ENTITY_ID</code> refers to the ID of this 
131     *          hosted service provider entity, one of the parameters named
132     *          <code>REALM</code> refers to the realm of the hosted entity.
133     */
134    public abstract void initialize(Map initParams);
135 
136    /**
137     * Invokes before OpenSSO sends the 
138     * Single-Sing-On request to IDP. 
139     * @param hostedEntityID entity ID for the hosted SP
140     * @param idpEntityID entity id for the IDP to which the request will 
141     *          be sent. This will be null in ECP case.
142     * @param realm Realm of the hosted SP.
143     * @param request servlet request
144     * @param response servlet response
145     * @param authnRequest the authentication request to be send to IDP 
146     * @exception SAML2Exception if user want to fail the process.
147     */
148    public void preSingleSignOnRequest(
149        String hostedEntityID, 
150        String idpEntityID,
151        String realm,
152        HttpServletRequest request, 
153        HttpServletResponse response, 
154        AuthnRequest authnRequest)
155    throws SAML2Exception {
156        return;
157    }
158
159
160    /**
161     * Invokes when the <code>FAM</code> received the Single-Sign-On response
162     * from the IDP, this is called before any processing started on SP side.
163     * @param hostedEntityID entity ID for the hosted SP
164     * @param realm Realm of the hosted SP.
165     * @param request servlet request
166     * @param response servlet response
167     * @param authnRequest the original authentication request sent from SP, 
168     *       null if this is IDP initiated SSO.
169     * @param ssoResponse response from IDP 
170     * @param profile protocol profile used, one of the following values: 
171     *     <code>SAML2Constants.HTTP_POST</code>, 
172     *     <code>SAML2Constants.HTTP_ARTIFACT</code>,
173     *     <code>SAML2Constants.PAOS</code>
174     * @exception SAML2Exception if user want to fail the process.
175     */
176    public void preSingleSignOnProcess(
177        String hostedEntityID, 
178        String realm,
179        HttpServletRequest request, 
180        HttpServletResponse response, 
181        AuthnRequest authnRequest, 
182        Response ssoResponse,
183        String profile)
184    throws SAML2Exception {
185        return;
186    }
187
188    /**
189     * Invokes after Single-Sign-On processing succeeded.
190     * @param hostedEntityID Entity ID for the hosted SP
191     * @param realm Realm of the hosted SP.
192     * @param request servlet request
193     * @param response servlet response
194     * @param session user's session
195     * @param authnRequest the original authentication request sent from SP, 
196     *       null if this is IDP initiated SSO.
197     * @param ssoResponse response from IDP 
198     * @param profile protocol profile used, one of the following values: 
199     *     <code>SAML2Constants.HTTP_POST</code>, 
200     *     <code>SAML2Constants.HTTP_ARTIFACT</code>,
201     *     <code>SAML2Constants.PAOS</code>
202     * @param isFederation true if this is federation case, false otherwise.
203     * @return true if browser redirection happened after processing, 
204     *     false otherwise. Default to false. 
205     * @exception SAML2Exception if user want to fail the process.
206     */
207    public boolean postSingleSignOnSuccess(
208        String hostedEntityID, 
209        String realm,
210        HttpServletRequest request, 
211        HttpServletResponse response, 
212        Object session,
213        AuthnRequest authnRequest, 
214        Response ssoResponse,
215        String profile, 
216        boolean isFederation)
217    throws SAML2Exception {
218        return false;
219    }
220
221
222    /**
223     * Invokes after Single Sign-On processing failed.
224     * @param hostedEntityID Entity ID for the hosted SP
225     * @param realm Realm of the hosted SP.
226     * @param request servlet request
227     * @param response servlet response
228     * @param authnRequest the original authentication request sent from SP,
229     *       null if this is IDP initiated SSO.
230     * @param ssoResponse response from IDP 
231     * @param profile protocol profile used, one of the following values: 
232     *     <code>SAML2Constants.HTTP_POST</code>, 
233     *     <code>SAML2Constants.HTTP_ARTIFACT</code>,
234     *     <code>SAML2Constants.PAOS</code>
235     * @param failureCode an integer specifies the failure code. Possible
236     *          failure codes are defined in this interface.
237     * @return true if browser redirection happened, false otherwise. Default to
238     *         false.
239     */
240    public boolean postSingleSignOnFailure(
241        String hostedEntityID,
242        String realm,
243        HttpServletRequest request,
244        HttpServletResponse response,
245        AuthnRequest authnRequest,
246        Response ssoResponse,
247        String profile, 
248        int failureCode) {
249        return false;
250    }
251
252
253    /**
254     * Invokes after new Name Identifier processing succeeded. 
255     * @param hostedEntityID Entity ID for the hosted SP
256     * @param realm Realm of the hosted SP.
257     * @param request servlet request
258     * @param response servlet response
259     * @param userID Universal ID of the user with whom the new name identifier
260     *        request performed
261     * @param idRequest New name identifier request, value will be
262     *                null if the request object is not available
263     * @param idResponse New name identifier response, value will be
264     *          null if the response object is not available
265     * @param binding Binding used for new name identifier request, 
266     *        one of following values:
267     *          <code>SAML2Constants.SOAP</code>,
268     *          <code>SAML2Constants.HTTP_REDIRECT</code>
269     */
270    public void postNewNameIDSuccess(
271        String hostedEntityID,
272        String realm,
273        HttpServletRequest request,
274        HttpServletResponse response,
275        String userID,
276        ManageNameIDRequest idRequest,
277        ManageNameIDResponse idResponse,
278        String binding) {
279        return;
280    }
281
282    /**
283     * Invokes after Terminate Name Identifier processing succeeded. 
284     * @param hostedEntityID Entity ID for the hosted SP
285     * @param realm Realm of the hosted SP.
286     * @param request servlet request
287     * @param response servlet response
288     * @param userID Universal ID of the user with whom name id termination 
289     *        performed.
290     * @param idRequest Terminate name identifier request. 
291     * @param idResponse Terminate name identifier response, value will be
292     *          null if the response object is not available
293     * @param binding binding used for Terminate Name Identifier request, 
294     *      one of following values:
295     *          <code>SAML2Constants.SOAP</code>,
296     *          <code>SAML2Constants.HTTP_REDIRECT</code>
297     */
298    public void postTerminateNameIDSuccess(
299        String hostedEntityID, 
300        String realm,
301        HttpServletRequest request, 
302        HttpServletResponse response,
303        String userID,
304        ManageNameIDRequest idRequest,
305        ManageNameIDResponse idResponse,
306        String binding) {
307        return;
308    }
309
310    /**
311     * Invokes before single logout process started on <code>SP</code> side. 
312     * This method is called before the user session is invalidated on the 
313     * service provider side. 
314     * @param hostedEntityID Entity ID for the hosted SP
315     * @param realm Realm of the hosted SP.
316     * @param request servlet request
317     * @param response servlet response
318     * @param userID universal ID of the user 
319     * @param logoutRequest single logout request object 
320     * @param logoutResponse single logout response, value will be
321     *          null if the response object is not available
322     * @param binding binding used for Single Logout request, 
323     *      one of following values:
324     *          <code>SAML2Constants.SOAP</code>,
325     *          <code>SAML2Constants.HTTP_REDIRECT</code>
326     * @exception SAML2Exception if user want to fail the process.
327     */
328    public void preSingleLogoutProcess(
329        String hostedEntityID,
330        String realm,
331        HttpServletRequest request,
332        HttpServletResponse response,
333        String userID,
334        LogoutRequest logoutRequest,
335        LogoutResponse logoutResponse,
336        String binding) 
337    throws SAML2Exception {
338        return;
339    }
340
341    /**
342     * Invokes after single logout process succeeded, i.e. user session 
343     * has been invalidated.
344     * @param hostedEntityID Entity ID for the hosted SP
345     * @param realm Realm of the hosted SP.
346     * @param request servlet request
347     * @param response servlet response
348     * @param userID universal ID of the user 
349     * @param logoutRequest single logout request, value will be
350     *          null if the request object is not available
351     * @param logoutResponse single logout response, value will be
352     *          null if the response object is not available
353     * @param binding binding used for Single Logout request, 
354     *      one of following values:
355     *          <code>SAML2Constants.SOAP</code>,
356     *          <code>SAML2Constants.HTTP_REDIRECT</code>
357     */
358    public void postSingleLogoutSuccess(
359        String hostedEntityID, 
360        String realm,
361        HttpServletRequest request, 
362        HttpServletResponse response, 
363        String userID,
364        LogoutRequest logoutRequest, 
365        LogoutResponse logoutResponse,
366        String binding) {
367        return;
368    }
369}