001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2010-2012 ForgeRock 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 * http://forgerock.org/license/CDDLv1.0.html
013 * See the License for the specific language governing
014 * permission and limitations under the License.
015 *
016 * When distributing Covered Code, include this CDDL
017 * Header Notice in each file and include the License file
018 * at http://forgerock.org/license/CDDLv1.0.html
019 * If applicable, add the following below the CDDL Header,
020 * with the fields enclosed by brackets [] replaced by
021 * your own identifying information:
022 * "Portions Copyrighted [year] [name of copyright owner]"
023 *
024 */
025
026package com.sun.identity.saml2.plugins;
027
028import com.sun.identity.saml2.common.SAML2Exception;
029import com.sun.identity.saml2.protocol.AuthnRequest;
030
031import javax.servlet.http.HttpServletRequest;
032import javax.servlet.http.HttpServletResponse;
033
034/**
035 * This interface <code> SAML2IdentityProviderAdapter</code> is used to perform
036 * specific tasks in the IdP
037 *
038 * @supported.all.api
039 */
040public interface SAML2IdentityProviderAdapter {
041
042    /**
043     * Initializes the federation adapter, this method will only be executed
044     * once after creation of the adapter instance.
045     *
046     * @param hostedEntityID entity ID for the hosted IDP
047     * @param realm realm of the hosted IDP
048     */
049    public void initialize(String hostedEntityID, String realm);
050
051    /**
052     * Invokes when OpenAM receives the authentication request for the first time
053     * from the SP, and is called before any processing started on the IDP side.
054     * If the authentication request is subsequently cached and retrieved, this method will not be called again.
055     * This method is not triggered in the case of IDP initiated SSO or a proxied request.
056     *
057     * @param hostedEntityID entity ID for the hosted IDP
058     * @param realm realm of the hosted IDP
059     * @param request servlet request
060     * @param response servlet response
061     * @param authnRequest the original authentication request sent from SP
062     * @param reqID the id to use for continuation of processing if the adapter redirects
063     * @return true if browser redirection is happening after processing, false otherwise. Default to false.
064     * @throws SAML2Exception for any exceptions occurring in the adapter. The federation process will continue.
065     */
066    public boolean preSingleSignOn(
067            String hostedEntityID,
068            String realm,
069            HttpServletRequest request,
070            HttpServletResponse response,
071            AuthnRequest authnRequest,
072            String reqID)
073            throws SAML2Exception;
074
075    /**
076     * Invokes when OpenAM has received the authn request, processed it, and is ready to redirect to authentication.
077     * This occurs when redirecting to authentication where there is no session, or during session upgrade.
078     * This method is not triggered in the case of IDP initiated SSO or a proxied request.
079     *
080     * @param hostedEntityID entity ID for the hosted IDP
081     * @param realm realm of the hosted IDP
082     * @param request servlet request
083     * @param response servlet response
084     * @param authnRequest the original authentication request sent from SP
085     * @param session the user session or null if the user has no session
086     * @param reqID the id to use for continuation of processing if the adapter redirects
087     * @param relayState the relayState that will be used in the redirect
088     * @return true if browser redirection is happening after processing, false otherwise. Default to false.
089     * @throws SAML2Exception for any exceptions occurring in the adapter. The federation process will continue.
090     */
091    public boolean preAuthentication(
092            String hostedEntityID,
093            String realm,
094            HttpServletRequest request,
095            HttpServletResponse response,
096            AuthnRequest authnRequest,
097            Object session,
098            String reqID,
099            String relayState)
100            throws SAML2Exception;
101
102    /**
103     * This method is invoked immediately before sending a non-error SAML2 Response.
104     * Called after successful authentication (including session upgrade) or if a valid session already exists.
105     * This method is not triggered in the case of a proxied request.
106     *
107     * @param authnRequest original authnrequest
108     * @param hostProviderID hosted providerID.
109     * @param realm realm of the hosted IDP
110     * @param request HttpServletRequest
111     * @param response HttpServletResponse
112     * @param session the user session or null if the user has no session
113     * @param reqID the id to use for continuation of processing if the adapter redirects
114     * @param relayState the relayState that will be used in the redirect
115     * @return true if browser redirection happened after processing, false otherwise. Default to false.
116     * @throws SAML2Exception if error occurs. The federation process will continue.
117     */
118    public boolean preSendResponse(
119            AuthnRequest authnRequest,
120            String hostProviderID,
121            String realm,
122            HttpServletRequest request,
123            HttpServletResponse response,
124            Object session,
125            String reqID,
126            String relayState)
127            throws SAML2Exception;
128
129    /**
130     * Called before a SAML error message is returned.
131     * This method is not triggered during IDP initiated SSO.
132     *
133     * @param request        HttpServletRequest
134     * @param response       HttpServletResponse
135     * @param faultCode      the fault code that will be returned in the SAML response
136     * @param faultDetail    the fault detail that will be returned in the SAML response
137     * @throws SAML2Exception if error occurs. The federation process will continue.
138     */
139    public void preSendFailureResponse(
140            HttpServletRequest request,
141            HttpServletResponse response,
142            String faultCode,
143            String faultDetail)
144            throws SAML2Exception;
145
146}