3 Deploying Oracle Identity Federation

3.2.5.1.1 Architecture

Figure 3–1 depicts the different external and internal modules of an Oracle Identity Federation deployment, and how they interact at runtime:

Figure 3-1 Oracle Identity Federation Module Interactions

For the sake of this discussion, Oracle Identity Federation is depicted as three internal modules:

• the Identity Federation Engine, which is responsible for creating and processing SAML messages such as AuthnRequest, assertion, and logout messages.

  This module:

  • works with the user data store when processing SAML messages;

  • interacts with the authentication engine when it is necessary for a user to be locally identified; and

  • interacts with the SP integration engines when the user is redirected to the IAM component after processing an assertion.

• the authentication engines, which are responsible for processing requests from the federation engine to authenticate users. This module interacts with the IAM component and the user data store to authenticate the user and retrieve the unique identifier Oracle Identity Federation uses to reference the user.

  This module can be invoked in either IdP or SP mode when local authentication is required.

  After authenticating the user, the authentication engine sends the authentication information, such as the user's identifier, the time of authentication, and other data to the federation engine.

• After successfully processing an incoming SAML assertion and locating the user referenced by the assertion, the federation engine instructs the SP integration Engine to create an authenticated session for that user in the IAM domain. It passes the necessary information (user's identifier, authentication time, and so on) to the SP integration Engine, which interacts with the IAM server to create the session.

3.2.5.1.2 Authentication Engine Framework

The authentication engine framework of Oracle Identity Federation is designed to authenticate a user, and includes several internal plug-ins that allow it to interact with the various IAM servers supported out of the box, such as:

• Oracle Single Sign-On

• Oracle Access Manager

• Username/Password using an LDAP Server

• Username/Password using an RDBMS Server

• Username/Password using an RDBMS Table

• InfoCard

• Federation SSO Proxy

• JAAS

Additionally, Oracle Identity Federation provides a framework so that the server can be integrated with third party authentication modules. The integrators have two approaches to customize Oracle Identity Federation to interact with other authentication platforms:

• Design and implement an authentication module that will interact with Oracle Identity Federation using internal JavaEE Servlet forwards. The new module would also be linked to the third party authentication solution responsible of authenticating the user.

• Leverage JAAS to use a specific Login module. Oracle Identity Federation will include an authentication engine, based on internal forwards, which uses the JAAS libraries to authenticate the user. This allows integrators to re-use any JAAS compliant login modules that already exist for use in Oracle Identity Federation server modules by configuring Oracle Identity Federation.

Here is a step-by-step description of how the authentication engine interacts with the other federation server components in a typical user flow:

1. The user accesses Oracle Identity Federation for an SSO operation (in either SP or IdP mode).

2. An internal process in the server determines that the user needs to be identified using a specific authentication mechanism (either the default one from the configuration or one requested by a remote service provider).

3. The Federation Server determines which authentication engine to use to challenge/identify the user for the specified authentication mechanism.

4. The Federation Server then internally forwards the user's request to the Web Context and Login Relative Path of the authentication engine to challenge/identify the user, and it passes some information, specified via Java Objects stored as Attributes of the HttpServletRequest instance:

   • The authentication mechanism to use when challenging the user for identification

   • An identifier referencing the current action that is being performed

   • The ProviderID and the description of the remote service provider for which this local authentication is requested, if a Federation SSO operation is performed

   • The identifier referencing the engine used to authenticate the user

   • The identifier of the user

   • The Force Authentication flag, indicating whether or not the engine should challenge the user even if the user is already authenticated.

   • The Is Passive flag, indicating whether or not the engine is allowed to visually interact with the user.

   • Optionally, a map of attributes that need to be set by the engine: these attributes are required in order for Oracle Identity Federation/IdP to create correctly the assertion with the AttributeStatement, as specified by the configuration for that specific remote provider.

   • Optionally, a String containing the Oracle Identity Federation session identifier, if the user has already an active session. Oracle Identity Federation is passing the sessionID of the already existing user session (if one exists), to the authentication engine, so that the engine can persist state linked to the user, and it can reference that data by using the sessionID value. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session.

5. The authentication engine processes the incoming request, and it has access to the information stored as HttpServletRequest attributes.

6. The authentication engine interacts with the IAM component and may challenge the user for credentials. After successful authentication, it may set a cookie (for example, to maintain the authenticated session with the IAM server and/or the target application).

7. The authentication module sends the user back to Oracle Identity Federation using an internal forward (Web Context /fed and Login Relative Path /user/loginsso), and it passes the following information as HttpServletRequest attributes:

   • The identifier of the user

   • Authentication time

   • Expiration time of the authenticated session

   • The authentication mechanism used to identify the user

   • The identifier referencing the action that was being performed, from the request

   • The identifier referencing the Engine used to authenticate the user

   • Optionally, a map of attributes that will be stored in the user session.

   • Optionally, a String containing the Oracle Identity Federation session identifier that Oracle Identity Federation needs to use to reference the Oracle Identity Federation user session. This allows the engine and Oracle Identity Federation to share the same identifier to reference the user session. Later on, when the logout flow is being executed, Oracle Identity Federation passes the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session.

   Note:

   • If the user ID attribute is empty but the Authentication Time and authentication mechanism attributes are not empty, it will mean to Oracle Identity Federation that the authentication succeeded, but that the user is unknown on the server. This is useful when Oracle Identity Federation, acting as an IdP, is configured to use the attributes passed by the engine to create an assertion

   • If the Authentication Time or Authentication Mechanism attributes are empty, it indicates to Oracle Identity Federation that the authentication failed.

8. Oracle Identity Federation performs these actions:

   • processes the incoming request

   • retrieves the data embedded as attributes in the HttpServletRequest

   • locates the user in the user data store

   • creates a session for the user

   • sets a cookie, and

   • resumes the SSO operation.

3.2.5.1.3 SP Integration Engine Framework

The SP integration Engine included with Oracle Identity Federation consists of a servlet that processes requests from the server to create a user authenticated session at the IAM server. The engine includes several internal plug-ins that allow it to interact with different IAM servers, such as:

• Oracle Single Sign-On

• Oracle Access Manager

• Oracle Identity Federation Test Application

Additionally, Oracle Identity Federation will provide a framework so that the server will be able to be integrated with third party IAM frameworks: the customized SP integration Module will interact with Oracle Identity Federation using internal J2EE Servlet forwards, and it will communicate with the third party IAM system to create the user authenticated session.

Here is a step-by-step description of how an SP integration Engine interacts with the Oracle Identity Federation Framework in a typical user flow:

1. The user attempts to access a resource protected by the IAM solution, and configured to use Federation SSO to authenticate the user.

2. The IAM deployment redirects the user to the corresponding SP integration Module on Oracle Identity Federation.

3. The SP integration Module decodes the information sent by the IAM deployment and internally forward the user to the Oracle Identity Federation server with the following information set as HttpServletRequest attributes:

   • An optional authentication mechanism specifying to the SP which authentication mechanism to request the IdP to use during authentication.

     Note:

     if set, this parameter is used to determine the IdP to use, disregarding the default parameter described next.

   • An optional Provider ID referencing the IdP to use for the Federation SSO. If missing, Oracle Identity Federation uses the IdP mapped for the specified authentication mechanism. If no IdP could be found, Oracle Identity Federation will use the IdP configured as the Default SSO IdP

   • An optional federation ID referencing the affiliation to use to trigger the Federation SSO

   • The relay state. It can contain a small string, for example a reference to some data saved in a repository or a small URL pointing to the protected resource to redirect the user to after completion of the SSO operation

   • The identifier of the SP engine that started the SSO flow

   • An optional boolean indicating if the Oracle Identity Federation server should authenticate the user locally using the authentication engines or if a Federation SSO should be started by redirecting the user to an IdP for authentication

   • A Boolean object indicating whether or not to use the configuration stored in Oracle Identity Federation or to only start the SSO based on the information being passed by the SP engine, except the IdP

   • A Boolean object indicating whether or not the SP should ask the IdP to challenge the user even if already authenticated

   • A Boolean object indicating whether or not the SP should allow the IdP to create a federation record if one does not yet exist, during the SSO operation

   • A Boolean object indicating whether or not the SP should ask the IdP not to interact with the user during the SSO operation

   • A String representing the binding to use when sending the AuthnRequest

   • A String representing the binding to use when sending the response with the assertion

   • An optional authentication mechanism comparison specifying to the SP which authentication context comparison to request the IdP to use during authentication

   • A String representing the NameID format the SP will ask to the IdP for the SSO operation

4. Oracle Identity Federation initiates a Federation SSO operation with a remote IdP.

5. The IdP authenticates the user and, if necessary, redirects the user, with an assertion, to the federation server acting as an SP.

6. The server processes the assertion and locates the user in the user data store. The user is now authenticated at the federation server.

7. Oracle Identity Federation internally forwards the user back to the SP integration Module by using the Web Context and Login Relative Path of that module configured in Oracle Identity Federation. The server will pass the following data as HttpServletRequest attributes:

   • A Boolean object indicating if the SSO operation was successful

   • The identifier of the user

   • Authentication time

   • Expiration time of the authenticated session

   • The authentication mechanism used to identify the user

   • The relay state

   • The contents of the assertion: the NameID, the Issuer of the assertion and the optional attributes. Note: the content of the assertion is not passed as XML Data, that is the original assertion will not be passed back to the module. The extra data will be referenced as:

     • orafed-nameid-value containing the Name ID value

     • orafed-nameid-qualifier containing the Name ID qualifier

     • orafed-nameid-format containing the Name ID format

     • orafed-providerid containing the Peer ProviderID

   • The top status of the SAML Response

   • The low status of the SAML Response if any

   • The status message if any

   • The ProviderID that created the SSO assertion

   • The identifier of the SP engine that will process the above information

   • A String containing the Oracle Identity Federation identifier of the user session. Oracle Identity Federation is passing the sessionID of the user session to the SP engine, so that it can persist state linked to the user, and it can reference that data by using the sessionID value. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session.

8. The SP integration Engine interacts with the IAM server to create an authenticated session for the user. The session is based on the data received from Oracle Identity Federation.

9. The SP integration Engine redirects the user to the final target URL.

3.2.5.1.4 Logout

When logging out, Oracle Identity Federation and the Authentication/SP Engines will need to be logged out. This will involve:

1. Logging out the user from the authentication engines

2. Logging out the user from the SP Engines

3. Performing the SAML/WS-Fed Global Logout profiles

4. Logging the user out from Oracle Identity Federation

Figure 3-2 Oracle Identity Federation Module Interactions

There are several ways to invoke the logout:

• The user invokes the Oracle Identity Federation logout server, at /fed/user/logout by specifying an optional return URL. In this case, Oracle Identity Federation will logout the user from Authentication/SP Engines, the remote SAML providers and from Oracle Identity Federation itself, and Oracle Identity Federation will redirect the user to the return URL, or display the logout result page.

• The user is redirected from a remote SAML/WS-Fed provider to Oracle Identity Federation using the Global Logout protocol. In this case, Oracle Identity Federation will logout the user from Authentication/SP Engines, the remote SAML/WS-Fed providers (except the one that sent the logout message), from Oracle Identity Federation itself and redirect the user back to the remote SAML provider that sent the original message.

• The user initiates logout from an environment integrated with an Authentication/SP Engine. In that case, that environment would invoke the Authentication/SP Engine for logout, and the Engine would then send the user to Oracle Identity Federation for Logout. From that point, Oracle Identity Federation would log out the user from the Authentication/SP Engines (except the engine that redirected the user to Oracle Identity Federation), from Oracle Identity Federation itself and redirect the user back to the Authentication/SP Engine that started the flow

Oracle Identity Federation invokes Authn/SP Engine

When Oracle Identity Federation sends the user to the Authentication/SP Engine, it will:

1. Perform an internal forward to the web context and relative logout path of the engine

2. Specify the engine ID of the invoked Engine for logout

3. Optionally the identifier of the user session being logged out

When the Authentication/SP Engine will have logged the user out, the engine will internally forward the user back to Oracle Identity Federation, it will:

1. Perform an internal forward to the /fed web context and /user/logoutretsso

2. Specify the engine ID of the invoked Engine

Authn/SP invokes Oracle Identity Federation

When an Authentication/SP Engine invokes Oracle Identity Federation for logout, it will:

1. Perform an internal forward to the /fed web context and /user/logoutsso

2. Specify the engine ID of the invoked Engine for logout

3. Specify a return URL where Oracle Identity Federation will redirect the user after logout.

At the end of the Logout flow, the user will be logged out from Oracle Identity Federation and redirected to the return URL.

3.2.5.1.5 Requirements

Oracle Identity Federation's design is consistent with certain requirements regarding authentication operations and SP integration (where a user session is created at the IAM server). Consequently, you must meet the following requirements when implementing a custom authentication engine or an SP integration Engine:

• The authentication engine, the SP integration Engine, the Identity Federation Engine and the IAM server must use the same user data store as the user repository. This store contains the user data used to look up and authenticate users.

• The authentication engine and the SP integration engine must include a Java Servlet /JSP.

• The data exchanges between Oracle Identity Federation and the Authentication/SP integration engines are done via internal HTTP request forwarding. This is actually an internal API call between the modules that relies on the J2EE servlet framework via the HTTP protocol.

• A logout service needs to be implemented and made available to the authentication engine and/or the SP integration engine. This logout service must be published as Servlet/JSP.

3.2.5.2.1 Planning a Custom Authentication Engine

Creating a customized authentication engine involves:

• creating a service that will process incoming requests from Oracle Identity Federation

• implementing a module to authenticate a user

• creating a service that forwards the user to the federation server with the required information

• deciding whether or not the authentication engine will set a cookie after authenticating a user. If yes, the authentication module must be integrated into the logout process (see Section 3.2.5.4, "Logout")

• packaging the services and module into a web application, and deploying the application to the Oracle WebLogic Managed Server where Oracle Identity Federation is running

• configuring Oracle Identity Federation to reference the new authentication engine.

• ensuring that the user identifier returned by the authentication engine references the same user in the Oracle Identity Federation User Data Store

3.2.5.2.2 Developing and Implementing the Authentication Module

Several aspects of module development are explained here.

URLs

Communication between the federation engine and the authentication engine occurs through internal servlet forwards that are equivalent to API calls. These forwards use the following J2EE API:

ServletContext.getContext(String contextPath)
   .getRequestDispatcher(String relativePath)
   .forward(HttpServletRequest request, 
      HttpServletResponse response)

where:

• contextPath is the root context path of the web application. For example, the contextPath of Oracle Identity Federation is /fed.

• relativePath is the service URL to which to forward the user; it is relative to the contextPath. For example, after authenticating a user, the authentication engine uses /user/loginsso as the relativePath when forwarding the user.

Oracle Identity Federation needs to be aware of the ID of the new authentication engine, as well as the contextPath and the relativePath. This is the URL that will process authentication requests issued by the federation server.

Adding or Modifying an Authentication Engine

To add an authentication engine or modify one:

• Go to Fusion Middleware Control and locate the Oracle Identity Federation instance.

• Navigate to Administration then Authentication Engines.

• To add an authentication engine, click Add and enter a name for that authentication engine. Oracle Identity Federation generates an ID for that new engine

  Note:

  the name will only be used in Fusion Middleware Control for display purposes while the ID will be used during communications between Oracle Identity Federation and the authentication engine

• To modify an authentication engine, select it and:

  • Enable or disable the engine

  • Specify the contextPath of the authentication engine in the Web Context field

  • Specify the relative path of the login service of the authentication engine in the Login Relative Path field

  • Enable or disable logout

  • Specify the relative path of the logout service of the authentication engine in the Logout Relative Path field

• Click Apply.

Implementing the Service

This section describes the roles that are played by the authentication engine, and the processing tasks that the service must be able to handle for a successful implementation.

The authentication engine needs to:

• process requests from the federation engine

• forward the user to the federation server after a successful authentication

When processing authentication requests from the server, the engine must process the following incoming data:

• The authentication mechanism to use when challenging the user for identification as a String (identified by oracle.security.fed.authn.authnmech)

• An identifier referencing the current action that is being performed as a String (identified by oracle.security.fed.authn.refid)

• The ProviderID and the description of the remote service provider for which this local authentication is requested, if a Federation SSO operation is performed as a String (identified by oracle.security.fed.authn.providerid and oracle.security.fed.authn.providerdescription).

• The identifier referencing the Engine used to authenticate the user (identified by oracle.security.fed.authn.engineid)

• The identifier of the user as a String, if set (identified by oracle.security.fed.authn.userid)

• The Force Authentication flag, a Boolean object, indicating whether or not the engine should challenge the user even if the user is already authenticated. If missing, False is assumed. (identified by oracle.security.fed.authn.forceauthn)

• The Is Passive flag, a Boolean object, indicating whether or not the engine is allowed to visually interact with the user. If missing, False is assumed. (identified by oracle.security.fed.authn.passive)

• Optionally, a map of attributes that need to be set by the engine: these attributes are required in order for Oracle Identity Federation/IdP to create correctly the assertion with the AttributeStatement, as specified by the configuration for that specific remote provider. (identified by oracle.security.fed.authn.attributes)

  When Oracle Identity Federation receives an SSO assertion, processes it and requests that the user be locally authenticated because the server was not able to map the assertion to a local user, the Map contains this data from the assertion:

  • orafed-nameid-value – the user's Name ID value

  • orafed-nameid-qualifier – the user's Name ID qualifier

  • orafed-nameid-format – the user's Name ID format

  • orafed-providerid – the IdP's ProviderID

  • orafed-assertionid - the ID of the assertion

  • orafed-xmlmessage - the optional XML message containing the assertion.

  See Section 6.13.2, "Provide XML Message to SP Engine after SSO Completes" for details.

• Optionally, a String containing the Oracle Identity Federation session identifier, if the user has already an active session. Oracle Identity Federation is passing the sessionID of the already existing user session (if one exists), to the authentication engine, so that the engine can persist state linked to the user, and it can reference that data by using the sessionID value. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session. (identified by oracle.security.fed.sessionid).

After successful authentication, the engine must forward the user to the federation server with the rootContext of the federation engine being /fed, and the relativePath /user/loginsso.

Oracle Identity Federation expects this data when processing the internal forward:

• The identifier of the user as a String (identified by oracle.security.fed.authn.userid)

• Authentication time as a Date object (identified by oracle.security.fed.authn.authntime)

• Expiration time of the authenticated session as a Date object (identified by oracle.security.fed.authn.expirationtime)

• The authentication mechanism used to identify the user as a String (identified by oracle.security.fed.authn.authnmech)

• The identifier referencing the action that was being performed, from the request (identified by oracle.security.fed.authn.refid)

• The identifier referencing the Engine used to authenticate the user (identified by oracle.security.fed.authn.engineid)

• Optionally, a Map of attributes that will be stored in the user session. This map will have String objects as the keys and a set of objects as the values (identified by oracle.security.fed.authn.attributes).

• Optionally, a String containing the Oracle Identity Federation session identifier that Oracle Identity Federation will need to use to reference the Oracle Identity Federation user session. This allows the engine and Oracle Identity Federation to share the same identifier to reference the user session. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session. (identified by oracle.security.fed.sessionid)

Here are some additional implementation requirements:

• If the service needs to set any cookies, perform this operation before forwarding the user to the federation server.

• Set the cookie path value to "/". This is required because of the internal forwards between the Oracle Identity Federation web application and the authentication engine web application; the user's browser needs to send the cookies related to the authentication engine, even when it is accessing only the federation server. This way, at an internal forward from the federation server to the authentication engine, the cookies set by the engine are available in the HTTP Request.

3.2.5.2.3 Sample Authentication Module for Oracle Single Sign-On Integration

This section describes how to integrate a custom authentication engine with OracleAS Single Sign-On.

Setup

In this example, the application server where Oracle Identity Federation is running has been integrated with the Oracle Single Sign-On server, and the SSO module statically protects the /engine/forward.jsp URL.

Additionally, the user data store configured for Oracle Identity Federation references the Oracle Internet Directory server used by Oracle Single Sign-On.

Packaging

The authentication engine consists of a Web application with a root context set to /engine, and contains two JSP pages:

• authentication.jsp which processes the incoming request from Oracle Identity Federation

• forward.jsp which is protected by Oracle Single Sign-On, and which forwards the user back to the federation server with the required data.

Adding the Engine

To add the engine:

• Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

• Navigate to Administration, then Authentication Engines. Select the Authentication Engines - Custom tab.

• To add an Authentication Engine, click Add and enter a name for that Authentication Engine. Oracle Identity Federation will generate an ID for that new engine: this ID will be reference by TEST_ENGINE_ID for this test

• Select the authentication engine to modify it:

  • Enable the engine.

  • Set "/engine" as the Web Context of the authentication engine

  • Set "/authentication.jsp" as the Login Relative Path of the Authentication Engine

• Click Apply.

Implementation of authentication.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="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 authnMech = (String)request.getAttribute("oracle.security.fed.authn.authnmech");
String refid = (String)request.getAttribute("oracle.security.fed.authn.refid");
 
String redirectURL = "/engine/forward.jsp?refid=" +
   (refid != null ? URLEncoder.encode(refid) : "");
 
response.sendRedirect(redirectURL);
%>

Implementation of forward.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String refid = request.getParameter("refid");
String userID = request.getRemoteUser();
String authnMethod = "oracle:fed:authentication:password-protected";
Date now = new Date();
 
request.setAttribute("oracle.security.fed.authn.engineid", TEST_ENGINE_ID);
request.setAttribute("oracle.security.fed.authn.userid", userID);
request.setAttribute("oracle.security.fed.authn.refid", refid);
request.setAttribute("oracle.security.fed.authn.authnmech", authnMethod);
request.setAttribute("oracle.security.fed.authn.authntime", now);

request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/user/loginsso").forward(request, response);
%>

Since the Oracle Single Sign-On framework sets cookies in the user's browser, the authentication engine should be integrated into the logout flow; see Section 3.2.5.4, "Logout".

3.2.5.2.4 Sample Authentication Module for LDAP Integration

This section shows how to integrate a customized authentication engine with a standalone LDAP server.

Setup

The user data store configured in Fusion Middleware Control for Oracle Identity Federation references the LDAP server used by the Authentication Engine.

Packaging

The authentication engine consists of a Web application with a root context set to /engine, and contains two JSP pages:

• loginpage.jsp, which processes the incoming request from the federation server, and displays the login page.

• ldapforward.jsp, which authenticates the user's credentials against the LDAP server; upon success it forwards the user to the federation server.

Adding the Engine

To add the engine:

1. Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

2. Navigate to Administration, then Authentication Engines. Select the Authentication Engines - Custom tab.

3. To add an Authentication Engine, click Add and enter a name for that Authentication Engine. Oracle Identity Federation will generate an ID for that new engine: this ID will be reference by TEST_ENGINE_ID for this test

4. Select the authentication engine to modify it:

   • Enable the engine

   • Set "/engine" as the Web Context of the authentication engine

   • Set "/loginpage.jsp" as the Login Relative Path of the Authentication Engine

5. Save the changes.

Implementation of loginpage.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="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 refid = request. getAttribute("oracle.security.fed.authn.refid");
 
String postURL = "/engine/ldapforward.jsp?refid=" +
   (refid != null ? URLEncoder.encode(refid) : "");
 
String msg = request.getParameter("message");
%>
<HTML>
<BODY>
<FORM action="<%=postURL%>" method="POST">
<% if(msg != null && msg.length() > 0) { %> <%=msg%><BR/> <%}%>
Username: <INPUT type="text" name="username"/><BR/>
Password: <INPUT type="password" name="password"/><BR/>
<INPUT type="submit" value="Submit"/>
</FORM>
</BODY>
</HTML>

Implementation of forward.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 refid = request.getParameter("refid");
String authnMethod = "oracle:fed:authentication:password-protected";
 
String userID = request.getParameter("username");
String password = request.getParameter("password");
Date now = new Date();
 
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://mynode.us.mycorp.com:389");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "cn=" + userID + ",cn=users,dc=us,dc=oracle,dc=com");
env.put(Context.SECURITY_CREDENTIALS, password);
 
try {
   DirContext ctx = new InitialDirContext(env);
} catch (NamingException ex) {
   String redirectURL = "/engine/loginpage.jsp?refid=" +
      (refid != null ? URLEncoder.encode(refid) : "") + "&message=" + URLEncoder.encode(ex.toString() + " for " + userID);
   response.sendRedirect(redirectURL);
   return;
}
 
request.setAttribute("oracle.security.fed.authn.engineid", TEST_ENGINE_ID);
request.setAttribute("oracle.security.fed.authn.userid", userID);
request.setAttribute("oracle.security.fed.authn.refid", refid);
request.setAttribute("oracle.security.fed.authn.authnmech", authnMethod);
request.setAttribute("oracle.security.fed.authn.authntime", now);
 
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher(“/user/loginsso”).forward(request, response);
%>

Logout

Since no cookies are set in this flow, the authentication engine is not required to integrate with the logout flow (described in Section 3.2.5.4, "Logout").

3.2.5.3.1 Planning a Custom SP Integration Engine

The steps for developing a custom SP integration engine involve:

• creating a service to process requests from Oracle Identity Federation in SP mode

• implementing a module to create an authenticated session for a user at the IAM server

• redirecting the user to the final target URL

• deciding whether the SP integration engine will set a cookie after it creates an authenticated session at the IAM Server. If so, the engine needs to be integrated into the logout process (Section 3.2.5.4, "Logout").

• packaging these services and module into a web application, and deploying it to Oracle WebLogic Managed Server where the federation server is running

• configuring Oracle Identity Federation to reference the new SP Integration module.

• if the SP integration engine accesses a user repository, ensuring that it is the same user data store configured in Fusion Middleware Control for use by Oracle Identity Federation

3.2.5.3.2 Developing and Implementing the Integration Module

This section describes how to develop the integration module and how to implement it in the federation environment.

URLs

Communication between the Identity Federation Engine and the SP integration engine requires internal servlet forwards that are equivalent to API calls. These forwards are achieved with the following JavaEE API:

ServletContext.getContext(String contextPath)
   .getRequestDispatcher(String relativePath)
   .forward(HttpServletRequest request, 
      HttpServletResponse response)

where

• contextPath is the root context path of the web application. For example, the contextPath of Oracle Identity Federation is /fed.

• relativePath is the service URL to which the uses is forwarded, and is relative to the contextPath. For example, when starting a Federation SSO flow, the SP integration engine uses /sp/startsso as the relativePath when forwarding the user.

Oracle Identity Federation needs to be aware of the ID as well as the contextPath and the relativePath of the new SP integration engine; This is the URL that will process the result of the Federation SSO operation after the federation server has processed the incoming assertion.

Adding or Modifying an SP Integration Engine

To add or modify the SP integration engine take these steps:

1. Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

2. Navigate to Administration then SP Integration Modules. Click the Custom SP Engine tab.

3. To add an SP integration engine, click Add and enter a name for that SP integration engine. Oracle Identity Federation will generate an ID for that new engine

   Note:

   the name will only be used in Fusion Middleware Control for display purposes while the ID will be used during communication between Oracle Identity Federation and the Authentication Engine

4. To modify an SP integration engine, select it and:

   • Enable or disable the engine

   • Specify the contextPath of the SP integration engine in the Web Context field

   • Specify the relative path of the login service of the SP integration engine in the Login Relative Path field

   • Select the authentication mechanism to use if a local authentication procedure needs to occur during the assertion processing (this can happen when Federated Identities are used to map the assertion to a user record, if the Federation record does not exist: in this case, the user will need to be locally authenticated in order to perform the one time operation that will create the record)

   • Enable or disable logout

   • Specify the relative path of the logout service of the SP integration engine in the Logout Relative Path field

5. Save your changes.

Implementing the Service

Upon receiving a request from Oracle Identity Federation, the SP integration engine needs to:

• create an authenticated session for the user

• redirect the user to the final URL

To initiate a Federation SSO operation, the SP integration module will need to forward the user to Oracle Identity Federation by specifying the following data as HttpServletRequest attributes:

• An optional authentication mechanism specifying to the SP which authentication mechanism to request the IdP to use during authentication. (identified by oracle.security.fed.sp.authnmech). This parameter is ignored if usedefault is true or missing.

  Note:

  if set, this parameter will be used to determine the IdP to use, as described below, disregarding the usedefault parameter

• An optional Provider ID referencing the IdP to use for the Federation SSO. If missing, Oracle Identity Federation will use the IdP mapped for the specified authentication mechanism. If no IdP could be found, Oracle Identity Federation will use the IdP configured as the default SSO IdP. The value is a String (identified by oracle.security.fed.sp.providerid)

• An optional federation ID referencing the affiliation to use to trigger the Federation SSO, as a String (identified by oracle.security.fed.sp.federationid)

• The relay state. It can contain a small string, for example a reference to some data saved in a repository or a small URL pointing to the protected resource to redirect the user to after completion of the SSO operation. (identified by oracle.security.fed.sp.relaystate)

• The identifier of the SP engine that started the SSO flow, as a String (identified by oracle.security.fed.sp.engineid)

• An optional boolean indicating if Oracle Identity Federation should authenticate the user locally using the authentication engines or if a Federation SSO should be started by redirecting the user to an IdP for authentication, as a Boolean (identified by oracle.security.fed.sp.localauthn ; default is false)

• A Boolean object indicating whether or not to use the configuration stored in Oracle Identity Federation or to only start the SSO based on the information being passed by the SP engine, except the IdP (identified by oracle.security.fed.sp.usedefault). If missing, true is assumed.

• A Boolean object indicating whether or not the SP should ask the IdP to challenge the user even if he/she is already authenticated (identified by oracle.security.fed.sp.forceauthn). This parameter is ignored if usedefault is true or missing.

• A Boolean object indicating whether or not the SP should allow the IdP to create a federation record if one does not yet exist, during the SSO operation (identified by oracle.security.fed.sp.allowfedcreation). This parameter is ignored if usedefault is true or missing.

• A Boolean object indicating whether or not the SP should ask the IdP not to interact with the user during the SSO operation (identified by oracle.security.fed.sp.passive). This parameter is ignored if usedefault is true or missing.

• A String representing the binding to use when sending the AuthnRequest (identified by oracle.security.fed.sp.requestbinding). This parameter is ignored if usedefault is true or missing. Acceptable values are httpredirect, httpost, httppostsimple depending on the protocol

• A String representing the binding to use when sending the Response with the assertion (identified by oracle.security.fed.sp.responsebinding). This parameter is ignored if usedefault is true or missing. Acceptable values are artifact or httpost depending on the protocol.

• An optional authentication mechanism comparison specifying to the SP which authentication context comparison to request the IdP to use during authentication. (identified by oracle.security.fed.sp.authnmechcomparison). This parameter is ignored if usedefault is true or missing.

• A String representing the NameID format the SP will ask to the IdP for the SSO operation (identified by oracle.security.fed.sp.nameidformat). This parameter is ignored if usedefault is true or missing.

Oracle Identity Federation will then perform a SAML/WS-Fed SSO operation with a remote IdP, process the assertion, map it optionally to a local user record and finally will forward the user back to the SP integration engine that initiated the operation by specifying the following information as HttpServletRequest attributes:

• A Boolean object indicating if the SSO operation was successful (identified by oracle.security.fed.sp.authnresult)

• The identifier of the user as a String (identified by oracle.security.fed.sp.userid)

• Authentication time as a Date object (identified by oracle.security.fed.sp.authntime)

• Expiration time of the authenticated session as a Date (identified by oracle.security.fed.sp.expirationtime)

• The authentication mechanism used to identify the user as a String (identified by oracle.security.fed.sp.authnmech)

• The relay state as a String (identified by oracle.security.fed.sp.relaystate)

• The contents of the assertion: the NameID, the issuer of the assertion and the optional attributes. Note: the content of the assertion is not passed as XML Data, that is the original assertion will not be passed back to the module. The data will be passed as a Map with Strings as keys and Set of Objects as values (identified by oracle.security.fed.sp.attributes). The extra data will be referenced as:

  • orafed-nameid-value containing the Name ID value

  • orafed-nameid-qualifier containing the Name ID qualifier

  • orafed-nameid-format containing the Name ID format

  • orafed-providerid containing the Peer ProviderID

  • orafed-assertionid - the ID of the assertion

  • orafed-xmlmessage - the optional XML message containing the assertion

    See Section 6.13.2, "Provide XML Message to SP Engine after SSO Completes" for details.

• The top status of the SAML Response as a String (identified by oracle.security.fed.sp.topstatus)

• The low status of the SAML Response if any, as a String (identified by oracle.security.fed.sp.lowstatus)

• The status message if any as a String (identified by oracle.security.fed.sp.statusmessage)

• The ProviderID that created the SSO assertion as a String (identified by oracle.security.fed.sp.providerid)

• The identifier of the SP engine that will process the above information (identified by oracle.security.fed.sp.engineid)

• A String containing the Oracle Identity Federation identifier of the user session. Oracle Identity Federation is passing the sessionID of the user session to the SP engine, so that it can persist state linked to the user, and it can reference that data by using the sessionID value. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session. (identified by oracle.security.fed.sessionid)

Using this data, the SP integration engine creates an authenticated session and redirects the user to the final target URL.

If the service needs to set cookies, the cookie path must be set to "/". This is necessary because of the internal forwards between the Oracle Identity Federation and SP integration engine web applications; the user's browser needs to send the cookies related to the SP integration engine, even when accessing only the federation server. This way, when an internal forward occurs from the federation server to the SP integration engine, the cookie set by the latter will be available in the HTTP Request.

3.2.5.3.3 Sample Integration Modules

The next two sections provide examples of implementing a custom authentication engine:

• Sample Integration Module 1: Oracle WebLogic Server JavaEE Integration

• Sample Integration Module 2: Customized Single Sign-On Integration

3.2.5.3.4 Sample Integration Module 1: Oracle WebLogic Server JavaEE Container Integration

This section shows a simple SP integration engine that uses the javax.servlet.http.HttpSession to set an attribute. The presence of this attribute shows whether or not a user is authenticated.

Setup

The SP integration engine will not interact with the user data store used by Oracle Identity Federation.

Packaging

The SP integration engine consists of a Web application with a root context set to /engine, and contains two JSP pages:

• wlsintegration.jsp, which processes the request from the federation server and creates an HttpSession with a feduserid attribute containing the user's identifier

• application.jsp, which serves as an application. It looks for the HttpSession's feduserid attribute, and triggers a Federation SSO if the attribute is not found

Adding or Modifying an SP Integration Engine

To add or modify the SP integration engine take these steps:

1. Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

2. Navigate to Administration, then SP Integration Modules. Click the Custom SP Engine tab.

3. To add an SP integration engine, click Add and enter a name for that SP integration engine. Oracle Identity Federation generates an ID for that new engine: this ID will be reference by TEST_ENGINE_ID for this test

4. To modify an SP integration engine, select it and:

   • Enable the engine

   • Set "/engine" as the Web Context of the authentication engine

   • Set "/wlsintegration.jsp" as the Login Relative Path of the SP integration engine

   • Select the authentication mechanism to use if a local authentication procedure needs to occur during the assertion processing (this can happen when Federated Identities are used to map the assertion to a user record, if the Federation record does not exist: in this case, the user will need to be locally authenticated in order to perform the one time operation that will create the record)

5. Save your changes.

Implementation of application.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="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 userid = (String)request.getSession().getAttribute("feduserid");
if (userid == null || userid.length() == 0) {
           request.setAttribute("oracle.security.fed.sp.engineid", TEST_ENGINE_ID);  
request.setAttribute("oracle.security.fed.sp.usedefault", Boolean.TRUE);
request.setAttribute("oracle.security.fed.sp.relaystate", "/engine/application.jsp");
      request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/sp/startsso").forward(request, response);
 return;
}
%>
Welcome <%=userid%>

Implementation of wlsintegration.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String userid = (String)request.getAttribute("oracle.security.fed.sp.userid"); 
String targetURL  = (String)request.getAttribute("oracle.security.fed.sp.relaystate");
 
request.getSession().setAttribute("feduserid", userid);
response.sendRedirect(targetURL);
%>

Logout

Since this application sets up an HttpSession in the Oracle WebLogic Managed Server instance, the SP Integration engine must be integrated in the logout flow (see Section 3.2.5.4, "Logout").

3.2.5.3.5 Sample Integration Module 2: Customized Single Sign-On Integration

This section shows an SP integration engine that uses a simple Single Sign-On framework based on a cookie containing the username and the expiration time of the authenticated session.

Setup

The SP integration engine will not interact with the user data store used by Oracle Identity Federation. The Engine will set up a cookie, for the entire domain, containing the user's identifier as a String variable and the session timeout as a long.

Packaging

The SP integration engine consists of a Web application with a root context set to /engine, and contains two JSP pages:

• domainintegration.jsp, which processes the request from the Oracle Identity Federation server and creates a cookie with the user ID and session timeout

• domainapplication.jsp, which serves as an application. It looks for the cookie and triggers a federation SSO if the cookie is not found.

Adding or Modifying an SP Integration Engine

To add or modify the SP integration engine take these steps:

1. Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

2. Navigate to Administration, then SP Integration Modules. Click the Custom SP Engine tab.

3. To add an SP integration engine, click Add and enter a name for that SP integration engine. Oracle Identity Federation will generate an ID for that new engine: this ID will be reference by TEST_ENGINE_ID for this test

4. To modify an SP integration engine, select it and:

   • Enable the engine

   • Set "/engine" as the Web Context of the authentication engine

   • Set "/domainintegration.jsp" as the Login Relative Path of the SP integration engine

   • Select the authentication mechanism to use if a local authentication procedure needs to occur during the assertion processing (this can happen when Federated Identities are used to map the assertion to a user record, if the Federation record does not exist: in this case, the user will need to be locally authenticated in order to perform the one-time operation that will create the record)

5. Save your changes.

Implementation of domainapplication.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.net.*, java.util.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
Cookie[] cookies = request.getCookies();
String userid = null;
Date timeout = null;
for(int i = 0, size = (cookies != null ? cookies.length : 0); i < size; i++) {
   String name = cookies[i].getName();
   if ("spintegrationcookie".equals(name)){
      String value = cookies[i].getValue();
      StringTokenizer st = new StringTokenizer(value, "*");
      userid = st.nextToken();
      timeout = new Date(Long.parseLong(st.nextToken()));
      break;
   }
}
if (userid == null || userid.length() == 0) {
request.setAttribute("oracle.security.fed.sp.engineid", TEST_ENGINE_ID);  
request.setAttribute("oracle.security.fed.sp.usedefault", Boolean.TRUE);
request.setAttribute("oracle.security.fed.sp.relaystate", "/engine/domainapplication.jsp");
   return;
}
%>
Welcome <%=userid%>. You are logged until <%=timeout%>

Implementation of domainintegration.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String userid = (String)request.getAttribute("oracle.security.fed.sp.userid"); 
String targetURL  = (String)request.getAttribute("oracle.security.fed.sp.relaystate");
Date expirationInst = (Date)request.getAttribute("oracle.security.fed.sp.expirationtime");
String cookieValue = userid + "*" + expirationInst.getTime();
Cookie cookie = new Cookie("spintegrationcookie", cookieValue);
cookie.setDomain(".us.oracle.com");
cookie.setPath("/");
response.addCookie(cookie);
response.sendRedirect(targetURL);
%>

Logout

Since this sample application sets up a domain cookie, the SP Integration engine must be integrated into the logout flow (see Section 3.2.5.4, "Logout").

3.2.5.4.1 Changing Logout Flow

This section contains topics relevant to redirection during logout.

URLs

During the logout operations, the user is being redirected between the federation engine and the logout service of the Authentication and SP integration engines.

Oracle Identity Federation needs to be aware of the location of the logout service in order to redirect the user to the servlet/jsp page for logout. This URL is defined in the Logout location field of the Authentication and SP Integration engines. The URL can be defined as the union of the Web Context of the engine and the Logout Relative path.

Implementing the Logout Service

The operations that need to be performed by the logout service include:

• processing requests from the federation engine, logging the user out of the IAM framework and sending the user back to Oracle Identity Federation

• processing requests from the IAM framework, sending the user to Oracle Identity Federation for logout, receiving the user back from Oracle Identity Federation after logout and sending the user to the IAM framework

Oracle Identity Federation invokes Authn/SP Engine

When Oracle Identity Federation sends the user to the Authentication/SP Engine, it will:

1. Perform an internal forward to the web context and relative logout path of the engine

2. Specify the engine ID of the invoked Engine on the HttpServletRequest the attribute referenced by oracle.security.fed.authn.engineid (if the engine is an Authentication Engine) or oracle.security.fed.sp.engineid (if the engine is an SP Engine)

3. Optionally specify on the HttpServletRequest the attribute referenced by oracle.security.fed.sessionid that will hold the identifier of the user session being logged out (String object)

When the Authentication/SP Engine will have logged the user out, the engine will internally forward the user back to Oracle Identity Federation, it will:

1. Perform an internal forward to the /fed web context and /user/logoutretsso

2. Specify the engine ID of the invoked Engine on the HttpServletRequest the attribute referenced by oracle.security.fed.authn.engineid (if the engine is an Authentication Engine) or oracle.security.fed.sp.engineid (if the engine is an SP Engine), and that attribute value will be the identifier of the engine that performed the logout operation

Authn/SP invokes Oracle Identity Federation

When an Authentication/SP Engine invokes Oracle Identity Federation for logout, it will:

1. Perform an internal forward to the /fed web context and /user/logoutsso

2. Specify the engine ID of the invoked Engine on the HttpServletRequest the attribute referenced by oracle.security.fed.authn.engineid (if the engine is an Authentication Engine) or oracle.security.fed.sp.engineid (if the engine is an SP Engine), and that attribute value will be the identifier of the engine being invoked for logout

3. Specify a return URL where Oracle Identity Federation will redirect the user after logout. That URL will be specified via HttpServletRequest attribute, referenced by oracle.security.fed.logout.returnurl.

At the end of the Logout flow, the user will be logged out from Oracle Identity Federation and redirected to the return URL.

3.2.5.4.2 Sample Logout Services

In the next two sections, these scenarios of logout services are outlined:

• Logout Service Example #1 describes a custom logout service when both the Authentication and SP Integration engines are customized

• Logout Service Example #2 describes a custom logout service when only the SP Integration engine is customized

3.2.5.4.3 Logout Service Example #1

This section describes how to integrate a custom Logout Service, assuming that both the Authentication and SP Integration engines have been customized, that is, the default engines are not used anymore.

Setup

In this example, the authentication engine is the LDAP engine described in section 3.3.2, and the SP integration engine is the Oracle WebLogic Server Integration engine described in Section 3.2.5.3.4, "Sample Integration Module 1: Oracle WebLogic Server JavaEE Container Integration".

Packaging

The Logout service consists of a JSP page bundled with the Authentication and SP Integration engines:

• logout.jsp, which will process the request from Oracle Identity Federation, remove the feduserid attribute from the HttpSession object, set in the wlsintegration.jsp page, and redirect the user to either Oracle Identity Federation or the doneURL parameter.

Updating the Engine

To update the engine:

1. Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

2. Navigate to Administration, then SP Integration Modules. Click the Custom SP Engine tab.

3. To modify an SP integration engine, select it and:

   • Enable logout engine

   • Set "/logout.jsp" as the Logout Relative Path of the SP integration engine

4. Save your changes.

Implementation of logout.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
request.getSession().removeAttribute("feduserid");
 
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/user/logoutretsso").forward(request, response);
%>

3.2.5.4.4 Logout Service Example #2

This section describes how to integrate a custom Logout Service, assuming that the SP Integration engine has been customized.

Setup

In this example, the SP integration engine is the customized SSO Integration engine described in Section 3.2.5.3.5, "Sample Integration Module 2: Customized Single Sign-On Integration".

Packaging

The Logout service consists of a JSP page bundled with the Authentication and SP Integration engines:

• domainlogout.jsp, which will process the request from Oracle Identity Federation, remove the cookie, and redirect the user to the /logoutretsso URL.

Updating the Engine

To update the engine:

1. Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

2. Navigate to Administration, then SP Integration Modules .

3. To modify the SP integration engine, select it and:

   • Enable logout engine

   • Set "/domainlogout.jsp" as the Logout Relative Path of the SP integration engine

4. Save your changes.

Implementation of domainlogout.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
Cookie cookie = new Cookie("spintegrationcookie", "");
cookie.setDomain(".us.oracle.com");
cookie.setPath("/");
cookie.setMaxAge(0);
response.addCookie(cookie);
 
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/user/logoutretsso").forward(request, response);
%>