Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Relying Party Enablement Servlet Implementation"

m (API)
(Retrieving Identity Attributes)
Line 28: Line 28:
 
<code><pre>
 
<code><pre>
 
public class AttributeHelper {
 
public class AttributeHelper {
 +
  /**
 +
  * Parse out space-separated claim names and return just the suffix of the
 +
  * claim name
 +
  * @param request the servletrequest whose context will be examined to find
 +
  *  configured claims
 +
  * @param optional whether to process the optional or required claims
 +
  * @return an array of claim suffixes
 +
  */
 +
  public static String[] getSimpleStringClaims(HttpServletRequest request,
 +
                                                boolean optional)
 +
  /**
 +
  * for a given attribute, return the value(s)
 +
  * @param request the servletrequest whose session will be checked for the named
 +
  *        attribute
 +
  * @param attribute - name of attribute stored in session
 +
  * @return an array of values associated with the attribute
 +
  */
 +
  public static String[] getMultiValuedAttribute(HttpServletRequest req,
 +
                                                  String attrname)
 
}
 
}
 
</pre></code>
 
</pre></code>

Revision as of 23:01, 27 January 2008

This is a servlet container implementation of the Relying Party Interface

Details

  • Language: Java
  • Packaging: JAR

Plans

  • The returned attributes are current stored in the session. The plan is to store the information as part of a JAAS Subject.

Service

  • Authentication filter for protected resource. Initializes the authentication protocol handler specified in web.xml.

API

Login

public class Login {
	public static void ContinueAuthentication(HttpServletRequest req,
			HttpServletResponse resp) throws IOException 
	public static boolean handleInvalidRequest(HttpServletRequest req,
			HttpServletResponse resp) {
}

The Login class provides methods to be called from the web application's login page. The login page is invoked once with HTTP GET to display login templates to the user. If the login page is being used with the Information Card authentication protocol handler then the login page must also contain the HTML tags to trigger the Identity Selector for the Information Cards. The GET method of the login page should call handleInvalidRequest and only proceed with the displaying of HTML if the method returns true. If the method will initialize a new authentication session if the request did not have a valid authentication session defined.

The login page will be invoked again with an HTTP POST method after the web application receives and an authentication token. The login page needs to call ContinueAuthentication method to continue the authentication and process the received token. This method calls the authenticate method of the protocol handler to continue processing the authentication. The authentication method of the protocol handler keeps track of authentication state and knows when to transition between states.

Retrieving Identity Attributes

public class AttributeHelper {
  /**
   * Parse out space-separated claim names and return just the suffix of the 
   * claim name
   * @param request the servletrequest whose context will be examined to find 
   *   configured claims
   * @param optional whether to process the optional or required claims
   * @return an array of claim suffixes
   */
   public static String[] getSimpleStringClaims(HttpServletRequest request, 
                                                 boolean optional)
  /**
   * for a given attribute, return the value(s)
   * @param request the servletrequest whose session will be checked for the named
   *        attribute
   * @param attribute - name of attribute stored in session 
   * @return an array of values associated with the attribute
   */
   public static String[] getMultiValuedAttribute(HttpServletRequest req, 
                                                  String attrname) 
}

SPI

The Relying Party Interface package (org.eclipse.higgins.rp.interface) defines a set of SPIs that need to be implemented by each platform implementation. The following SPIs are implemented by the servlet implementation. The DispatchCallbackHandler, ResultCallbackHandler and SessionContextImpl objects are created for each authentication protocol handler and allow the authentication protocol handler code to be platform agnostic.

DispatchCallbackHandler

Implements the Relying Party DispatchCallback interface. This is used to interact with the end-user and is an abstraction of the requestDispatcher interface in servlet containers.

public class DispatchCallbackHandler implements DispatchCallback,Serializable {
    public DispatchCallbackHandler(String authContext, HttpSession httpsession )
    public void redirect(String externalLocation)
    public void forward(String targetLocation)
}

ResultCallbackHandler

Implements the Relying Party ResultCallback interface. Used by the authentication protocol handler to signal success or failure of this authentication session.

public class ResultCallbackHandler implements ResultCallback,Serializable {
    public ResultCallbackHandler(String authSession, HttpSession httpsession )
    public void handleFailure(int errCode) 
    public void handleFailure (int errCode, Throwable rootCause)
    public void handleSuccess(String protectedResource, RPSecurityToken 
                                                       authenticationResult)
}

The handleSuccess method extracts the identity attributes from the authentication result. These results can be access through the AttributeHelper methods (see API section)

SessionContextImpl

Implements the Relying Party SessionContext interface. The routines in this class are used to abstract how a platform stores session attributes and values. For the servlet implementation this abstracts the httpsession interface. This class also has routines to store the name of the original URL (the protected resource). These routines are called by the platform independent authentication protocol handlers.

public class SessionContextImpl implements SessionContext, Serializable{
public SessionContextImpl( String origUri, HttpSession httpsession )
public SessionContextImpl(HttpSession httpsession )
public Object retrieveAttribute(String attribute)
public Object retrieveAttribute(String authContext, String attribute)
public int storeAttribute(String attribute, Object value)
public int storeAttribute(String authContext, String attribute, Object value)
public boolean attributeExists(String attribute)
public boolean attributeExists(String authContext, String attribute)
public void deleteAttribute(String attribute)
public void deleteAttribute(String authContext, String attribute)
public String getProtectedResource()
public String setProtectedResource(String rsrc)
public String getCurrentRequestUrl()
public String getRealPath(String path)
}

RelyingPartyEnablerImpl

Implements the Relying Party RelyingPartyEnabler interface.

Creating a relying party web application

Configuration/development of a web application to use the relying party enablement servlet requires some changes to the web deployment file (web.xml), configuration parameters for the authentication protocol handler configured in the deployment file and creation of a login page to be displayed to the user of the application. The application can also call APIs to retrieve the identity information from the security token used for authentication.

1. Additions to the web application deployment file (WebContent/WEB-INF/web.xml)

In the servlet implementation, authentication is performed through a servlet filter and logout is performed by a servlet. Information about the authentication filter and the logout servlet needs to be added to the application's deployment file. The following lines should be added to the web.xml file inside the <web-app> element:

<web-app ......>
  <filter>
	<filter-name>AuthenticationFilter</filter-name>
	<filter-class>org.eclipse.higgins.rp.servlet.server.AuthNFilter</filter-class>
  </filter>
  <filter-mapping>
	<filter-name>AuthenticationFilter</filter-name>
	<url-pattern>/protected/*</url-pattern>
  </filter-mapping>
  <servlet>
	<description>Logout servlet for filter</description>
	<display-name>Logout</display-name>
	<servlet-name>Logout</servlet-name>
	<servlet-class>
		org.eclipse.higgins.rp.servlet.server.Logout</servlet-class>
  </servlet>
  <servlet-mapping>
	<servlet-name>Logout</servlet-name>
	<url-pattern>/Logout</url-pattern>
  </servlet-mapping>
...
</web-app>

The value of the <bold>url-pattern</bold> in the filter-mapping element should be the name of the resource(s) you want protected by the authentication filter. In the example above all resources in the "protected" directory of the application's context root will require authentication using the authentication filter.

The following servlet context parmaters are configured to define the types of tokens supported, the authentication protocol handlers to configure and the properties file to use for the authentication protocol handlers.

<web-app ......>
...
  <context-param>
	<param-name>TokenTypes</param-name>
	<param-value>urn:oasis:names:tc:SAML:1.0:assertion</param-value>
  </context-param>
  <context-param>	
	<param-name>RootCertUrl</param-name>
	<param-value>TestRoot.cer</param-value>
   </context-param>
   <context-param>
	<param-name>RequiredClaims</param-name>
	<param-value>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier</param-value>	
  </context-param>
  <context-param>	
	<param-name>OptionalClaims</param-name>
	<param-value>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress http://schemas.xmlsoap.org/ws/2005/05/identity/claims/stateorprovince http://schemas.xmlsoap.org/ws/2005/05/identity/claims/postalcode http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country http://schemas.xmlsoap.org/ws/2005/05/identity/claims/homephone</param-value>
  </context-param>
  <context-param>
	<param-name>PrivacyUrl</param-name>
	<param-value>https://localhost/RelyingPartyDemoApp2/Privacy.txt</param-value>
  </context-param>	
  <context-param>
	<param-name>AuthProtocolHandlers</param-name>
	<param-value>org.eclipse.higgins.rp.icard.ICardProtocolHandler</param-value>
  </context-param>
  <context-param>
	<param-name>urn:oasis:names:tc:SAML:1.0:assertionProperties</param-name>
	<param-value>/icard.properties</param-value>
  </context-param>
...
</web-app>	

The values for TokenTypes, RootCertUrl, RequiredClaims, OptionalClaims, PrivacyUrl and AuthProtocolHandlers should be changed to reflect the values that pertain to relying party site and application being written. The last parameter name is derived from the name of the token type concatenated with the string "Properties". The only token type currently supported is urn:oasis:names:tc:SAML:1.0:assertion so the parameter name becomes urn:oasis:names:tc:SAML:1.0:assertionProperties. The value is the name of a file that contains configuration parameters for the authentication protocol handler that supports that token type. See Extensible authentication protocol RP Website Solution#Configuration for details about setting these values.

2. Create a properties file to configuration each authentication protocol handler

The name of the properties file defining configuration parameters for each authentication protocol handler is specified in the web.xml file. The Information Card authentication protocol handler has the following name value pairs in its properties file:

icardLoginPage=../MultiLogin.jsp
icardErrorPage=NoXmlToken.jsp
keystorename=localhost.jks
keystorepw=changeit
keystoretype=JKS
keystorekeyalias=leaf
xmlsecconfig=resource/config.xml

The values of each keyword need to be configured for application. See Extensible authentication protocol RP Website Solution#Configuration for details about setting these values.

3. Create a login page

The name of the login page is specified in the properties file for the authentication protocol handler. The login page is called twice during the process of authentication. The first time it is called from the authentication protocol handler with an HTTP GET method. The login page is invoked again by an HTTP POST method after the Identity Selector has been invoked. Therefore the login page must handle both the GET and POST methods. The following code can be added to the login page (assuming the login page is JSP file):

<%@ page import="org.eclipse.higgins.rp.servlet.server.CxtConstants" %>
<%@ page import="org.eclipse.higgins.rp.servlet.server.AttributeHelper" %>
<%@ page import="org.eclipse.higgins.rp.servlet.server.Login" %>
<%@ page import="org.eclipse.higgins.rp.icard.ICardProtocolHandler" %>
<%@ page import="org.eclipse.higgins.rp.util.RPClaimTypeImpl" %>
<%@ page import ="java.util.Map" %>

<% 
        // Continue Authentication process if this is a POST
	if (request.getMethod().equals("POST")) 
   		Login.ContinueAuthentication(request, response);     	
        else 
	if ( Login.handleInvalidRequest( request, response ) ){
		String authSession = request.getParameter
                              (ICardProtocolHandler.AUTH_SESSION_PARAM );
		Map mp = (Map)request.getSession().getAttribute( authSession );
		ICardProtocolHandler hdlr = (ICardProtocolHandler)mp.get
                               (CxtConstants.PROTOCOL_HANDLER_URI );
%>
add html for GET request here
<% } %> 

For POST the code just needs to call the API to continue the authentication protocol. For GET the code needs to make sure the authentication session, protocol handler and inputs to the protocol handler have been properly initialized before proceeding with the code to trigger the Identity Selector.

Inside the HTML for the GET method is code to trigger the Identity Selector. The following is an example to trigger a Cardspace compatible Identity Selector using an OBJECT tag.

<form name="ctl00" id="ctl00" method="post" action=""> 
    <object type="application/x-informationCard" name="xmlToken">
         <param name="tokenType" value="<%= 
                     request.getSession().getServletContext().getInitParameter(
                                                   CxtConstants.TOKEN_TYPES) %>" />
         <param name="requiredClaims" value="<%= RPClaimTypeImpl.claimListToString(
                                                   hdlr.getRequiredClaims() )%>" />
         <param name="privacyUrl" value="<%= 
               request.getSession().getServletContext().getInitParameter(   
                                                     CxtConstants.PRIVACY_URL)%>" />
         <param name="privacyVersion" value="1" />
         <param name="optionalClaims" value="<%= RPClaimTypeImpl.claimListToString(
                                                      hdlr.getOptionalClaims() )%>" />
    </object>                        						
    <input type="hidden" name="<%= CxtConstants.PROTECTED_RESOURCE %>" value="<%= mp.get(CxtConstants.PROTECTED_RESOURCE) %>" />  					  						            
</form>

The empty action string in the form will cause the same URL to be called on POST. The original resource that is being protected is passed as a parameter to the HTTP POST request. The values for the params in the OBJECT element are extracted from the appliation sevlet context and from the configured authentication protocol handler.

The file MultiLogin.jsp in the WebContent directory of the org.eclipse.higgins.rp.servlet.sample package shows a login page with the above elements.

4. Accessing Identity Attributes

The identity attributes that are extracted from the authentication token are stored as name value pairs in the session store. There are helper routines for an application to call to get the name of the attributes (these are the name of the required and optionals claims requested by the application) and the values for these attributes.

See the APIs for the AttributeHelper class above. To see an example web application that calls these routines see index.jsp in the WebContent/protected directory of the org.eclipse.higgins.rp.servlet.sample package.

Links

Back to the top