001/** 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 003 * 004 * Copyright (c) 2010-2013 ForgeRock AS. 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; 030import com.sun.identity.saml2.protocol.Response; 031 032import javax.servlet.http.HttpServletRequest; 033import javax.servlet.http.HttpServletResponse; 034 035/** 036 * This interface <code> SAML2IdentityProviderAdapter</code> is used to perform 037 * specific tasks in the IdP 038 * 039 * @supported.all.api 040 */ 041public interface SAML2IdentityProviderAdapter { 042 043 /** 044 * Initializes the federation adapter, this method will only be executed 045 * once after creation of the adapter instance. 046 * 047 * @param hostedEntityID entity ID for the hosted IDP 048 * @param realm realm of the hosted IDP 049 */ 050 public void initialize(String hostedEntityID, String realm); 051 052 /** 053 * Invokes when OpenAM receives the authentication request for the first time 054 * from the SP, and is called before any processing started on the IDP side. 055 * If the authentication request is subsequently cached and retrieved, this method will not be called again. 056 * This method is not triggered in the case of IDP initiated SSO or a proxied request. 057 * 058 * @param hostedEntityID entity ID for the hosted IDP 059 * @param realm realm of the hosted IDP 060 * @param request servlet request 061 * @param response servlet response 062 * @param authnRequest the original authentication request sent from SP 063 * @param reqID the id to use for continuation of processing if the adapter redirects 064 * @return true if browser redirection is happening after processing, false otherwise. Default to false. 065 * @throws SAML2Exception for any exceptions occurring in the adapter. The federation process will continue. 066 */ 067 public boolean preSingleSignOn( 068 String hostedEntityID, 069 String realm, 070 HttpServletRequest request, 071 HttpServletResponse response, 072 AuthnRequest authnRequest, 073 String reqID) 074 throws SAML2Exception; 075 076 /** 077 * Invokes when OpenAM has received the authn request, processed it, and is ready to redirect to authentication. 078 * This occurs when redirecting to authentication where there is no session, or during session upgrade. 079 * This method is not triggered in the case of IDP initiated SSO or a proxied request. 080 * 081 * @param hostedEntityID entity ID for the hosted IDP 082 * @param realm realm of the hosted IDP 083 * @param request servlet request 084 * @param response servlet response 085 * @param authnRequest the original authentication request sent from SP 086 * @param session the user session or null if the user has no session 087 * @param reqID the id to use for continuation of processing if the adapter redirects 088 * @param relayState the relayState that will be used in the redirect 089 * @return true if browser redirection is happening after processing, false otherwise. Default to false. 090 * @throws SAML2Exception for any exceptions occurring in the adapter. The federation process will continue. 091 */ 092 public boolean preAuthentication( 093 String hostedEntityID, 094 String realm, 095 HttpServletRequest request, 096 HttpServletResponse response, 097 AuthnRequest authnRequest, 098 Object session, 099 String reqID, 100 String relayState) 101 throws SAML2Exception; 102 103 /** 104 * This method is invoked before sending a non-error SAML2 Response, but before the SAML Response object is 105 * constructed. 106 * Called after successful authentication (including session upgrade) or if a valid session already exists. 107 * 108 * @param authnRequest original authnrequest 109 * @param hostProviderID hosted providerID. 110 * @param realm realm of the hosted IDP 111 * @param request HttpServletRequest 112 * @param response HttpServletResponse 113 * @param session the user session or null if the user has no session 114 * @param reqID the id to use for continuation of processing if the adapter redirects 115 * @param relayState the relayState that will be used in the redirect 116 * @return true if browser redirection happened after processing, false otherwise. Default to false. 117 * @throws SAML2Exception if error occurs. The federation process will continue. 118 */ 119 public boolean preSendResponse( 120 AuthnRequest authnRequest, 121 String hostProviderID, 122 String realm, 123 HttpServletRequest request, 124 HttpServletResponse response, 125 Object session, 126 String reqID, 127 String relayState) 128 throws SAML2Exception; 129 130 /** 131 * Called after the SAML Response object is created, but before the Response is signed/encrypted. When artifact 132 * binding is being used, this method is invoked when the response object is created, and not when the artifact 133 * is actually resolved. 134 * This extension point's purpose is to make it possible to adjust the content of the SAML response (for example by 135 * adding custom SAML extensions), hence this method does not provide a way to abort the SAML flow. 136 * 137 * @param authnRequest The original SAML Authentication Request (may be null if this was an IdP initiated SSO). 138 * @param res The SAML Response. 139 * @param hostProviderID The entity ID of the IdP. 140 * @param realm The realm the IdP belongs to. 141 * @param request The HttpServletRequest object. 142 * @param session The user session or null if the user has no session. 143 * @param relayState The relayState that will be used in the redirect 144 * @throws SAML2Exception If an error occurs. The federation process will continue. 145 */ 146 public void preSignResponse( 147 AuthnRequest authnRequest, 148 Response res, 149 String hostProviderID, 150 String realm, 151 HttpServletRequest request, 152 Object session, 153 String relayState) throws SAML2Exception; 154 155 /** 156 * Called before a SAML error message is returned. 157 * This method is not triggered during IDP initiated SSO. 158 * 159 * @param request HttpServletRequest 160 * @param response HttpServletResponse 161 * @param faultCode the fault code that will be returned in the SAML response 162 * @param faultDetail the fault detail that will be returned in the SAML response 163 * @throws SAML2Exception if error occurs. The federation process will continue. 164 */ 165 public void preSendFailureResponse( 166 HttpServletRequest request, 167 HttpServletResponse response, 168 String faultCode, 169 String faultDetail) 170 throws SAML2Exception; 171}