20 Implementing Custom Authentication Actions

Custom authentication actions enable site-specific operations to be executed during a Federation single sign-on flow with Oracle Access Management Identity Federation acting as an Identity Provider. These actions can be used to authenticate the user or check the validity of the user's session if the user is already authenticated.

The following sections explain how to implement custom authentication actions.

20.1 Understanding Custom Authentication Actions

The Oracle Access Management Identity Federation server (Identity Federation) implements custom actions using the pre- and post-processing action plug-ins. The pre- and post-processing plug-ins are implemented as JSP or JavaEE servlets which are invoked during a Federation single sign-on (SSO) flow either before or after invoking Oracle Access Manager. The following sections explain how the actions work and how they interact with Identity Federation.

20.1.1 Using Pre and Post Processing Custom Authentication Actions

Identity Federation acting as an Identity Provider (IdP) always invokes Oracle Access Manager during a Federation SSO operation. This is done either to identify the user or to check the user's session to see if the user is already authenticated. If Identity Federation determines the user must be identified, the user is forwarded to Oracle Access Manager, specifying the root context and the relative path of the OAM endpoint. At this point, Oracle Access Manager will:

  • Perform an authentication operation if necessary.

  • Check the validity of the user's session

  • (Optionally) perform an Authorization verification to ensure that the user can perform a Federation SSO operation with the SP Partner.

If these operations are successful, Oracle Access Manager forwards the user back to Identity Federation with the authentication information (a user identifier and the time at which the identity was established). Identity Federation analyzes the information and creates or updates the user session. Custom actions can be used during this interaction to:

  • Manipulate the data exchanged between Identity Federation and the Oracle Access Manager Authentication Engine. For example, you can construct an email address from a user name: johndoe becomes johndoe@mycompany.com.

  • Perform additional steps during authentication. For example, you can contact an external data source or system to obtain more information about the user.

20.1.2 Setting Up a Custom Authentication Action Plug-in

The following overview illustrates how to set up a custom action plug-in.

  1. Implement one or more custom action plug-ins as explained.

  2. Deploy the plug-in(s) to the WebLogic Managed Server on which Oracle Access Manager is running.

  3. Configure Identity Federation based on the plug-in task you are implementing.

    • Configure Identity Federation to invoke the plug-in (rather than Oracle Access Manager) if the plug-in is to perform pre-processing tasks.

    • Configure Identity Federation to have Oracle Access Manager invoke the plug-in (rather than redirecting to Identity Federation) if the plug-in is to perform post-processing tasks.

20.1.3 Understanding the Custom Action Flow

When Identity Federation needs to authenticate a user, the flow is as follows.

  1. Identity Federation, as part of a runtime IdP SSO flow, determines whether the:

    • User needs to be locally authenticated by Oracle Access Manager.

    • User has an existing session and needs to be forwarded to Oracle Access Manager to check the validity of the session.

  2. Identity Federation (acting as the IdP) invokes the pre-processing plug-in to perform the applicable custom tasks.

  3. The pre-processing plug-in invokes Oracle Access Manager.

  4. Oracle Access Manager challenges and authenticates the user, or checks the validity of the user's session.

  5. Oracle Access Manager bundles the authentication data and invokes the post-processing plug-in to perform applicable custom tasks.

  6. The post-processing plug-in invokes Identity Federation, providing the authentication data.

  7. Identity Federation (acting as an IdP) resumes operations.

Figure 20-1 illustrates this flow when Identity Federation is customized and configured to invoke plug-ins:

Figure 20-1 Custom Actions Plug-in Flow

Description of Figure 20-1 follows
Description of ''Figure 20-1 Custom Actions Plug-in Flow''

20.2 Using Pre-Processing Custom Actions

The pre-processing plug-in is a module to which the user is directed, as part of an authentication operation, before invoking Oracle Access Manager. The plug-in enables custom actions to be taken before authentication. When the plug-in is in use, Identity Federation does not redirect the user to the Authentication Engine; rather, it forwards the user internally to the plug-in, passing to it certain data for use during authentication. After performing its custom actions, the plug-in forwards the user to Oracle Access Manager, along with the data originally provided by Identity Federation, to resume the authentication flow. The following sections contain details.

20.2.1 Passing Data to the Pre-Processing Plug-in

The pre-processing custom action interacts with Identity Federation. When Identity Federation redirects a user to Oracle Access Manager, it passes certain data as attributes in the HttpServletRequest object. The same data must be made available to pre-processing plug-ins. The data includes:

  • The default scheme identifier to be used to challenge the user. This String is identified by oracle.security.fed.authn.defaultschemeid.

  • A list of scheme identifiers requested by the service provider (SP) to be used to challenge the user. This String list is identified by oracle.security.fed.authn.schemeidlevels.

  • The comparison rule requested by the SP to determine the scheme with which to challenge the user when a list of scheme identifiers is provided. This is a String identified by oracle.security.fed.authn.schemeidcomp.

  • The Force Authentication flag indicating whether Oracle Access Manager should challenge the user - even if the user is already authenticated. This is a Boolean identified by oracle.security.fed.authn.forceauthn. If missing, false is assumed.

  • The Is Passive flag indicating whether Oracle Access Manager is allowed to visually interact with the user. This is a Boolean identified by oracle.security.fed.authn.passive. If missing, false is assumed.

  • An identifier referencing the action being performed. This String is identified by oracle.security.fed.authn.refid.

  • The identifier (userID) of the user if set. This String is identified by oracle.security.fed.authn.userid.

  • The canonical user identifier of the user (userID + Identity Store Name + LDAP DN) if set. This String is identified by oracle.security.fed.authn.canonicaluserid.

  • The Identity Federation SessionID if set. This String is identified by oracle.security.fed.sessionid.

  • The identifier referencing the Oracle Access Manager server used to authenticate the user. This String is identified by oracle.security.fed.authn.engineid.

  • The partner name and the description of the remote SP for which this local authentication is requested, if a federated SSO operation is performed. This String is identified by oracle.security.fed.authn.providerid and oracle.security.fed.authn.providerdescription respectively.

  • The web context where the user should be redirected after authentication by Oracle Access Manager. This String is identified by oracle.security.fed.return.webcontext. The root web context is /oam.

  • The web relative path where the user should be redirected after authentication by Oracle Access Manager. This String is identified by oracle.security.fed.return.webpath. The relative path is /server/fed/authn.

Note:

The pre-processing plug-in can modify all attributes that were set in the HttpServletRequest object except the following:
  • oracle.security.fed.authn.defaultschemeid

  • oracle.security.fed.authn.schemeidlevels

  • oracle.security.fed.authn.schemeidcomp

  • oracle.security.fed.authn.refid

  • oracle.security.fed.authn.engineid

  • oracle.security.fed.return.webcontext

  • oracle.security.fed.return.webpath

20.2.2 Configuring Identity Federation for the Pre-Processing Action

Configure Identity Federation to forward the user to a pre-processing plug-in by performing these tasks.

  1. Enter the WLST environment.

    $IAM_HOME/common/bin/wlst.sh

  2. Connect to the WLS Admin Server.

    connect()

  3. Navigate to the Domain Runtime folder.

    domainRuntime()

  4. Execute the putStringProperty() WLST command to set the following properties:

    • The preauthnenginewebcontext property references the web context where the custom JSP Page or servlet of the pre-processing plug-in resides. Replace CUSTOM_WEB_CONTEXT with the value specific to your plug-in.

      putStringProperty("/authnengines/preauthnenginewebcontext", "CUSTOM_WEB_CONTEXT ")

    • The preauthnenginewebpath property references the path in the web context where the pre-processing plug-in resides. Replace CUSTOM_WEB_PATH with the value specific to your plug-in.

      putStringProperty("/authnengines/preauthnenginewebpath", "CUSTOM_WEB_PATH")

  5. Execute the putBooleanProperty() WLST command to enable or disable the pre-processing custom plug-in.

    • putBooleanProperty("/authnengines/preauthnengineenabled", "true") to configure Identity Federation to invoke the pre-processing plug-in.

    • putBooleanProperty("/authnengines/preauthnengineenabled", "false") to configure Identity Federation not to invoke the pre-processing plug-in.

20.3 Example: Custom Action Pre-processing

This section illustrates a simple pre-processing plug-in that is invoked by Identity Federation before the user is redirected to Oracle Access Manager. This pre-processing plug-in retrieves the name of the SP partner with which the Federation SSO operation is performed and will save it in a custom cookie that can be used by custom pages; for example, a custom error page. In this example:

  • Identity Federation acts as an IdP

  • A custom pre-authentication plug-in is used in this example to set a cookie containing the SP partner name. The cookie is called fed-sppartner-cookie.

The pre-processing plug-in consists of a Web application with a root context set to /plugin. It contains one JSP page (named cookiepartnerset.jsp) which sets the SP partner name in a cookie. Example 20-1 is an example implementation of cookiepartnerset.jsp.

Example 20-1 cookiepartnerset.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*, javax.naming.*, 
  javax.naming.directory.*, java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String partnerName = (String)request.getAttribute
  ("oracle.security.fed.authn.providerid");
 
Cookie cookie = new Cookie("fed-sppartner-cookie", partnerName);
response.addCookie(cookie);
 
// forward to the OAM server to resume the flow
request.getSession().getServletContext().getContext("/oam").getRequestDispatcher
 ("/server/fed/authn").forward(request, response);
%>

Note:

The WAR file of this Web application will need to be deployed to the WLS Managed Server on which Oracle Access Manager is running.

To resume the flow, the plug-in redirects the user to Oracle Access Manager by means of an internal forward. Take the following steps to configure Identity Federation to invoke the pre-processing plug-in.

  1. Enter the WLST environment:

    $IAM_HOME/common/bin/wlst.sh

  2. Connect to the WLS Admin Server:

    connect()

  3. Navigate to the Domain Runtime folder:

    domainRuntime()

  4. Execute the putStringProperty() WLST command to set the preauthnenginewebcontext property.

    putStringProperty("/authnengines/preauthnenginewebcontext", "/plugin")

  5. Execute the putStringProperty() WLST command to set the preauthnenginewebpath property.

    putStringProperty("/authnengines/preauthnenginewebpath", "/cookiepartnerset.jsp")

  6. Execute the putBooleanProperty() WLST command to enable the pre-processing plug-in to be invoked by Identity Federation.

    putBooleanProperty("/authnengines/preauthnengineenabled", "true")

20.4 Using Post-Processing Custom Actions

The user is directed to the post-processing plug-in module, as part of an authentication operation, after the Oracle Access Manager Authentication Engine has completed processing and before the user is directed to Identity Federation. The plug-in enables custom actions to be taken after authentication.

When the post-processing plug-in is in use, Oracle Access Manager forwards the user and authentication data internally to it. After performing its custom actions, the plug-in returns the user to Identity Federation, supplying the authentication data. The plug-in must provide Identity Federation with the data that was passed to it as part of the authentication flow; this consists of attributes that were set in the HttpServletRequest object. The following sections have details.

20.4.1 Passing Data to the Post-Processing Plug-in

The post-processing plug-in interacts with Identity Federation. When Oracle Access Manager redirects a user to Identity Federation, it passes certain data to the plug-in as attributes in the HttpServletRequest object. The data includes:

  • The identifier referencing the requested action that was performed. The String is identified by oracle.security.fed.authn.refid.

  • The schemeID and level of the authentication performed by Oracle Access Manager. The String is identified by oracle.security.fed.authn.result.schemeidlevel.

  • The result of the authentication operation. The String is identified by oracle.security.fed.authn.result.statuscode as SUCCESS, if the operation was successful.

  • The partner name of the remote SP for which this local authentication is requested if a federated SSO operation is performed. The String is identified by oracle.security.fed.authn.providerid.

  • The Oracle Access Manager module identifier used to authenticate the user. The String is identified by oracle.security.fed.authn.engineid.

  • The canonical identifier of the user (userID + Identity Store Name + LDAP DN). The String is identified by oracle.security.fed.authn.userid.

  • The authentication time. The Date is identified by oracle.security.fed.authn.authntime.

  • The expiration time of the authenticated session. The Date is identified by oracle.security.fed.authn.expirationtime.

  • The user's Oracle Access Manager SessionID. The String is identified by oracle.security.fed.authn.oamsessionid.

  • The user's Oracle Access Manager Session type. The String is identified by oracle.security.fed.authn.oamsessiontype.

  • The Identity Federation SessionID if set. The String is identified by oracle.security.fed.sessionid.

Note:

The plug-in can modify all attributes that were set on the HttpServletRequest object except:
  • oracle.security.fed.authn.result.schemeidlevel

  • oracle.security.fed.authn.engineid

  • oracle.security.fed.authn.oamsessionid

  • oracle.security.fed.authn.oamsessiontype

  • oracle.security.fed.sessionid

The custom post-processing plug-in can add these optional elements.

  • A map of attributes to be included in the outgoing SAML Assertion as SAML Attributes. This map has String objects as keys and a Collection (Set/List) of String objects or a String object as values (identified by oracle.security.fed.authn.fedattributes).

    The attributes will be included in the outgoing SSO response as is, and will only be sent for this current Federation SSO operation. They will be discarded afterwards.

  • A string to be used as the SAML NameID value instead of the configured NameID expression in the SP Partner entry. For SAML 2.0 SP Partners, this string will only be used if the NameID format for the SP Partner is not Persistent or Transient. The String is identified by oracle.security.fed.authn.feduserid.

    This string will only be used as the NameID for this current Federation SSO operation and will be discarded afterwards.

After processing, the post-processing plug-in must forward the user to Identity Federation. (Oracle Access Manager would invoke in the absence of the plug-in).

  • The root web context is /oamfed

  • The relative path is /user/loginsso

20.4.2 Configuring Identity Federation for the Post-Processing Action

Configure Identity Federation to forward the user to a post-processing plug-in by performing the following tasks.

  1. Enter the WLST environment:

    $IAM_HOME/common/bin/wlst.sh

  2. Connect to the WLS Admin Server:

    connect()

  3. Navigate to the Domain Runtime folder:

    domainRuntime()

  4. Execute the putStringProperty() WLST command to set the two following properties:

    • The postauthnenginewebcontext property references the web context where the custom JSP Page or servlet of the post-processing plug-in resides. Replace CUSTOM_WEB_CONTEXT by the value specific to your plug-in.

      putStringProperty("/authnengines/postauthnenginewebcontext", "CUSTOM_WEB_CONTEXT")

    • The postauthnenginewebpath property references the path in the web context where the post-processing plug-in resides. Replace CUSTOM_WEB_PATH by the value specific to your plug-in.

      putStringProperty("/authnengines/postauthnenginewebpath", "CUSTOM_WEB_PATH")

  5. Execute the putBooleanProperty() WLST command to enable or disable the post-processing plug-in.

    • putBooleanProperty("/authnengines/postauthnengineenabled", "true") to configure Identity Federation to invoke the post-processing plug-in.

    • putBooleanProperty("/authnengines/postauthnengineenabled", "false") to configure Identity Federation not to invoke the post-processing plug-in.

20.5 Example: Custom Action Post-Processing

This section illustrates a simple post-processing plug-in that is invoked by Oracle Access Manager before the user is redirected to Identity Federation at the end of a local authentication operation. This plug-in accesses a custom cookie presented by the browser, extracts data from it, and sets the data as attributes. Identity Federation will then include it in the outgoing SAML assertion. In this example:

  • Identity Federation acts as an IdP.

  • The custom post authentication plug-in sets some attributes as session attributes called attr1 and attr2.

  • Identity Federation (as the IdP) will send the attr1 and attr2 attributes to the SP Partner with which the Federation SSO operation is being performed when creating an assertion.

  • A custom component sets the cookie used in this example.

In this sample, the plug-in adds the following attributes, extracted from a custom cookie that is previously set by another component, after a successful authentication:

  • cookie-language contains the preferred language of the user.

  • cookie-homepage contains the preferred home page of the user.

The post-processing plug-in consists of a Web application with a root context set to /plugin. It contains one JSP page (named cookieextract.jsp) which extracts the data from the custom cookie and sets it as session attributes. Example 20-2 is an example implementation of cookieextract.jsp.

Example 20-2 cookieextract.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*, javax.naming.*, 
  javax.naming.directory.*, java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
// check if authentication was successful
if ("SUCCESS".equals(request.getAttribute("oracle.security.fed.authn.result.statuscode")))
{
        // authentication was successful. Attributes will be added
        Map attributes = new HashMap();
        
        // get the cookie
        Cookie[] cookies = request.getCookies();
        String cookieValue = null;
        for(int i = 0; i < cookies.length; i++)
        { 
                Cookie cookie = cookies[i];
                if (cookie.getName().equals("customcookie")) 
                        cookieValue = cookie.getValue();
        }
        if (cookieValue != null && cookieValue.length() > 0)
        {
                StringTokenizer st = new StringTokenizer(cookieValue, "+");
                String language = st.nextToken();
                String homepage = st.nextToken();
 
                attributes.put("cookie-language", language);
                attributes.put("cookie-homepage", homepage);
 
                request.setAttribute( "oracle.security.fed.authn.fedattributes", attributes);
        }
}
 
// forward to the OIF server to resume the flow
request.getSession().getServletContext().getContext("/oamfed").getRequestDispatcher("/user/loginsso").forward(request, response);
%> 

Note:

The WAR file of this Web application will need to be deployed on the WLS Managed Server where OAM is running

The plug-in redirects the user to the Identity Federation server by means of an internal forward to resume the flow. Take the following steps to configure Identity Federation to invoke the post-processing plug-in at the end of local authentication flow.

  1. Enter the WLST environment:

    $IAM_HOME/common/bin/wlst.sh

  2. Connect to the WLS Admin Server:

    connect()

  3. Navigate to the Domain Runtime folder:

    domainRuntime()

  4. Execute the putStringProperty() WLST command to set the postauthnenginewebcontext property.

    putStringProperty("/authnengines/postauthnenginewebcontext", "/plugin")

  5. Execute the putStringProperty() WLST command to set the postauthnenginewebpath property.

    putStringProperty("/authnengines/postauthnenginewebpath", "/cookieextract.jsp")

  6. Execute the putBooleanProperty() WLST command to enable the post-processing plug-in.

    putBooleanProperty("/authnengines/postauthnengineenabled", "true")