Any service operation exposed by a DSC can be invoked either anonymously or after performing authentication. Authentication can be performed in two ways

Implicit authentication

Implicitly via creation of ServiceClientFactory - When you create a ServiceClientFactory instance you can provide the credentials through the poperties. This information is later used by the DSC container for authentication purpose. Here you are limited to username/password based authentication.

    Properties props = new Properties();
    props.setProperty("DSC_DEFAULT_EJB_ENDPOINT", "jnp://localhost:1099");
    props.setProperty("DSC_TRANSPORT_PROTOCOL","EJB");          
    props.setProperty("DSC_SERVER_TYPE", "JBoss");
	
	//Here we are setting the credentials which would later be used while invoking the services
    props.setProperty("DSC_CREDENTIAL_USERNAME", "administrator");
    props.setProperty("DSC_CREDENTIAL_PASSWORD", "password");

    //Create a ServiceClientFactory object
    ServiceClientFactory myFactory = ServiceClientFactory.createInstance(props);

Explicit authentication

Explicitly via obtaining an AuthResult by authenticating using one of the methods exposed by AuthenticationManager. The AuthenticationManagerServiceClient implements this interface and you would use it for performing authentication. It provides methods for

• Username/password based authentication
• Certificate based authentication
• Impersonating a user

Apart from that there are overloaded methods for performing domain based authentication. We would discuss these modes in later parts of this series. For now lets authenticate a user

    ...
    //Create a ServiceClientFactory object
    ServiceClientFactory myFactory = ServiceClientFactory.createInstance(props);
    AuthenticationManagerServiceClient authClient = new AuthenticationManagerServiceClient(myFactory);

    //Now use the client to perform authentication using the username and password
    AuthResult authResult = authClient.authenticate(username, password.getBytes());

Once you authenticate you get an AuthResult. It contains an assertion which acts as a sort of security token in LiveCycle. If this token is passed through any of the supported remote access mechanism then LiveCycle would use it for authentication purpose. Before examining the assertion contents lets see how it can be used

   //Create an instance of com.adobe.idp.Context 
   Context context = new Context();
   context.initPrincipal(authResult);

   //Set the context in your ServiceClientFactory instance. 
   myFactory.setContext(context);

Here we create a Context and initialized it with the AuthResult obtained previously. This context is then set in the ServiceClientFactory instance. Now any call made using this factory instance would carry the context and at server side the user’s identity would be established using this context object. At first instance it would look more complicated than the implicit authentication but soon we would see how it can be more useful for us.

SAML Assertion

The assertion which is present in the AuthResult object is actually a serialized SAML assertion. As a user you need not have to interpret its content. You can treat it as an opaque object and just pass it back to LiveCycle for each invocation.

<Assertion xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
    xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
    xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
    AssertionID="fd4bd0c87302780e0d9bbfa8726d5bc0" IssueInstant="2008-04-17T13:47:00.720Z" Issuer="LiveCycle"
    MajorVersion="1" MinorVersion="1">
    <Conditions NotBefore="2008-04-17T13:47:00.720Z" NotOnOrAfter="2008-04-17T15:47:00.720Z">
    </Conditions>
    <AuthenticationStatement
        AuthenticationInstant="2008-04-17T13:47:00.720Z"
        AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:unspecified">
        <Subject>
            <NameIdentifier NameQualifier="DefaultDom">administrator</NameIdentifier>
            <SubjectConfirmation>
                <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</ConfirmationMethod>
            </SubjectConfirmation>
        </Subject>
    </AuthenticationStatement>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
            <ds:SignatureMethod    Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1"></ds:SignatureMethod>
            <ds:Reference URI="#fd4bd0c87302780e0d9bbfa8726d5bc0">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:Transform>
                    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                        <ec:InclusiveNamespaces    xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"
                            PrefixList="code ds kind rw saml samlp typens #default">
                        </ec:InclusiveNamespaces>
                    </ds:Transform>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
                <ds:DigestValue>hVrtqjWr+VzaVUIpQx0YI9lIjaY=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>UMbBb+cUcPtcWDCIhXes4n4FxfU=</ds:SignatureValue>
    </ds:Signature>
</Assertion>

Following are the important aspects for this assertion

• It is valid for certain duration - By default for 2 hrs
• It is issued for a particular user - Here its for administrator
• It is digitally signed. So any modification done to it would break the signature - This is an imporatant point. This assertion content is protected by a xml signature. So any modification done to it would make it invalid.
• It can be presented to LiveCycle as a token of user’s identity similar to username,password

This assertion is confirming to the SAML 1.0 specification. As it is xml based you can also pass it as a part of the Web Service Security Header¹.

Benefits of explicit authentication

Explicit authentication is beneficial in following ways

Firstly you can use it to authenticate using more secure ways like certificates - How would be part of some future post

Secondly you can use it to invoke the LiveCycle services in a more secure way - Lets say you are creating a custom application which invokes the services exposed by LiveCycle. In that a typical requirement is that User A login to the system. Here he authenticates say by providing his credentials. Now at later stage you want to invoke some LiveCycle service on behalf of this user. For this you have following options

• Store the user’s credential locally and make a call to LiveCycle using them - This has an issue that you are holding the user’s credentials in memory. Which is not a good practice in terms of security. If you pass these credentials everytime to the LiveCycle server then you risk them being exposed. You can make it secure by using a secure way to communicate
• Authenticate against the LiveCycle server and store the assertion obtained. Reuse this assertion everytime you communicate with the server. This way even if someone obtains this assertion he can only use it for a certain period time (before the assertion expires). This provides a better level of security than the previous option
• Have a trust relationship with the LiveCycle server and obtain an assertion on behalf of that user. This is called as impersonation and we would talk about it in later part of the series

Hence the SAML assertion stored in AuthResult acts as a security token for a user in LiveCycle. In later part of this series we would see how it can be passed as a part of WS-Security header to impersonate a user. The next post in series would talk of one of the SSO mechanism supported by LiveCycle which is HTTP Header based SSO.

¹ Using SAML assertion in web service authentication is explained at Using SAML based authentication at LiveDocs

To start, lets understand few terms that are used as part of this series. The User Management component (henceforth referred as UM) of LiveCycle handles all the security related items like handling authentication, managing Users, Groups , Roles etc. It provides three important services

• AuthenticationManager - Provides the authentication related methods.
• AuthorizationManager - Provides methods for determining access and authorization.
• DirectoryManager - Provides methods to query the UM domain model. Also provides methods to create, update, search User, Roles etc

Domain model

In brief following are few of the important domain objects provided by UM

• Principal - The most basic entity in UM is a Principal. You can assign Roles to a Principal or assign task. A Principal is extended by User or Group
• User - The name says it all. An User can be created locally or it can be synched from an external repository like Directory Server.
• Group - A Group represent a set of users or groups. One can assign permission, roles to a group which then get percolated to the group members. Groups can be nested. They can be created locally or synched from an external repository.

User Types

For authentication purpose we are more concerned with User. User’s can be broadly classified in two ways

• Local User - These are user’s which are created and managed by UM. You can create such user’s through the AdminUI or through apis exposed by the DirectoryManager. These users can only be authenticated through username/password mechanism
• Enterprise Users - These user’s are synched from an external repository. There authentication is also handled by an external authentication service like a Directory Server. For creating such user you typically create a Domain and synch the users from such external sources

Again our focus would be more on such external users. The concepts would also apply to the local users also (in a limited way)

User Attributes

An enterprise user has following important attributes

• userid - This is the user’s login identifier. Say while authenticating using username and password a user would provide the userid as his username. A user’s userid can change
• canonicalName - This serves as a user’s unique identifier. Refer to this post to understand what constitute as unique identifier. In brief this value should NEVER change for a user

SSO

SSO stands for Single Sign On. In LiveCycle SSO means two things

• SSO between End User UI - This is a new feature introduced in ES U1. It means that if you log into one of the LiveCycle application like Workspace, Content Services etc then you can navigate to any other component’s ui seamlessly. Say if you are in Content Services UI and click on Task’s link then it should open the workspace without you providing your credentials again. This is something which is internal to LiveCycle so as a user you would not have to configure it

• SSO within Enterprise - Cannot think of a better phrase. Anyway it means that if your company already has a SSO solution in place then LiveCycle can integrate with that. Next few post in this series would deal with this area only and we would also discuss about the new SPNEGO based SSO

This was in brief a small introduction to UM lingo. The next post would talk about Users Identity in LiveCycle

If you would like to find out which LiveCycle ES 8.2 services are available with the Foundation and which services come with other licensed products, keep this document bookmarked: http://help.adobe.com/en_US/livecycle/8.2/solutioncomponents_services.pdf

If you are interested in learning more about how to put portfolios together, register for the upcoming "PDF Portfolios and Beyond" session here: http://www.acrobatusers.com/events/online/257/

If you are a LiveCycle customer with external facing forms you should ensure your customer-facing teams are familiar with the new version.

* Active Directory - CN=sampleuser,CN=Users,DC=companydomain,DC=global,DC=company,DC=com
* Sun One - uid=sampleuser,ou=People,O=company.com

For users/groups belonging to an Enterprise domain an unique id is required. This unique id as the name implies uniquely identifies the user/group in the directory server from where it has been synched. Any attribute which is used for unique id should have following two properties

1. Should uniquely identify the user/group - No two unique identifier must be same ever i.e. even if the object gets deleted the same id SHOULD NOT be issued to any new object
2. Should remain constant throughout the object's life time

At a first glance dn of any directory object looks like a perfect fit for unique id. But it does not satisfy the second requirement. Depending on directory server configuration the users may be divided by there departments or any other criteria. So following scenarios may arise

* A user sampleuser belonging to sales dept would initially have dn as cn=sampleuser,ou=sales,ou=example,ou=com. Later the person moves to a different dept and as such his dn would then change and would thus break rule 2
* A user tuser having dn as cn=sampleuser,ou=sales,ou=example,ou=com leaves the company. Another user then joins having the name sampleuser and thus assigned same dn. In that case when that user gets synched in the UM would get the roles given to earlier user which is not correct.

So admin must use an attribute which satisfies both the above conditions. Our recommendations are

* Active Directory - objectGUID
* Sun one - nsuniqueid
* IBM Tivoli - ibm-entryuuid
* Novell directory - guid

Re-start the managed server. Point your debugger at the debug port (1044 in the example above).

If the managed server is being started from a script, the debug arguments should be added to the startup script, instead of within the Admin Console.

var doc = event.target;
doc.resetForm("XMLExampleForm[0].XMLExamplePage1[0].SignatureField1[0]");

In this example the user must enter the Name field to apply a valid signature. If the Name is removed or the Name is not entered, the signature field is cleared.

Unlike IBM HTTP Server, the Proxy Server does not require a lot of configuration. There is no HTTP Plugin to configure and to copy to all nodes. All that is needed is that:
1) you create and run a proxy server, and
2) when the LiveCycle EAR files are deployed, you should map them to the proxy_host virtual host.

The following steps apply to WebSphere 6.1.0.15.

Create Proxy Server
-------------------------
1) Login to the WebSphere Admin Console
2) On the left navigation pane, expand the 'Servers' node
3) Click on 'Proxy Servers'
4) Click the 'New' button
5) Select the node on which you want to run the Proxy Server java process from the dropdownlist of avaiable nodes
6) type in the name of the server (eg: proxy1), click Next
7) uncheck the checkbox for SIP
8) Choose the proxy_server template
9) Click 'Finish' and save the changes

Configure Proxy Server
-----------------------------
1) Click on the Proxy Server you just created
2) In the 'Proxy Settings' section on the right, expand the 'HTTP Proxy Server Settings' node
3) Click on 'Proxy Settings'
4) Check the checkboxes for 'Cache SSL content', 'Cache Aggressively' and 'Cache Dynamic Content' if you desire
5) Save the changes.

For more details, please see Erik Burckart's article in the IBM WebSphere Developer Technical Journal and excerpt from the book WebSphere Application Server: Step by Step.

When deploying LiveCycle EAR files, ensure that you map them to the proxy_host virtual host which has the default port of 80 for HTTP and 443 for HTTPS.

Assuming that the node hosting the proxy server (this can be on the same node as Deployment Manager) is nodeA.company.com, the URL for the LiveCycle AdminUI would be this:
http://nodeA.company.com/adminui

GPU-Z is a free utility that can help you determine your video card type.

Download the sample below and then open with Designer. Once loaded, drag each of the objects from the PDF into the Custom Object Library. Once there, you will be able to drag and drop these on to any of your forms. Better yet, create Form Fragments so if any changes occur you only have to update the data in one place.

First, download this sample WorkspaceCustomizationBatchFiles.zip from https://share.acrobat.com/adc/document.do?docid=bf6c4f37-12e5-11dd-acd1-65538200e0b2. This will provide you with batch files to help extract and then repackage the WorkSpace EAR file (these are not part of LC ES).

Download and unzip the file onto your C:\ drive into a folder of your choosing. No spaces in the folder name. In the directory you will find 4 batch files marked with easy to follow steps. (The last three could have been combined but I wanted to explain what goes on behind the scenes.)

Preparation
Before running any of these steps, you must have the 2.0.1 Flex JDK in your path as well as your Java SDK. Take note that the compile step will not work with the 3.0.0 JDK compiler.

Step1-CreateCustomizableWorkspaceEnvironment.bat
The first step takes the EAR file from your J2EE deploy directory and extracts the files you need to customize the look and feel of WorkSpace. Although not required, you may want to change the WORKING_DIR to direct output to another location. What you will need to do is change the JBOSS_DIR to the directory where your LC EAR files are deployed. If you are using the default turn-key installation you won't need to change this.

The first batch file covers these steps:

Once the first step is complete you can quickly make changes to the images and style sheet that provide you with the look and feel of the default Workspace.

The first image to start with would be the "login_splash.png" which gives you the background on the login screen. You can find this image under C:\WorkspaceCustomization\ExpandedWAR\images\login_splash.png. The next most obvious change would be the "corp-logo.png" image that is displayed at the top left hand corner of WorkSpace. This is found under C:\WorkspaceCustomization\ExpandedWAR\images\corp-logo.png.

You have a choice to change the images by overwriting the existing files or simply change the HeaderPane or loginSplash sections in the C:\WorkspaceCustomization\ExpandedWAR\lc.css style sheet.

Step2-CompileNewSWF.bat
Once the images and style sheet have been changed we need to recompile the workspace-theme.swf file. This can be done by running the step 2 batch file. Again, be sure you are using the 2.0.1 SDK. To check, drop to a command line and run mxmlc.exe to see which version you are using.

Step3-CreateNewWARFile.bat>
The next step is to package up the changes into a WAR file. This step will create a new WAR file under C:\WorkspaceCustomization\NewWAR.

Step4-CreateNewEARFile.bat
Lastly, run step 4 and the new adobe-workspace-client.ear will be created under C:\WorkspaceCustomization\NewEAR.

Deploy the new EAR file
Backup and then delete the original adobe-workspace-client.ear file (Do NOT backup the ear file in the deploy directory or it will remain deployed). Under the default turn-key installation this can be found under C:\Adobe\LiveCycle8\jboss\server\all\deploy\adobe-workspace-client.ear. When you remove the file, you should receive a message in your log that indicates that the application has been undeployed:
2008-04-25 13:14:19,041 INFO [org.jboss.deployment.EARDeployer] Undeploying J2EE application, destroy step: file:/C:/Adobe/LiveCycle8/jboss/server/all/deploy/adobe-workspace-client.ear

Now copy the C:\WorkspaceCustomization\NewEAR\adobe-workspace-client.ear into the C:\Adobe\LiveCycle8\jboss\server\all\deploy directory to deploy the newly customized WorkSpace application.

When deployed correctly your log should indicate that the new application has been deployed:
2008-04-25 13:16:58,364 INFO [org.jboss.deployment.EARDeployer] Started J2EE application: file:/C:/Adobe/LiveCycle8/jboss/server/all/deploy/adobe-workspace-client.ear

To test your new application, go to http://yourmachine:8080/workspace and make sure the changes have taken place (be sure to close and reopen your browser in case any caching has occurred).

You should now have a slightly customized version of WorkSpace deployed!

If you would like to go one step further and create a separate URL for your new WorkSpace, do the following BEFORE running the step 4 batch file.

This is useful when creating Workspace versions that look slightly different for different groups or departments without having to change the underlying Flex application.

From within Flex click on the "Data" menu option and then select "Import Web Service". When the wizard starts you will be prompted for a folder where the Action Script is to be generated. Click on the folder of your choice and then select Next. Now enter the location of your WSDL. Under LiveCycle the default WSDL location is as follows: "http://yourservername:theport/soap/services/servicename?wsdl" (a great reason not to use spaces in your service names).

If your WebService is successfully reached you will then need to select the operation (invoke by default), your package name, and the main class name. If you have problems at this point make sure you can reach the WSDL by using your favorite browser.

If you are not sure where to start with the code that is generated, open the "yourservicenameServiceService.as". It describes the next steps and provides you with sample code.

Don't modify the code. When you make changes to your service on the server, select "Data", "Manage Web Services" and then simply click on the update button. This will prompt you to regenerate the code associated with the service (you will need to change your application yourself of course).