Access Management 7.3.2

Integrate with the Fedlet WAR File

You can integrate your applications with the Java Fedlet to perform many of the SAML v2.0 service provider operations. The Java Fedlet offers the SAML v2.0 capabilities identified in Fedlet Support for SAML v2.0 Features.

Integrate your application

The Fedlet includes the following files that you can use when building your own service provider application:

conf/

Configuration files copied to the $HOME/fedlet directory when you first deploy and configure the Fedlet. When deploying your application, you can move these to an alternate location passed to the Java virtual machine for the web application container at startup. For example, if you store the configuration under the /export/fedlet/ directory, then you could pass the following property to the JVM.

-Dcom.sun.identity.fedlet.home=/export/fedlet/conf

You do not need to include these files in your application.

fedletAttrQuery.jsp

Sample SAML attribute query and response handlers.

fedletEncode.jsp

Utility JSP to encode a password, such as the password used to protect a Java keystore.

fedletSampleApp.jsp

Demo application. You can remove these before deployment to replace them with your application.

fedletXACMLQuery.jsp

Sample SAML XACML query and response handlers.

logout.jsp

Utility page to perform single log out.

saml2/jsp/

JSPs to initiate single sign-on and single logout, and to handle errors, and also a JSP for obtaining Fedlet metadata, saml2/jsp/exportmetadata.jsp.

WEB-INF/classes/

Localized Java properties files for strings used in the Fedlet user interface.

WEB-INF/lib/

Fedlet libraries required by your application.

WEB-INF/web.xml

Fedlet web application configuration, showing how JSPs map to URLs used in the Fedlet. Add mappings for your application before deployment.

In the web.xml mappings, your application must be mapped to /fedletapplication, as this is the assertion consumer URL set in the Fedlet metadata.

<servlet>
  <servlet-name>yourApp</servlet-name>
  <jsp-file>/fedletSampleApp.jsp</jsp-file>
</servlet>
<servlet-mapping>
  <servlet-name>yourApp</servlet-name>
  <url-pattern>/fedletapplication</url-pattern>
</servlet-mapping>

Follow these steps for a demonstration of how to customize demo pages within the Fedlet:

  1. Backup the fedletSampleApp.jsp file.

    $ cd /path/to/tomcat/webapps/fedlet/
$ cp fedletSampleApp.jsp fedletSampleApp.jsp.orig

  2. Edit the fedletSampleApp.jsp file to reduce it to a single redirection to the myapp.jsp page. An implementation of the <html> element of the file follows below.

    <html>
    <head>
        <title>Fedlet Sample Application</title>
        <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
    </head>
    <body>
        <%
         // BEGIN : following code is a must for Fedlet (SP) side application
         Map map;
         try {
             // invoke the Fedlet processing logic. this will do all the
             // necessary processing conforming to SAML v2.0 specifications,
             // such as XML signature validation, Audience and Recipient
             // validation etc.
             map = SPACSUtils.processResponseForFedlet(request, response,
             new PrintWriter(out, true));
             response.sendRedirect("myapp.jsp");
         } catch (SAML2Exception sme) {
             SAMLUtils.sendError(request, response,
             response.SC_INTERNAL_SERVER_ERROR, "failedToProcessSSOResponse",
             sme.getMessage());
             return;
         } catch (IOException ioe) {
             SAMLUtils.sendError(request, response,
             response.SC_INTERNAL_SERVER_ERROR, "failedToProcessSSOResponse",
             ioe.getMessage());
             return;
         } catch (SessionException se) {
             SAMLUtils.sendError(request, response,
             response.SC_INTERNAL_SERVER_ERROR, "failedToProcessSSOResponse",
             se.getMessage());
             return;
         } catch (ServletException se) {
             SAMLUtils.sendError(request, response,
             response.SC_BAD_REQUEST, "failedToProcessSSOResponse",
             se.getMessage());
             return;
         }
         // END : code is a must for Fedlet (SP) side application
        %>
    </body>
</html>

  3. Add a myapp.jsp page to the Fedlet, such as the following:

    <html>
    <head>
        <title>My Application</title>
        <meta http-equiv="Content-Type" content="text/html" />
    </head>
    <body>
        <h1>My Application</h1>
        <p>After you change the <code>fedletSampleApp.jsp</code>, all it does
           is redirect to this home page after successful login.</p>
    </body>
</html>

  4. Go to the Fedlet URL, such as https://openam.example.com:8443/fedlet/, and try one of the login methods.

    After login, you are redirected to the myapp.jsp page.

Perform single sign-on

The Java Fedlet includes a JSP file, saml2/jsp/fedletSSOInit.jsp, that you can call to initiate single sign-on from the Fedlet (SP) side. The Fedlet home page, index.jsp, calls this page when the user does Fedlet-initiated single sign-on.

When calling this JSP, the parameters to use are those also used by the saml2/jsp/spSSOInit.jsp page in AM. The parameters are described in Implement SSO and SLO.

For IDP-initiated single sign-on, call the appropriate page on the identity provider. AM’s page is described in Implement SSO and SLO.

After single sign-on, the user-agent is directed by default to the assertion consumer URI set in the Fedlet metadata, which by default is /fedletapplication. Also by default, that URI points to the JSP, fedletSampleApp.jsp.

Perform single logout

The Java Fedlet includes a JSP file, saml2/jsp/spSingleLogoutInit.jsp, that you can call to initiate single logout from the Fedlet (SP) side. The Fedlet assertion consumer page, fedletSampleApp.jsp, calls this when the user does Fedlet-initiated single logout.

When calling this JSP, the parameters to use are those also used by the saml2/jsp/spSingleLogoutInit.jsp page in AM. Those parameters are described in Implement SSO and SLO.

For IDP-initiated single logout, call the appropriate page on the identity provider. AM’s page is described in Implement SSO and SLO.

Set the RelayState parameter when initiating logout to redirect the user-agent appropriately when the process is complete.