| Oracle® Fusion Middleware Administrator's Guide for Oracle Identity Federation 11g Release 1 (11.1.1) E13400-03 |
|
 Previous |
 Next |
| Oracle® Fusion Middleware Administrator's Guide for Oracle Identity Federation 11g Release 1 (11.1.1) E13400-03 |
|
Previous |
Next |
Custom actions enable site-specific operations to be executed during an Oracle Identity Federation flow before and after an authentication engine or SP integration engine is invoked.
Oracle Identity Federation implements custom actions using the pre- and post-processing action plug-ins. This chapter explains how to implement custom actions.
|
Note: Oracle Identity Federation is also referred to here as the federation server. |
The pre- and post-processing plug-ins are implemented as JSP or JavaEE servlets, invoked during an authentication flow:
before and after invoking an authentication engine
before and after invoking an SP integration engine
You can use custom actions with all authentication engines and SP integration engines, including custom engines. This section explains how the actions work and how they interact with Oracle Identity Federation:
Pre- and Post-Processing Custom Actions for Authentication Engines
Pre- and Post-Processing Custom Actions for SP Integration Engines
Oracle Identity Federation invokes an authentication engine to identify the user when required at run-time. The following steps describe the typical flow of events.
Oracle Identity Federation takes these steps:
determines that the user must be identified
selects the authentication engine to be used
retrieves the location of the authentication engine
internally forwards the user to the authentication engine, specifying the root context and the relative path of the engine's endpoint
The authentication engine, which is a pluggable module that interacts with external authentication providers to establish user identity, takes these steps:
interacts with the user to obtain credentials. For example, an LDAP authentication engine displays a login page to accept user credentials, which are then validated against an LDAP directory.
if successful, internally forwards the user back to Oracle Identity Federation with the authentication information, which consists of the user identifier and the time at which identity was established.
Oracle Identity Federation analyzes the information and creates or updates the user session.
You can use custom actions to:
manipulate the data exchanged between the federation server and the authentication engine; for example, to construct email address from the username johndoe->johndoe@mycompany.com
perform additional steps during authentication; for example, to contact an external data source or system to obtain more information about the user.
To set up a custom action plug-in:
implement a pre-processing action plug-in to be performed before invoking the authentication engine
implement a post-processing plug-in for any actions or changes to be performed after authentication, when the user is redirected from the authentication engine to Oracle Identity Federation
deploy the plug-in to the WebLogic managed server where Oracle Identity Federation is running
configure Oracle Identity Federation to invoke the plug-in instead of the authentication engine so that the plug-in can perform pre-processing tasks
configure the authentication engine to invoke the plug-in instead of redirecting to Oracle Identity Federation, so that the plug-in can perform post-processing tasks.
|
Note: If the default (out-of-the-box) authentication engine is in use, you will need to modify the Oracle Identity Federation configuration; if a custom engine is in use, you will need to update the engine. |
When Oracle Identity Federation is acting as a service provider, either:
the Identity and Access Management (IAM) system, for example Oracle Access Manager, invokes Oracle Identity Federation to perform a federated SSO operation to authenticate the user at a remote identity provider, or
a remote identity provider initiates a federated SSO operation for the user to access a protected resource in the SP domain
When the IAM system invokes Oracle Identity Federation for federated SSO, the flow is as follows:
A user attempts to access a resource protected by the IAM system.
The IAM system determines that the user needs to be authenticated by means of a federated SSO operation.
The IAM system redirects the user to the Oracle Identity Federation SP engine with which it is integrated.
The Oracle Identity Federation SP integration module, which could be a custom module, performs some operations and internally forwards the user to Oracle Identity Federation, specifying the information needed for the operation. For example, it can specify the authentication mechanism to use, the relay state, and so on.
Oracle Identity Federation processes the information, triggers the federated SSO operation, and redirects the user to the remote identity provider for authentication.
The identity provider identifies the user, creates an assertion, and redirects the user back to Oracle Identity Federation/SP.
Oracle Identity Federation validates the assertion, maps it to a user in the local domain, and creates an Oracle Identity Federation session for the user.
Oracle Identity Federation internally forwards the user back to the SP integration module that triggered the flow (or to the default SP integration module in case of an IdP-initiated SSO operation).
The SP integration module processes the data, creates a web access session, and redirects the user to the protected resource.
The IAM system grants the user access to the resource.
You can use custom actions to customize the data exchanged between the federation server and the SP integration module, and perform certain actions in the process.
To set up a custom action plug-in:
implement a pre-processing plug-in when actions or changes must occur before the SP Integration Module redirects the user to Oracle Identity Federation to start the flow.
implement a post-processing plug-in when actions or changes must happen after the federated SSO operation, when the user is redirected from Oracle Identity Federation to the SP Integration Module.
deploy the plug-in to the WebLogic Managed Server where Oracle Identity Federation is running
configure the SP integration module to invoke the plug-in instead of redirecting to Oracle Identity Federation, so that the plug-in can perform the custom tasks.
|
Note: If the default (out-of-the-box) SP integration module is in use, you will need to modify the Oracle Identity Federation configuration; if a custom engine is in use, you will need to update the engine. |
configure Oracle Identity Federation to invoke the plug-in instead of the SP integration module, so the plug-in can perform the custom tasks.
Figure 12-1 explains the custom actions plug-in architecture:
In this figure, Oracle Identity Federation is customized and configured to invoke plug-ins:
before the SP integration engine invokes Oracle Identity Federation
before Oracle Identity Federation invokes the SP integration engine
before Oracle Identity Federation invokes the authentication engine
before the authentication engine invokes Oracle Identity Federation
During a federated SSO operation where Oracle Identity Federation acts as the service provider, the flow is as follows:
An Identity and Access Management (IAM) module such as Oracle Access Manager invokes the SP integration engine to start a federated SSO operation. The SP integration engine invokes the pre-processing plug-in for the SP engine to perform custom actions.
The pre-processing plug-in for SP engine invokes Oracle Identity Federation to start the federated SSO flow.
Oracle Identity Federation redirects the user to an IdP where the user is authenticated and an assertion created.
The IdP redirects the user back to Oracle Identity Federation with an assertion that is validated and mapped to a user.
Oracle Identity Federation bundles the user and assertion data, and invokes the post-processing plug-in for the SP engine to perform some custom tasks.
The post-processing plug-in invokes the SP integration engine by providing the user and assertion data.
The SP engine creates a use session in the IAM domain, and redirects the user to the protected resource.
When Oracle Identity Federation needs to authenticate a user, the flow is as follows:
Oracle Identity Federation, as part of a runtime flow, determines that it needs to locally authenticate the user. It invokes the pre-processing plug-in for the authentication engine to perform some custom tasks.
The pre-processing plug-in invokes the authentication engine.
The authentication engine uses the IAM domain to challenge and identify the user.
The authentication engine bundles the authentication data and invokes the post-processing plug-in for the authentication engine to perform some custom tasks.
The post-processing plug-in for authentication engine invokes Oracle Identity Federation, providing the authentication data.
Oracle Identity Federation resumes operations.
The pre-processing plug-in is a module to which the user is directed, as part of an authentication operation, before invoking the authentication engine. The plug-in enables custom actions to be taken before authentication.
When the plug-in is in use, Oracle Identity Federation does not redirect the user to the authentication engine; rather, it forwards the user internally to the plug-in, passing it certain data for use during authentication. After performing its custom actions, the plug-in forwards the user to the correct authentication engine, along with the data originally provided by the federation server, to resume the authentication flow.
Custom Action Interaction with Oracle Identity Federation
When Oracle Identity Federation redirects a user to the authentication engine, it passes certain data to the engine as attributes on the HttpServletRequest object. The same data is made available to pre-processing plug-ins:
the authentication mechanism to use when challenging the user for identification (String, identified by oracle.security.fed.authn.authnmech)
an identifier referencing the action being performed (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 federated SSO operation is performed (String, identified by oracle.security.fed.authn.providerid and oracle.security.fed.authn.providerdescription respectively)
the identifier referencing the engine used to authenticate the user (String, identified by oracle.security.fed.authn.engineid)
the identifier of the user, if set (String, identified by oracle.security.fed.authn.userid)
the Force Authentication flag, indicating whether the engine should challenge the user even if the user is already authenticated. If missing, false is assumed. (Boolean, identified by oracle.security.fed.authn.forceauthn)
the Is Passive flag, indicating whether the engine is allowed to visually interact with the user. If missing, false is assumed (Boolean, identified by oracle.security.fed.authn.passive)
Optionally, a map of attributes that need to be set by the engine; these attributes are required so that Oracle Identity Federation/IdP can create 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 and processes an SSO assertion, but is not able to map the assertion to a local user, the server requests that the user be locally authenticated. The map then 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
Optionally, the Oracle Identity Federation session identifier, if the user already has an active session. Oracle Identity Federation passes the session identifier of the existing user session to the authentication engine, so that the engine can persist the state linked to the user, and refer to that data using the sessionID value. (String, identified by oracle.security.fed.sessionid)
Later, when the logout flow is executed, Oracle Identity Federation passes the session identifier to the engine, so that the engine can delete the data used for this user session.
Forwarding the User to the Authentication Engine
After processing, the pre-processing plug-in must forward the user to the correct authentication engine (the engine that Oracle Identity Federation would invoke in the absence of the plug-in).
You can use the oracle.security.fed.authn.engineid attribute present in the HttpServletRequest object to determine the path to which the user must be internally forwarded. The possible engine ID values are shown in Table 12-1:
Table 12-1 Engine IDs for Authentication Engines
| Engine ID | Meaning |
|---|---|
|
osso |
Invoke the Oracle Single Sign-On engine by performing a forward to the endpoint referenced by |
|
oam |
Invoke the Oracle Access Manager engine by performing a forward to the endpoint referenced by |
|
ldap |
Invoke the LDAP engine by performing a forward to the endpoint referenced by |
|
rdbmssec |
Invoke the RDBMS security engine by performing a forward to the endpoint referenced by |
|
rdbmstable |
Invoke the RDBMS table engine by performing a forward to the endpoint referenced by |
|
jaas |
Invoke the JAAS engine by performing a forward to the endpoint referenced by |
|
infocard |
Invoke the Infocard engine by performing a forward to the endpoint referenced by |
|
proxy |
Invoke the Fed SSO Proxy engine by performing a forward to the endpoint referenced by |
|
httpheader |
Invoke the HTTP Header engine by performing a forward to the endpoint referenced by |
|
Notes:
|
Configure Oracle Identity Federation to forward the user to a pre-processing plug-in by performing these tasks:
identify the authentication engine whose flow will be modified. Choices are: Oracle SSO, OAM, LDAP, RDBMS Security, RDBMS Table, Proxy, JAAS and Infocard engines
Create or set the following two properties:
the web context property, referencing the web context where the custom JSP Page or servlet of the pre-processing plug-in resides. This property is located in the authnengines group of the Oracle Identity Federation configuration.
the relative path property referencing the path in the web context where the custom plug-in resides.
Table 12-2 shows how to set the properties for each authentication engine:
Table 12-2 Authentication Engine Configuration for Pre-processing Plug-in
| Authentication Engine | web context property | relative path property |
|---|---|---|
|
Oracle Single Sign-On |
osso-login-context (default missing) |
osso-login (default /user/authnosso) |
|
Oracle Access Manager |
oam-login-context (default missing) |
oam-login (default /user/authnoam) |
|
LDAP |
ldap-login-context (default missing) |
ldap-login (default /user/authnldap) |
|
RDBMS Security |
rdbmssec-login-context (default missing) |
rdbmssec-login (default /user/authnrdbmssec) |
|
RDBMS Table |
rdbmstable-login-context (default missing) |
rdbmstable-login (default /user/authnrdbmstb) |
|
JAAS |
jaas-login-context (default missing) |
jaas-login (default /user/authnjaas) |
|
Infocard |
infocard-login-context (default missing) |
infocard-login (default /user/authnic) |
|
Fed SSO Proxy |
proxy-login-context (default missing) |
proxy-login (default /user/authnproxy) |
|
HTTP Header |
httpheader-login-context (default missing) |
httpheader-login (default /user/authnhttp) |
Use the WLST commands to set these properties in the Oracle Identity Federation configuration.
For example, the following commands, in the WLST script environment for the Oracle Identity Federation instance, configure a pre-processing plug-in to be invoked before the Oracle SSO engine:
setConfigProperty('authnengines', 'osso-login-context', '/rootcontext', 'string')
setConfigProperty('authnengines', 'osso-login', '/relativepath', 'string')
The user is directed to the post-processing plug-in module, as part of an authentication operation, after the authentication engine has completed processing and before the user is directed to Oracle Identity Federation. The plug-in enables custom actions to be taken after authentication.
When the plug-in is in use, the authentication engine forwards the user internally to the plug-in, passing it the authentication data. After performing its custom actions, the plug-in forwards the user to Oracle Identity Federation, supplying the authentication data.
|
Note: The available authentication engines are: Oracle SSO, OAM, LDAP, RDBMS Security, RDBMS Table, Proxy, JAAS Infocard, and HTTP Header. |
Custom Action Interaction with Oracle Identity Federation
When the authentication engine redirects the user to Oracle Identity Federation during the authentication flow, it provides the following data to the plug-in as attributes on the HttpServletRequest object:
The identifier of the user (String, identified by oracle.security.fed.authn.userid)
Authentication time (Date, identified by oracle.security.fed.authn.authntime)
Expiration time of the authenticated session (Date, identified by oracle.security.fed.authn.expirationtime)
The authentication mechanism used to identify the user (String, identified by oracle.security.fed.authn.authnmech)
The identifier referencing the action that was being performed, from the request (String, identified by oracle.security.fed.authn.refid)
The identifier referencing the engine used to authenticate the user (String, identified by oracle.security.fed.authn.engineid)
Optionally, a map of attributes to be stored in the user session. This map has String objects as keys and a set of objects as values (identified by oracle.security.fed.authn.attributes).
Optionally, the Oracle Identity Federation session identifier that Oracle Identity Federation uses 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. (String, identified by oracle.security.fed.sessionid)
Later, when the logout flow is executed, Oracle Identity Federation passes the sessionID that is being logged out to the engine, so that the engine can delete the data used for this user session.
|
Notes:
|
To configure Oracle Identity Federation to forward the user to a post-processing plug-in following the authentication flow, set the following properties:
Create or set the web context property, referencing the web context where the custom JSP Page or servlet resides. This property is located in the serverconfig group of the Oracle Identity Federation configuration. Set the authncontext string property in serverconfig, default missing.
Set the relative path property referencing the path in the web context where the custom JSP Page or servlet resides. Set the authnpath string property in serverconfig, default /user/loginsso.
Use the WLST commands to set these properties in the Oracle Identity Federation configuration.
For example, the following commands, in the WLST script environment for the Oracle Identity Federation instance, configure a post-processing plug-in to be invoked after all the authentication engines:
setConfigProperty('serverconfig', 'authncontext', '/rootcontext', 'string')
setConfigProperty('serverconfig', 'authnpath', '/relativepath', 'string')
This section shows a simple post-processing plug-in that is invoked by all the built-in authentication engines before the user is redirected to Oracle 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 it as Oracle Identity Federation session attributes that can then be used during the operation that creates the assertion.
Oracle Identity Federation supports the concept of session attributes set by the authentication engine during a local authentication operation:
Oracle Identity Federation acts as an IdP
The authentication engine flow sets some attributes as session attributes called attr1 and attr2
Oracle Identity Federation is configured to send the session attributes referenced as attr1 and attr2 when creating an assertion for specific service provider partners
This sample shows how a post-processing plug-in can set session attributes in a local authentication flow where a built-in authentication engine is used.
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, containing the preferred language of the user
cookie-homepage, containing the preferred home page of the user
The post-processing plug-in consists of a Web application with a root context set to /plugin, and contains one JSP page, cookieextract.jsp, which extracts the data from the custom cookie and set it as session attributes; the plug-in redirects the user to the federation server by means of an internal forward to resume the flow.
To configure Oracle Identity Federation to invoke the post-processing plug-in before the Oracle Identity Federation server at the end of local authentication flow, take these steps:
Enter the WLST script environment for the Oracle Identity Federation instance.
Set the authncontext property containing the root context of the post-processing plug-in page:
setConfigProperty('serverconfig', 'authncontext', '/plugin', 'string')
Set the authnpath property containing the relative path of the post-processing plug-in page:
setConfigProperty('serverconfig', 'authnpath', '/cookieextract.jsp', 'string')
Exit the WLST script environment.
The JSP looks like this:
<%@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 (request.getAttribute("oracle.security.fed.authn.authntime") != null)
{
// authentication was successful. Attributes will be added
Map attributes = (Map)request.getAttribute("oracle.security.fed.authn.attributes");
if (attributes == null)
{
attributes = new HashMap();
request.setAttribute("oracle.security.fed.authn.attributes", attributes);
}
// 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();
Set languageValues = new HashSet();
languageValues.add(language);
attributes.put("cookie-language", languageValues);
Set homepageValues = new HashSet();
homepageValues.add(homepage);
attributes.put("cookie-homepage", homepageValues);
}
}
// forward to the OIF server to resume the flow
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/user/loginsso").forward(request, response);
%>
The pre-processing plug-in is a module to which the user is directed, as part of an SP SSO flow from an SP integration module, instead of being redirected to the Oracle Identity Federation server to start the Federation SSO operation. The plug-in enables custom actions to be taken before the SSO flow.
When the pre-processing plug-in is in use, the SP integration module internally forwards the user to the plug-in, supplying the runtime data to be used for the federated SSO operation. The plug-in performs custom operations, and forwards the user to Oracle Identity Federation - with the runtime data - to resume the Federation SP SSO flow.
When the SP engine redirects a user to Oracle Identity Federation, it passes certain data to the server as attributes on the HttpServletRequest object. The same data is made available to the pre-processing plug-in.
Here is the data passed to the plug-in:
An optional Provider ID referencing the IdP to use for the federated SSO. If missing, Oracle Identity Federation uses the IdP mapped for the specified authentication mechanism. If no IdP could be found, Oracle Identity Federation uses the IdP configured as the default SSO IdP (String, identified by oracle.security.fed.sp.providerid)
An optional federation ID referencing the affiliation to use to trigger the federated SSO (String, identified by oracle.security.fed.sp.federationid)
The relay state containing a small string, for example a reference to some data saved in a repository or a small URL pointing to the protected resource to which the user is redirected after completion of the SSO operation. (String, identified by oracle.security.fed.sp.relaystate)
The protected resource the user was trying to access, when the SP Engine is an out-of-the-box SP engine (either Oracle Access Manager, Oracle Single Sign-On, or test SP engine). (identified by oracle.security.fed.sp.returnurl)
The identifier of the SP engine that started the SSO flow (String, identified by oracle.security.fed.sp.engineid)
An optional flag indicating if Oracle Identity Federation should authenticate the user locally using the authentication engines or if a federated SSO should be started by redirecting the user to an IdP for authentication (Boolean, identified by oracle.security.fed.sp.localauthn; default is false)
Whether 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 (Boolean, identified by oracle.security.fed.sp.usedefault). If missing, true is assumed.
Whether the SP should ask the IdP to challenge the user even if he/she is already authenticated (Boolean, identified by oracle.security.fed.sp.forceauthn). This parameter is ignored if usedefault is true or missing.
Whether the SP should allow the IdP to create a federation record, if one does not yet exist, during the SSO operation (Boolean, identified by oracle.security.fed.sp.allowfedcreation). This parameter is ignored if usedefault is true or missing.
Whether the SP should ask the IdP not to interact with the user during the SSO operation (Boolean, identified by oracle.security.fed.sp.passive). This parameter is ignored if usedefault is true or missing.
The binding to use when sending the AuthnRequest (String, identified by oracle.security.fed.sp.requestbinding). This parameter is ignored if usedefault is true or missing. Acceptable values are httpredirect, httpost, and httppostsimple depending on the protocol.
The binding to use when sending the response with the assertion (String, 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. (String, identified by oracle.security.fed.sp.authnmechcomparison). This parameter is ignored if usedefault is true or missing.
The NameID format the SP will issue to the IdP for the SSO operation (String, identified by oracle.security.fed.sp.nameidformat). This parameter is ignored if usedefault is true or missing.
Optional attributes to be requested from the IdP during the Federation SSO operation, for example when interacting with an OpenID IdP. The data is passed as a Map with Strings as keys and set of Objects as values (identified by oracle.security.fed.sp.attributes). The values are optional, while the keys contain the attribute names.
|
See Also: Section 10.4.2, "Developing and Implementing the Integration Module" for details about the data provided by the SP integration engine. |
|
Notes:
|
To configure Oracle Identity Federation to forward the user to a pre-processing plug-in at the start of the SP federated SSO flow, set the following properties:
Create or set the web context property, referencing the web context where the custom JSP Page or servlet resides. This property is located in the serverconfig group of the Oracle Identity Federation configuration. Set the spcontext string property in serverconfig, default missing.
Set the relative path property referencing the path in the web context where the custom JSP Page or servlet resides. Set the sppath string property in serverconfig, default /sp/startsso.
Use the WLST commands to set these properties in the Oracle Identity Federation configuration.
For example, the following commands, in the WLST script environment for the Oracle Identity Federation instance, configure a pre-processing plug-in to be invoked prior to the SSO flow:
setConfigProperty('serverconfig', 'spcontext', '/rootcontext', 'string')
setConfigProperty('serverconfig', 'sppath', '/relativepath', 'string')
This example shows a simple pre-processing plug-in, invoked by the out-of-the-box SP engines before the user is forwarded to Oracle Identity Federation to start the Federation SSO operation, to determine the IdP to be used for the Federation SSO operation.
In this example, the local domain has two resources protected by Oracle Access Manager:
http://www.domain.com/resource1, and the IdP to use must be idp1.com
http://www.domain.com/resource2, and the IdP to use must be idp2.com
The pre-processing plug-in consists of a Web application with a root context set to /plugin, and contains one JSP page, fedidpeval.jsp, which evaluates the URL of the protected resource and determines which IdP to use.
To configure the Oracle Access Manager SP engine to invoke the pre-processing plug-in before Oracle Identity Federation processing at the beginning of the federation SSO flow, take these steps:
Enter the WLST script environment for the Oracle Identity Federation instance.
Set the spcontext property containing the root context of the pre-processing plug-in page:
setConfigProperty('serverconfig', 'spcontext', '/plugin', 'string')
Set the sppath property containing the relative path of the pre-processing plug-in page:
setConfigProperty('serverconfig', 'sppath', '/fedusercheck.jsp', 'string')
Exit the WLST script environment.
Implementation of fedusercheck.jsp
Implementation of fedusercheck.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 returnURL = (String) request.getAttribute("oracle.security.fed.sp.returnurl");
String providerid = null;
if (returnURL != null && returnURL.startsWith("http://www.domain.com/resource1"))
{
providerid = "idp1.com";
}
else if (returnURL != null && returnURL.startsWith("http://www.domain.com/resource2"))
{
providerid = "idp2.com";
}
if (providerid != null)
request.setAttribute("oracle.security.fed.sp.providerid", providerid);
// forward to OIF
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/sp/startsso").forward(request, response);
%>
The post-processing plug-in is a module to which the user is directed, as part of a federated SSO operation. The plug-in enables custom actions to be taken after the operation is complete.
When the plug-in is in use, Oracle Identity Federation does not redirect the user to the SP engine; rather, it forwards the user internally to the plug-in, passing it the data resulting from the SSO operation. After performing its custom actions, the plug-in forwards the user to the correct SP engine, along with the data originally provided by the federation server, to resume the authentication flow.
When Oracle Identity Federation redirects the user to the SP engine at the end of the federated SSO flow, it passes certain data to the engine as attributes on the HttpServletRequest object. The same data is made available to the post-processing plug-in.
Here is the data passed to the plug-in:
Whether the SSO operation was successful (Boolean, identified by oracle.security.fed.sp.authnresult)
The identifier of the user (String, identified by oracle.security.fed.sp.userid)
Authentication time (Date, identified by oracle.security.fed.sp.authntime)
Expiration time of the authenticated session (Date, identified by oracle.security.fed.sp.expirationtime)
The authentication mechanism used to identify the user (String, identified by oracle.security.fed.sp.authnmech)
The relay state (String, identified by oracle.security.fed.sp.relaystate)
The protected resource the user was trying to access, when the SP engine is an out-of-the-box SP engine (Oracle Access Manager, Oracle Single Sign-On, or test SP engine); identified by oracle.security.fed.sp.returnurl.
The contents of the assertion consisting of the NameID (the assertion issuer) and the optional attributes.
The assertion content is not passed as XML data, that is, the original assertion is not passed back to the module; rather, the data is passed as a map with strings as keys and a set of objects as values (identified by oracle.security.fed.sp.attributes). The extra data is referenced as:
orafed-nameid-value – the Name ID value
orafed-nameid-qualifier – the Name ID qualifier
orafed-nameid-format – the Name ID format
orafed-providerid – the ProviderID
orafed-assertionid - the ID of the assertion
orafed-xmlmessage - the optional XML message containing the assertion
The top status of the SAML response (String, identified by oracle.security.fed.sp.topstatus)
The low status of the SAML response if any, (String, identified by oracle.security.fed.sp.lowstatus)
The status message if any (String, identified by oracle.security.fed.sp.statusmessage)
The ProviderID that created the SSO assertion (String, identified by oracle.security.fed.sp.providerid)
The identifier of the SP engine to process this information (identified by oracle.security.fed.sp.engineid)
The Oracle Identity Federation identifier of the user session. (String, identified by oracle.security.fed.sessionid)
Oracle Identity Federation passes the sessionID of the user session to the SP engine so it can persist the state linked to the user, and can reference the data using the sessionID value. Later, when the logout flow is executed, Oracle Identity Federation passes the sessionID being logged out to the engine, so that the engine can delete the data used for this user session.
|
Notes:
|
Configure Oracle Identity Federation to forward the user to a post-processing plug-in rather than to the SP engine at the end of the SSO flow by performing these tasks:
identify the SP engine whose flow will be modified. Choices are: Oracle SSO, Oracle Access Manager, Test SP, Proxy engines.
Set the following two properties:
Create or set the web context property, referencing the web context where the custom JSP page or servlet of the post-processing plug-in resides. This property is located in the spengines group of the Oracle Identity Federation configuration.
the relative path property referencing the path in the web context where the custom JSP page or servlet resides.
Table 12-2 shows how to set the properties for each SP engine:
Table 12-3 SP Engine Configuration for Post-processing Plug-in
| SP Engine | web context property | relative path property |
|---|---|---|
|
Oracle Single Sign-On |
osso-login-context (default missing) |
osso-login (default /user/spretosso) |
|
Oracle Access Manager |
oam-login-context (default missing) |
oam-login (default /user/spretoam) |
|
TestSP |
testsp-login-context (default missing) |
testsp-login (default /user/testspretsso) |
|
Fed SSO Proxy |
proxy-login-context (default missing) |
proxy-login (default /user/proxyretsso) |
Use the WLST commands to set these properties in the Oracle Identity Federation configuration.
For example, the following commands, in the WLST script environment for the Oracle Identity Federation instance, configure a post-processing plug-in to be invoked before the Oracle SSO SP engine at the end of the federated SSO operation:
setConfigProperty('spengines', 'osso-login-context', '/rootcontext', 'string')
setConfigProperty('spengines', 'osso-login', '/relativepath', 'string')
This section shows a simple post-processing plug-in to be invoked by Oracle Identity Federation, at the end of a federated SSO and before the Oracle Access Manager SP Engine, to check that the user referenced in the assertion actually belongs to the local domain of the identity provider (IdP).
Oracle Identity Federation can have multiple IdPs as federation partners, each authenticating users on behalf of the Oracle Identity Federation SP and the local domain where the federation server is deployed.
In a typical scenario:
the user is redirected to the IdP for authentication
the IdP creates an assertion containing the user's identity
Oracle Identity Federation/SP maps the incoming assertion to a local user record and creates an authenticated session in the domain.
Some deployments might require Oracle Identity Federation/SP to verify that the user referenced in the assertion belongs to the domain of the assertion issuer; that way, users may only be able to access the services of the SP domain if they used their primary identity providers.
In this example, the assertion Name ID is based on the email address, with the address domain being mapped to a single IdP. The following IdPs are known to Oracle Identity Federation/SP:
http://idp.acme.com/fed/idp, and the corresponding email addresses of the users from this domain is @acme.com
http://samlidp.foo.com/fed/idp, and the corresponding email addresses of the users from this domain is @foo.com
http://fed.bar.com/fed/idp, and the corresponding email addresses of the users from this domain is @bar.com
The post-processing plug-in consists of a Web application with a root context set to /plugin, and contains one JSP page, fedusercheck.jsp, which verifies the assertion data received from the IdP. If the verification is successful the plug-in redirects the user to the Oracle Access Manager SP engine through an internal forward, so that an Oracle Access Manager session can be created, and the user redirected to the protected resource.
To configure Oracle Identity Federation to invoke the post-processing plug-in before the Oracle Access Manager SP engine at the end of the federated SSO flow, take these steps:
Enter the WLST script environment for the Oracle Identity Federation instance.
Set the oam-login-context property containing the root context of the post-processing plug-in page:
setConfigProperty('spengines', 'oam-login-context', '/plugin', 'string')
Set the oam-login property containing the relative path of the post-processing plug-in page:
setConfigProperty('spengines', 'oam-login', '/fedusercheck.jsp', 'string')
Exit the WLST script environment.
The JSP is implemented as follows:
<%@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");
Map attributes = (Map)request.getAttribute("oracle.security.fed.sp.attributes");
String email = (String)attributes.get("orafed-nameid-value");
String providerid = (String)attributes.get("orafed-providerid");
// check that email address is linked to providerid
if ("http://idp.acme.com/fed/idp".equals(providerid))
{
// acme domain
if (!email.endsWith("@acme.com"))
{
throw new Exception("User is invalid: " + email + " does not belong to " + providerid);
}
}
else if ("http://samlidp.foo.com/fed/idp".equals(providerid))
{
// foo domain
if (!email.endsWith("@foo.com"))
{
throw new Exception("User is invalid: " + email + " does not belong to " + providerid);
}
}
else if ("http://fed.bar.com/fed/idp".equals(providerid))
{
// bar domain
if (!email.endsWith("@bar.com"))
{
throw new Exception("User is invalid: " + email + " does not belong to " + providerid);
}
}
else
throw new Exception("Unknown IdP: " + providerid);
// forward to the OAM SP Engine to resume the flow
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/user/spretoam").forward(request, response);
%>
|
 Copyright © 2006, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|