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}