a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster/**
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster *
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * Copyright (c) 2010-2013 ForgeRock AS. All Rights Reserved.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster *
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * The contents of this file are subject to the terms
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * of the Common Development and Distribution License
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * (the License). You may not use this file except in
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * compliance with the License.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster *
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * You can obtain a copy of the License at
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * http://forgerock.org/license/CDDLv1.0.html
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * See the License for the specific language governing
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * permission and limitations under the License.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster *
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * When distributing Covered Code, include this CDDL
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Header Notice in each file and include the License file
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * at http://forgerock.org/license/CDDLv1.0.html
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * If applicable, add the following below the CDDL Header,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * with the fields enclosed by brackets [] replaced by
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * your own identifying information:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * "Portions Copyrighted [year] [name of copyright owner]"
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster *
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster */
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterpackage com.sun.identity.saml2.plugins;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterimport com.sun.identity.saml2.common.SAML2Exception;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterimport com.sun.identity.saml2.protocol.AuthnRequest;
079f146cc6b658c00ec79e35a47d027c5039588aPeter Majorimport com.sun.identity.saml2.protocol.Response;
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterimport javax.servlet.http.HttpServletRequest;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterimport javax.servlet.http.HttpServletResponse;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster/**
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This interface <code> SAML2IdentityProviderAdapter</code> is used to perform
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * specific tasks in the IdP
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster *
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @supported.all.api
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder */
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterpublic interface SAML2IdentityProviderAdapter {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster /**
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * Initializes the federation adapter, this method will only be executed
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * once after creation of the adapter instance.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder *
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param hostedEntityID entity ID for the hosted IDP
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param realm realm of the hosted IDP
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder */
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder public void initialize(String hostedEntityID, String realm);
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder /**
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * Invokes when OpenAM receives the authentication request for the first time
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * from the SP, and is called before any processing started on the IDP side.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * If the authentication request is subsequently cached and retrieved, this method will not be called again.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * This method is not triggered in the case of IDP initiated SSO or a proxied request.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder *
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param hostedEntityID entity ID for the hosted IDP
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param realm realm of the hosted IDP
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param request servlet request
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param response servlet response
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param authnRequest the original authentication request sent from SP
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param reqID the id to use for continuation of processing if the adapter redirects
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @return true if browser redirection is happening after processing, false otherwise. Default to false.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @throws SAML2Exception for any exceptions occurring in the adapter. The federation process will continue.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder */
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder public boolean preSingleSignOn(
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String hostedEntityID,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String realm,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder HttpServletRequest request,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder HttpServletResponse response,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder AuthnRequest authnRequest,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String reqID)
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder throws SAML2Exception;
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder /**
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * Invokes when OpenAM has received the authn request, processed it, and is ready to redirect to authentication.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * This occurs when redirecting to authentication where there is no session, or during session upgrade.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * This method is not triggered in the case of IDP initiated SSO or a proxied request.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder *
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param hostedEntityID entity ID for the hosted IDP
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param realm realm of the hosted IDP
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param request servlet request
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param response servlet response
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param authnRequest the original authentication request sent from SP
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param session the user session or null if the user has no session
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param reqID the id to use for continuation of processing if the adapter redirects
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param relayState the relayState that will be used in the redirect
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @return true if browser redirection is happening after processing, false otherwise. Default to false.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @throws SAML2Exception for any exceptions occurring in the adapter. The federation process will continue.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder */
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder public boolean preAuthentication(
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String hostedEntityID,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String realm,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder HttpServletRequest request,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder HttpServletResponse response,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder AuthnRequest authnRequest,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder Object session,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String reqID,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String relayState)
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder throws SAML2Exception;
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder /**
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * This method is invoked before sending a non-error SAML2 Response, but before the SAML Response object is
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * constructed.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * Called after successful authentication (including session upgrade) or if a valid session already exists.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster *
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param authnRequest original authnrequest
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param hostProviderID hosted providerID.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param realm realm of the hosted IDP
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param request HttpServletRequest
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param response HttpServletResponse
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param session the user session or null if the user has no session
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param reqID the id to use for continuation of processing if the adapter redirects
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param relayState the relayState that will be used in the redirect
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @return true if browser redirection happened after processing, false otherwise. Default to false.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @throws SAML2Exception if error occurs. The federation process will continue.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster */
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder public boolean preSendResponse(
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder AuthnRequest authnRequest,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String hostProviderID,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String realm,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder HttpServletRequest request,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder HttpServletResponse response,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder Object session,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String reqID,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String relayState)
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder throws SAML2Exception;
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major /**
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * Called after the SAML Response object is created, but before the Response is signed/encrypted. When artifact
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * binding is being used, this method is invoked when the response object is created, and not when the artifact
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * is actually resolved.
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * This extension point's purpose is to make it possible to adjust the content of the SAML response (for example by
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * adding custom SAML extensions), hence this method does not provide a way to abort the SAML flow.
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major *
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * @param authnRequest The original SAML Authentication Request (may be null if this was an IdP initiated SSO).
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * @param res The SAML Response.
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * @param hostProviderID The entity ID of the IdP.
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * @param realm The realm the IdP belongs to.
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * @param request The HttpServletRequest object.
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * @param session The user session or null if the user has no session.
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * @param relayState The relayState that will be used in the redirect
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major * @throws SAML2Exception If an error occurs. The federation process will continue.
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major */
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major public void preSignResponse(
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major AuthnRequest authnRequest,
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major Response res,
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major String hostProviderID,
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major String realm,
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major HttpServletRequest request,
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major Object session,
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major String relayState) throws SAML2Exception;
079f146cc6b658c00ec79e35a47d027c5039588aPeter Major
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder /**
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * Called before a SAML error message is returned.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * This method is not triggered during IDP initiated SSO.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder *
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param request HttpServletRequest
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param response HttpServletResponse
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param faultCode the fault code that will be returned in the SAML response
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @param faultDetail the fault detail that will be returned in the SAML response
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder * @throws SAML2Exception if error occurs. The federation process will continue.
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder */
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder public void preSendFailureResponse(
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder HttpServletRequest request,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder HttpServletResponse response,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String faultCode,
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder String faultDetail)
7da3f239ac3deab008336f663f21e82d5d01aeadJonathan Scudder throws SAML2Exception;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster}