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: FederationSPAdapter.java,v 1.4 2008/06/25 05:46:50 qcheng Exp $
026 *
027 */
028
029package com.sun.identity.federation.plugins;
030
031import com.sun.identity.federation.common.FederationException;
032import com.sun.identity.federation.message.FSAuthnRequest;
033import com.sun.identity.federation.message.FSAuthnResponse;
034import com.sun.identity.federation.message.FSFederationTerminationNotification;
035import com.sun.identity.federation.message.FSLogoutNotification;
036import com.sun.identity.federation.message.FSLogoutResponse;
037import com.sun.identity.federation.message.FSNameRegistrationRequest;
038import com.sun.identity.federation.message.FSNameRegistrationResponse;
039import com.sun.identity.federation.message.FSResponse;
040import java.util.Set;
041import javax.servlet.http.HttpServletRequest;
042import javax.servlet.http.HttpServletResponse;
043
044/**
045 * The interface <code>FederationSPAdapter</code> could be implemented to 
046 * perform user specific processing during federation process on the
047 * Liberty Service Provider side.   
048 * <p>
049 * A singleton instance of this <code>FederationSPAdapter</code> will be used 
050 * during runtime, so make sure implementation of the federation 
051 * processing methods (except initialize() method) are thread safe. 
052 * @supported.all.api
053 */
054
055public interface FederationSPAdapter {
056
057    /**
058     * Federation or Single Sign on process succeed at <code>SP</code> side.
059     */
060    public static final int SUCCESS = 0;
061
062    /**
063     * Response from <code>IDP</code> with Browser POST or LECP profile contains     * non-Success status code.
064     */
065    public static final int INVALID_AUTHN_RESPONSE = 1;
066
067    /**
068     * Response from <code>IDP</code> with Browser Artifact profile contains
069     * non-Success status code.
070     */
071    public static final int INVALID_RESPONSE = 2;
072
073    /**
074     * Account federation failed.
075     */
076    public static final int FEDERATION_FAILED = 3;
077
078    /**
079     * Account federation failed because it failed to generate user token.
080     */
081    public static final int FEDERATION_FAILED_SSO_TOKEN_GENERATION = 4;
082
083    /**
084     * Account federation failed because it failed to generate anonymous
085     * token.
086     */
087    public static final int FEDERATION_FAILED_ANON_TOKEN_GENERATION = 5;
088
089    /**
090     * Account federation failed because anonymous user account is inactive.
091     */
092    public static final int FEDERATION_FAILED_ANON_AUTH_USER_INACTIVE = 6;
093
094    /**
095     * Account federation failed because anonymous user account is locked.
096     */
097    public static final int FEDERATION_FAILED_ANON_AUTH_USER_LOCKED = 7;
098
099    /**
100     * Account federation failed because anonymous user account is expired.
101     */
102    public static final int FEDERATION_FAILED_ANON_AUTH_ACCOUNT_EXPIRED = 8;
103
104    /**
105     * Account federation failed because it failed to write account federation
106     * info.
107     */
108    public static final int FEDERATION_FAILED_WRITING_ACCOUNT_INFO = 9;
109
110    /**
111     * Single Sign On failed.
112     */
113    public static final int SSO_FAILED = 10;
114
115    /**
116     * Single Sign On failed because federation info does not exist at
117     * <code>SP</code> side.
118     */
119    public static final int SSO_FAILED_FEDERATION_DOESNOT_EXIST = 11;
120
121    /**
122     * Single Sign On failed because it failed to find auto federation user.
123     */
124    public static final int SSO_FAILED_AUTO_FED = 12;
125
126    /**
127     * Single Sign On failed because the user account is inactive.
128     */
129    public static final int SSO_FAILED_AUTH_USER_INACTIVE = 13;
130
131    /**
132     * Single Sign On failed because the user account is locked.
133     */
134    public static final int SSO_FAILED_AUTH_USER_LOCKED = 14;
135
136    /**
137     * Single Sign On failed because the user account is expired.
138     */
139    public static final int SSO_FAILED_AUTH_ACCOUNT_EXPIRED = 15;
140
141    /**
142     * Single Sign On failed because it failed to generate user token.
143     */
144    public static final int SSO_FAILED_TOKEN_GENERATION = 16;
145
146    /**
147     * Adapter's initialization parameter name for realm.
148     */
149    public static final String ENV_REALM = "REALM=";
150
151    /**
152     * Initializes the federation adapter, this method will only be executed
153     * once after creation of the adapter instance.
154     * @param hostedEntityID entity ID for the hosted SP
155     * @param initParams  initial set of parameters(such as REALM) configured
156     *  in the service provider for this adapter.
157     */
158    public void initialize(String hostedEntityID, Set initParams);
159 
160    /**
161     * Invokes before federation manager sends the Single-Sing-On and Federation
162     * request to IDP. 
163     * @param hostedEntityID entity ID for the hosted SP
164     * @param idpEntityID entity id for the IDP to which the request will 
165     *          be sent
166     * @param request servlet request
167     * @param response servlet response
168     * @param authnRequest the authentication request to be send to IDP 
169     */
170    public void preSSOFederationRequest(
171        String hostedEntityID, 
172        String idpEntityID,
173        HttpServletRequest request, 
174        HttpServletResponse response, 
175        FSAuthnRequest authnRequest);
176
177
178    /**
179     * Invokes when the FM received the Single-Sign-On and Federation response
180     * from the IDP, this is called before any processing started on SP side.
181     * @param hostedEntityID entity ID for the hosted SP
182     * @param request servlet request
183     * @param response servlet response
184     * @param authnRequest the original authentication request sent from SP 
185     * @param authnResponse response from IDP if Browser POST or LECP profile
186     *          is used for the request, value will be null if Browser Artifact
187     *          profile is used. 
188     * @param samlResponse response from IDP if Browser Artifact profile is used
189     *          for the request, value will be null if Browser POST or LECP 
190     *          profile is used.
191     * @exception FederationException if user want to fail the process.
192     */
193    public void preSSOFederationProcess(
194        String hostedEntityID, 
195        HttpServletRequest request, 
196        HttpServletResponse response, 
197        FSAuthnRequest authnRequest, 
198        FSAuthnResponse authnResponse,
199        FSResponse samlResponse)
200    throws FederationException;
201
202    /**
203     * Invokes after Single-Sign-On and Federation processing is successful.
204     * @param hostedEntityID Entity ID for the hosted SP
205     * @param request servlet request
206     * @param response servlet response
207     * @param ssoToken   user's SSO Token 
208     * @param authnRequest the original authentication request sent from SP 
209     * @param authnResponse response from IDP if Browser POST or LECP profile
210     *          is used for the request, value will be null if Browser Artifact
211     *          profile is used. 
212     * @param samlResponse response from IDP if Browser Artifact profile is used
213     *          for the request, value will be null if Browser POST or LECP 
214     *          profile is used.
215     * @return true if browser redirection happened, false otherwise.
216     * @exception FederationException if user want to fail the process.
217     */
218    public boolean postSSOFederationSuccess(
219        String hostedEntityID, 
220        HttpServletRequest request, 
221        HttpServletResponse response, 
222        Object ssoToken,
223        FSAuthnRequest authnRequest, 
224        FSAuthnResponse authnResponse,
225        FSResponse samlResponse)
226    throws FederationException;
227
228
229    /**
230     * Invokes after Single-Sign-On or Federation processing is failed.
231     * @param hostedEntityID Entity ID for the hosted SP
232     * @param request servlet request
233     * @param response servlet response
234     * @param authnRequest the original authentication request sent from SP
235     * @param authnResponse response from IDP if Browser POST or LECP profile
236     *          is used for the request, value will be null if Browser Artifact
237     *          profile is used.
238     * @param samlResponse response from IDP if Browser Artifact profile is used     *          for the request, value will be null if Browser POST or LECP
239     *          profile is used.
240     * @param failureCode an integer specifies the failure code. Possible
241     *          failure codes are defined in this interface.
242     * @return true if browser redirection happened, false otherwise.
243     */
244    public boolean postSSOFederationFailure(String hostedEntityID,
245                                HttpServletRequest request,
246                                HttpServletResponse response,
247                                FSAuthnRequest authnRequest,
248                                FSAuthnResponse authnResponse,
249                                FSResponse samlResponse,
250                                int failureCode);
251
252
253    /**
254     * Invokes after Register Name Identifier processing is successful 
255     * @param hostedEntityID Entity ID for the hosted SP
256     * @param request servlet request
257     * @param response servlet response
258     * @param userDN DN of the user with whom name identifier registration
259     *        performed
260     * @param regRequest register name identifier request, value will be
261     *                null if the request object is not available
262     * @param regResponse register name identifier response, value will be
263     *          null if the response object is not available
264     * @param regProfile register name identifier profile used, one of following
265     *          IFSConstants.NAME_REGISTRATION_SP_HTTP_PROFILE
266     *          IFSConstants.NAME_REGISTRATION_SP_SOAP_PROFILE
267     *          IFSConstants.NAME_REGISTRATION_IDP_HTTP_PROFILE
268     *          IFSConstants.NAME_REGISTRATION_IDP_SOAP_PROFILE
269     */
270    public void postRegisterNameIdentifierSuccess(
271        String hostedEntityID,
272        HttpServletRequest request,
273        HttpServletResponse response,
274        String userDN,
275        FSNameRegistrationRequest regRequest,
276        FSNameRegistrationResponse regResponse,
277        String regProfile);
278
279    /**
280     * Invokes after the service provider successfully terminates federation 
281     * with IDP.
282     * @param hostedEntityID Entity ID for the hosted SP
283     * @param request servlet request
284     * @param response servlet response
285     * @param userDN DN of the user with whom name identifier registration
286     *        performed
287     * @param notification federation termination notification message 
288     * @param termProfile federation termination profile used, one of following
289     *          IFSConstants.TERMINATION_SP_HTTP_PROFILE
290     *          IFSConstants.TERMINATION_SP_SOAP_PROFILE
291     *          IFSConstants.TERMINATION_IDP_HTTP_PROFILE
292     *          IFSConstants.TERMINATION_IDP_SOAP_PROFILE
293     */
294    public void postTerminationNotificationSuccess(
295        String hostedEntityID, 
296        HttpServletRequest request, 
297        HttpServletResponse response,
298        String userDN,
299        FSFederationTerminationNotification notification,
300        String termProfile);
301
302    /**
303     * Invokes before single logout process started on FM side. This method
304     * is called before the user token is invalidated on the service provider
305     * side. 
306     * @param hostedEntityID Entity ID for the hosted SP
307     * @param request servlet request
308     * @param response servlet response
309     * @param userDN user DN
310     * @param logoutRequest single logout request object 
311     * @param logoutResponse single logout response, value will be
312     *          null if the response object is not available
313     * @param sloProfile single logout profile used, one of following
314     *          IFSConstants.LOGOUT_SP_REDIRECT_PROFILE
315     *          IFSConstants.LOGOUT_SP_SOAP_PROFILE
316     *          IFSConstants.LOGOUT_IDP_REDIRECT_PROFILE
317     *          IFSConstants.LOGOUT_IDP_SOAP_PROFILE
318     */
319    public void preSingleLogoutProcess(
320        String hostedEntityID,
321        HttpServletRequest request,
322        HttpServletResponse response,
323        String userDN,
324        FSLogoutNotification logoutRequest,
325        FSLogoutResponse logoutResponse,
326        String sloProfile);
327
328    /**
329     * Invokes after single logout is successful completed, i.e. user token
330     * has been invalidated.
331     * @param hostedEntityID Entity ID for the hosted SP
332     * @param request servlet request
333     * @param response servlet response
334     * @param userDN user DN
335     * @param logoutRequest single logout request, value will be
336     *          null if the request object is not available
337     * @param logoutResponse single logout response, value will be
338     *          null if the response object is not available
339     * @param sloProfile single logout profile used, one of following
340     *          IFSConstants.LOGOUT_SP_HTTP_PROFILE
341     *          IFSConstants.LOGOUT_SP_SOAP_PROFILE
342     *          IFSConstants.LOGOUT_IDP_HTTP_PROFILE
343     *          IFSConstants.LOGOUT_IDP_SOAP_PROFILE
344     */
345    public void postSingleLogoutSuccess(
346        String hostedEntityID, 
347        HttpServletRequest request, 
348        HttpServletResponse response, 
349        String userDN,
350        FSLogoutNotification logoutRequest, 
351        FSLogoutResponse logoutResponse,
352        String sloProfile);
353}