Creating Authentication Providers that use Security Tokens

Setting up your development environment
Defining your application logic
Defining the component XML file for the authentication provider

You can create authentication providers for User Management that authenticates a user by using a third-party security token. The authentication provider handles both web service authentication and HTTP-based authentication. The User Management SPI contains a method named authenticate that is invoked to authenticate users. As of LiveCycle, this method accepts a map that contains a security token. The authentication provider responds to an authentication request depending on the AuthScheme that is passed along with the credential. An AuthScheme.THIRDPARTY_SSO_TYPE scheme represents a request for authenticating a user using a security token.

Three attributes types can be passed with the credential map when using the AuthScheme.THIRDPARTY_SSO_TYPE scheme:

AuthProvider.HTTP_REQUEST: Represents an instance of javax.servlet.http.HttpServletRequest
AuthProvider.HTTP_RESPONSE: Represents an instance of javax.servlet.http.HttpServletResponse
AuthProvider.SOAP_MESSAGE_CONTEXT: Represents an instance of javax.xml.rpc.handler.soap.SOAPMessageContext

An authentication token named WebRequestToken encapsulates a state related to a web request (for example, an http request or an http response). Performing an authentication operation using the WebRequestToken results in one of the following three outcomes:

The authentication provider supports the AuthScheme.THIRDPARTY_SSO_TYPE token and is able to determine user's identity.
The authentication provider supports the AuthScheme.THIRDPARTY_SSO_TYPE token. However, the security token located in the request is invalid and an exception is thrown.
The authentication provider does not support AuthScheme.THIRDPARTY_SSO_TYPE and null is returned.

Http request received at /um/login for authentication

An AuthProvider.HTTP_REQUEST is used when the request is received using a SSOFilter (for example, authentication is performed for an end user using a web application). Consider the following steps:

1. If a user navigates to an application by clicking an URL located in a web application. The web application passes a security token (for example, a SAML assertion) as part of a request parameter.

2.The request is redirected to the SSOFilter component configured at /um/login. It also preserves all the request parameters passed to it in step 1.

3. The SSOFilter constructs a WebRequestToken object and passes it to the authentication provider.

4. The authentication provider looks for a preconfigured request parameter and extracts out the relevant information. It then validates the security token and retrieves user details.

5. If you want to develop the web security authentication provider to communicate back to the application as part of authentication procedure, then use the response object.

Web service request

Assume that a web service client invokes a web service exposed by LiveCycle. It passes the security token as part of the ws-security header. The WSSecurity Handler checks the ws-security header. If the authentication provider can determine the type of security token, then the token is validated. If the authentication provider cannot, then the WSSecurity Handler constructs a WebRequestToken object and pass it to the authentication provider.

Summary of steps

To develop a web security authentication provider, perform the following steps:

Set up your development environment.
Define your application logic.
Define the component XML file.
Package the component.

Setting up your development environment

To create a custom authentication provider, create an Eclipse Java project. The version of Eclipse that is supported is 3.2.1 or later. The User Management SPI requires the um-spi.jar file to exist in your project’s class path. If you do not reference this JAR file, you cannot use the User Management SPI in your Java project. This JAR file is installed with the LiveCycle SDK in the <install directory>\sdk\spi folder.

The following JAR files must be added to your project’s classpath:

adobe-livecycle-client.jar
adobe-usermanager-client.jar
um-spi.jar

Defining your application logic

To define an authentication provider, create a Java class that implements the com.adobe.idp.um.spi.authentication.AuthProvider interface. This interface processes authentication requests and provides the name of the configuration node. Implement the following methods, that User Management invokes when it performs user authentication:

authenticate
getConfigName

The following code example demonstrates how to authenticate a user by using information located in the HTTP header value. The example is an implementation of AuthProvider which can authenticate a user based on an HTTP header value. This example validates a user if the user name is part of a set of predefined names. Notice that the authentication provider uses the request object to get the header values.

import java.util.HashSet; 
import java.util.List; 
import java.util.Map; 
import java.util.Set; 
 
import javax.servlet.http.HttpServletRequest; 
 
import com.adobe.idp.um.spi.authentication.AuthConfigBO; 
import com.adobe.idp.um.spi.authentication.AuthProvider; 
import com.adobe.idp.um.spi.authentication.AuthResponse; 
import com.adobe.idp.um.spi.authentication.AuthResponseImpl; 
import com.adobe.idp.um.spi.authentication.AuthScheme; 
 
public class HeaderBasedAuthProvider implements AuthProvider { 
 
     private Set<String> validUsers = new HashSet<String>(); 
 
     public AuthResponse authenticate(Map credential, List authConfigs) { 
     
       String authScheme = (String) credential.get(AUTH_TYPE); 
     
       //Check the AuthScheme 
       if(!AuthScheme.THIRDPARTY_SSO_TYPE.equals(authScheme)){ 
         return null; 
       } 
 
       if(authConfigs.isEmpty()){ 
         throw new IllegalArgumentException("No authConfog provided"); 
       } 
     
       AuthConfigBO ac = (AuthConfigBO) authConfigs.get(0); 
       String domainName = ac.getDomainName(); 
     
       //The request object can be used for checking various parameters as may be required by a SPI 
       HttpServletRequest request = (HttpServletRequest) credential.get(HTTP_REQUEST); 
     
       String userId = request.getHeader("userId"); 
 
       //Probably this request may not contain the required headers. So return null 
       if(userId == null){ 
         return null; 
       } 
     
       AuthResponse ar = new AuthResponseImpl(); 
       ar.setUsername(userId); 
       ar.setDomain(domainName); 
       if(validUsers.contains(userId)){ 
         ar.setAuthStatus(AuthResponse.AUTH_SUCCESS); 
       } 
       return ar; 
     } 
 
     public String getConfigName() { 
        return "SampleAuthenticationManager"; 
    } 
}

Note: Because this example uses the HttpServletRequest data type, ensure that you reference a JAR file, such as J2EE.jar, that defines this type in your class path.

Defining the component XML file for the authentication provider

Create a component XML file to deploy the authentication provider. A component XML file exists for each component and provides metadata about the component. For more information about the component XML file, see the Component XML Reference.

The following component.xml file is used for the authentication provider. Notice that the service name is SampleHTTPAuthenticationManagerService and the operations this service exposes are authenticate and getConfigName.

<component xmlns="http://adobe.com/idp/dsc/component/document"> 
      <component-id>com.adobe.livecycle.samples.authentication.SampleAuthenticationManagerService</component-id> 
      <version>1.0</version>     
      <descriptor-class>com.adobe.idp.dsc.component.impl.DefaultPOJODescriptorImpl</descriptor-class> 
       <class-path>um-spi.jar</class-path> 
      <dynamic-import-packages> 
         <package version="1.0" isOptional="true">*</package> 
      </dynamic-import-packages> 
      <services> 
         <service name="SampleHTTPAuthenticationManagerService"> 
           <implementation-class>HeaderBasedAuthProvider</implementation-class> 
             <specifications> 
                <specification spec-id="com.adobe.idp.um.spi.authentication.AuthProvider"/> 
             </specifications> 
            <operations> 
               <operation name="authenticate" method="authenticate" > 
                  <input-parameter name="credential" type="java.util.Map" /> 
                  <input-parameter name="authConfigs" type="java.util.List" /> 
                  <output-parameter name="echoed-value" type="com.adobe.idp.um.spi.authentication.AuthResponse"/> 
               </operation> 
               <operation name="getConfigName" method="getConfigName" > 
                  <output-parameter name="echoed-value" type="java.lang.String"/> 
               </operation> 
              </operations> 
          </service> 
      </services> 
</component>

Note: For information about packaging your authentication provider, see Packaging the authentication provider.

Note: For information about deploying your authentication provider, see Deploying and testing the authentication provider.