TechNote

Configuring SSL authentication for LiveCycle Forms ES and LiveCycle Output ES on UNIX

Configuring LiveCycle Forms ES and LiveCycle Output ES to use protected resources

This article describes how to ensure that Forms ES and Output ES properly render forms that use protected resources or web services.

You must ensure that the form and the LiveCycle ES trust store are properly configured to allow access to the protected resource or web service. If LiveCycle ES cannot authenticate the user or service that is trying to access the protected resource or web service, the protected content is rendered blank in the output.

The following sections describe the required configurations:

• Designing the LiveCycle ES form.
• Configuring the LiveCycle ES trust store.

Designing the LiveCycle ES form

You must design the form template properly to access the secured resource or web service. For information about creating a connection to a secured resource or web service, see the "Authentication (New Data Connection dialog box)" topic in LiveCycle Designer ES Help for Workbench ES.

Configuring the LiveCycle ES trust store

You must configure the LiveCycle ES trust store to contain the necessary security information to authenticate the requesting user or service. This security information may be one of these types:

• User name and password (see Configuring the LiveCycle ES trust store for user name and password authentication)
• SSL client certificate (see Configuring the LiveCycle ES trust store for certificate authentication).

Configuring the trust store for user name and password authentication

Perform the following procedure to configure the trust store to authenticate a user by user name and password (for either basic or digest authentication).

To configure user name and password authentication:

1. Log in to LiveCycle Administration Console and click Settings > Trust Store Management > User and Password Credentials, and then click Add.
2. In the Profile Name box, enter the alias, in one of the following the formats, of the resource or web service that is protected by this credential:
   • For basic and digest authentication, enter [servername]:[realm].
   • For web service authentication, enter the URL of the SOAP endpoint.
3. In the User Name box, enter an appropriate user name.
4. In the Password box, enter the password for the user and click OK.

Configuring the trust store for certificate authentication

You must configure the trust store to store credentials that LiveCycle ES uses when executing authenticated web services. You can use the LiveCycle Administration Console to configure the trust store. (See the "Managing Local Credentials" section in LiveCycle ES Trust Store Management Help.)

Successful client certificate authentication requires certificates from a common certificate authority (CA) on both the LiveCycle ES server and the server hosting the protected resource. You may need to add the CA to the server hosting LiveCycle ES and make it accessible to the LiveCycle ES Javaâ„¢ process. If LiveCycle ES cannot verify a common CA, the certificate-protected resource is not processed and an error message is logged.

LiveCycle ES supports the PKCS#12 type of certificate. LiveCycle ES Update 1 (8.2) provides a default root certificate file (ca-bundle.crt) in one of the following locations:

• (JBoss Application Server) [appserver home]/server/all/svcdata/XMLFormService/bin
• (WebLogic Server) [appserver home]/user_projects/domains/[domain name]/adobe/[server name]/XMLFormService/bin
• (WebSphere Application Server) [appserver home]/AppServer/installedApps/adobe/[server name]/XMLFormService/bin

You may want to add other root certificates that are obtained from other certificate authorities. You can also use any other CA bundle certificate by setting the environment variable CURL_CA_BUNDLE to the location of the file (for example, export CURL_CA_BUNDLE=/home/tools/ca-bundle.crt), and then restarting the application server hosting LiveCycle ES.

Note: It is recommended that you use a custom CA bundle file containing certificates only from authorities that your organization trusts.

You must ensure that the following conditions are met:

• The local certificate file on the server (or server cluster) where LiveCycle ES is deployed contains certificates for all protected resources that LiveCycle ES processes (see the procedure To import a local credential for a protected resource).
• The server hosting the protected resource has a certificate from the same CA that issued the certificate used for client authentication on the LiveCycle ES server (see the To add a root certification authority certificate (Windows) procedure or the To add a root certification authority certificate (UNIX) procedure).

Configuring certificate authentication may require an SSL tool, such as the OpenSSL utility. You can obtain the OpenSSL utility from the following sources:

• OpenSSL for Windows
• OpenSSL source files from which you may compile your own OpenSSL utility for UNIX
• Documentation for OpenSSL and Documentation for OpenSSL for x509 certificates

To import a local credential for a protected resource:

1. Log in to LiveCycle Administration Console and click Settings > Trust Store Management > Local Credentials, and then click Import.
2. On the Import Credential window, do the following:
   • Under Trust Store Type, ensure that Document Signing Credential is selected.
   • In the Alias box, enter the URL to the resource or web service that will be protected with this credential.
   • Beside the Credential box, click Browse, and then navigate to and select the credential that will protect the resource.
   • In the Password box, enter the password for the credential.
3. Click OK.

To add a root certification authority certificate (Windows):

1. From an appropriate certificate authority, obtain additional X.509 root certificates that you require for your LiveCycle ES installation and place them in a location that your LiveCycle ES server can access.
2. On the computer hosting LiveCycle ES, open Internet Explorer and select Tools > Internet Options.
3. On the Content tab, in the Certificates section, click Certificates.
4. In the Certificates dialog box, click Import.
5. On the Welcome to the Certificate Import wizard screen, click Next.
6. On the File to Import screen, click Browse, select a certificate, and then click Next.
7. On the Password screen, in the Password box, enter the password for the credential, and then click Next.

   Note: Ensure that Enable strong private key protection and Mark this key as exportable are properly selected or deselected, as required for your deployment. You can configure either or both of these options as deselected.

8. On the Certificate Store screen, select Place all certificates in the following store, click Browse, select Trusted Root Certification Authorities as the Certificate store, and then click Next.
9. On the Completing the Certificate Import Wizard screen, click Finish.
10. Repeat steps 2 to 9 to add additional root certificates that you obtained in step 1.

To add a root certification authority certificate (UNIX):

1. From an appropriate certificate authority, obtain additional X.509 root certificates that you need for your LiveCycle ES installation.
2. Run the OpenSSL utility to extract the contents of the root certificate file to a plain text file. Use one of the following OpenSSL commands, as appropriate for the format of your root certificate file (in this example, [CertificateFile]), to extract the information to a plain text file (in this example, [TextFile]):
   • If the root certificate file is in .PEM format, use this command:
     opennssl x509 -in [CertificateFile] -text -fingerprint > [TextFile]
   • If the root certificate file is in .DER format (typically used by Microsoft Internet Explorer), use this command:
     opennssl x509 -in [CertificateFile] -text -fingerprint -inform DER > [TextFile]
3. In a text editor, open the ca-bundle.crt file that is used in your LiveCycle ES deployment. The ca-bundle.crt file for a default LiveCycle ES deployment is in one of these locations:
   • (JBoss Application Server) [appserver home]/server/all/svcdata/XMLFormService/bin
   • (WebLogic Server) [appserver home]/user_projects/domains/[domain name]/adobe/[server name]/XMLFormService/bin
   • (WebSphere Application Server) [appserver home]/AppServer/installedApps/adobe/[server name]/XMLFormService/bin
4. Add the plain text results you extracted from the certificate file to the ca-bundle.crt file as an additional entry.

   Caution: Ensure that you match the existing format of the ca-bundle.crt file when you add the information for the new certificate. The format of the information as extracted from the root certificate file may not match the format of existing entries in the ca-bundle.crt file.

5. Repeat steps 2 to 4 to add entries to the ca-bundle.crt file for additional certificates you obtained in step 1.
6. Save the edited ca-bundle.crt file.

Search Support

---