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