Agent for SharePoint Guide › Advanced Options › How to Enable SSL for the Agent for SharePoint › Verify the Prerequisites

Verify the Prerequisites

The first step in protecting the ClaimsWS service is verifying the prerequiites.

Verify the following prerequisites before protecting the Claims WS service with SSL:

• Farm administrator privileges and local administrator privileges for each SharePoint server in the farm.
• The java_home variable in your environment points to the proper JDK installation directory.
  For example, if you are using Java 1.6, your java_home variable must point to the installation directory for the Java 1.6 JDK.
• For UNIX/Linux operating environments, verify the following conditions:
  • The Agent for SharePoint environment variables are exported to your environment. Run the following script:

    Agent-for-SharePoint_home\ca_sps_env.sh
    

Create the JCEKS Key Store and Private Key

The next step in protecting the ClaimsWS service is creating a JCEKS key store and private key.

The JCEKS key store is a repository for the certificates and their related private keys. The certificates that you create are stored in the JCEKS key store. Creating a key store also creates a server certificate. This process requires the following information:

• An alias (nickname) for the server certificate you are requesting.
• A password for the JCEKS key store.
• The fully qualified domain name of the server hosting your Agent for SharePoint
• The name of your organizational unit (department or group)
• The name of your organization.
• The locality of your organization.
• The two-letter state and country codes for your organization.

Follow these steps:

1. Log in to the system hosting your Agent for SharePoint.
2. Open a command-line window.
3. Navigate to the following directory:

   Agent_for_SharePoint_home\SSL\keys
   

   Agent-for-SharePoint_Home

   Indicates the directory where the CA SiteMinder Agent for SharePoint is installed.

   Default: (Windows) [32-bit] C:\Program Files\CA\Agent-for-SharePoint

   Default: (Windows) [64-bit] C:\CA\Agent-for-SharePoint
   Default: (UNIX/Linux) /opt/CA/Agent-for-SharePoint

4. Run the following command:

   keytool -genkeypair -keyalg RSA -keystore .\ServerCert.jceks -alias Alias_Name -storetype JCEKS -storepass keystore_password
   

   The following table lists the prompts from the JCEKS keytool utility and sample responses:

The keytool utility displays a confirmation resembling the following example:

Is the following correct: cn=agentforsharepointserver.example.com,ou=support,o=example,l=Your City,st=YS,c=YC

1. Enter yes.

   The keystore and private key are created.

2. Leave the command-line window open, and continue with the next step of creating a certificate request.

Create a Certificate Signing Request and Submit It to a Certificate Authority

The next step in protecting the ClaimsWS service involves creating a certificate signing request for the server certificate in your JCEKS key store.

A signing request submits the certificate to a certificate authority. The certificate authority validates (signs) the certificate. Certificates that are signed third-party certificate authorities are considered more secure than self-signed certificates.

Self-singed certificates are acceptable for evaluation or testing environments.

To submit a certificate signing request, you need the following information:

• The alias of your server certificate for the Agent for SharePoint.
• A file name for your certificate request (.csr file).
• The password for your JCEKS key store.

Follow these steps:

1. Create a certificate signing request with the following command:

   keytool -certreq -v -alias Alias_Name -sigalg MD5withRSA -file .\file_name_of_certificate_request.csr -keypass keystore_password -keystore ServerCert.jceks -storepass keystore_password -storetype JCEKS
   

   The keytool utility produces a certificate signing request similar to the following example:

   -----BEGIN NEW CERTIFICATE REQUEST-----
   MIIBrzCCARgCAQAwbzELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMRMwEQYDVQQHEwpGcmFtaW5n
   aGFtMQswCQYDVQQKEwJDQTEPMA0GA1UECxMGU01URVNUMSAwHgYDVQQDExdzbXNwczIwMTAuc210
   ...
   ...
   ...
   dsrZKqtNaqym7DrkSql7LsUGcsACUp1K4PU6t3P16CKvagspJ18zwTqTRpkGtbu6emvEwpcQveuW
   k27YooCZ4XDzFxtpAnv9EIl7L4N4QHHxXCa8kIULOdGtJ4vD
   -----END NEW CERTIFICATE REQUEST-----
   

2. Copy the entire certificate signing request.
3. Close the command-line window.
4. Submit the certificate signing request to a certificate authority with the following steps:

   Note: This procedure demonstrates submitting a request to a Microsoft Active Directory Certificate Services certificate authority.

   1. Open your Web browser, and then navigate to the following URL:

      https://fully_qualilfied_domain_name_of_server_running_active_directory_certificate_services/certsrv
      

      Note: An example of such a URL is http://certificateauthority.example.com/certsrv.

   2. Click Request a certificate.
   3. Click the advanced certificate request link.
   4. Click the Create and submit a request to this CA.
   5. An Advanced Certificate Request form appears.
   6. Complete the form by doing the following tasks:
      • Submitting a request for a PKCS # 7 file.
      • Copying your certificate signing request into the field

      Note: Under the type of certificate needed drop-down list, verify that Client Authentication Certificate appears.

   7. Click Submit.

      A confirmation dialog appears.

   8. Click Yes.

      The request is submitted. Note your request ID for future reference.

Generate the Certificates by Processing the Request at the Certificate Authority

The next step in protecting the ClaimsWS service is having a certificate authority process your request.

After the certificate authority receives your certificate signing request, they will process the request and will return the signed certificate.

Some organizations use third-party certificate authorities to sign their certificate requests. Other organizations could possibly have an internal group that operates a certificate authority.

The following procedure demonstrates the process for approving a certificate with Microsoft Active Directory Certificate services:

Follow these steps:

Certificate administrators approve or reject certificate requests. Certificate administrator privileges are separate from the Administrator privileges in the Windows operating environment. Not all users who have accounts on the computer hosting Active Directory Certificate services have sufficient privileges to approve or reject certificates.

Use this procedure if you have certificate administrator privileges. Otherwise, ask the certificate administrator in your organization to issue the certificate for you.

Follow these steps:

1. Log in to the web server hosting the Active Directory Certificate services using an account with Certificate administrator privileges.
2. Click Start, Administrative Tools, Certification Authority.

   The certsrv snap-in appears.

3. Click the name of the certification authority, and then click the pending request folder.

   A list of pending certificate requests appears.

4. Right-click the request ID associated with the request for the client certificate.
5. From the context menu, select All Tasks, Issue.

   The certificate is issued.

   Continue with the next step of downloading and importing the certificate.

Download and Import the Certificate Chain

The next step in protecting the ClaimsWS service is downloading and importing the certificate chain.

After your certificate has been signed, download and install the following items to the server hosting your Agent for SharePoint:

• The signed certificate.
• The certificate chain (any additional certificate-authority certificates that your certificate-authority issued).

The certificate chain validates your certificate to the web browsers of your users.

This process requires the following information:

• The alias (nickname) of the server certificate you are requesting.
• The password for the JCEKS key store.

Follow these steps:

1. Log in to the server hosting your Agent for SharePoint.
2. Download the following files with the same Web browser from which sent the certificate signing request:
   • certnew.cer (your signed certificate)
   • certnew.p7b (the certificate chain)
3. Move the files that you downloaded in Step 2 to the following directory:

   Agent_for_SharePoint_home/SSL/keys
   

4. Import the certificate chain into the keystore with the following command;

   keytool -importcert -v -noprompt -alias Alias_Name -file .\certnew.p7b -keypass keystore_password -keystore ServerCert.jceks -storepass keystore_password -storetype JCEKS
   

5. Continue with the next step of defining the claims store and the SSL ports.

Define the KeyStore and the SSL Ports

The next step in protecting the ClaimsWS service is defining the key store and SSL ports.

After downloading and importing the certificate chain to the server hosing the Agent for SharePoint, add the following settings:

• The local SSL port number (defined when you ran the SharePoint Connection wizard).
• The path to the key store on the server that is hosting the Agent for SharePoint.

These settings are defined in the server.conf file.

Follow these steps:

1. Open the following file with a text editor:

   Agent_for_SharePoint_home\proxy-engine\conf\server.conf
   

   Locate the following section of the file:

   <localapp>
   

2. In the <localapp> section, locate the following line:

   #local.https.port=port_number
   

3. Remove the # from the beginning of the previous line.
4. Verify that the port number following the equal sign matches what you entered for the Claims WS service SSL port in the SharePoint connection wizard. If you defined port number 2525 for your connection, the edited line would match the following example:

   local.https.port=2525
   

5. Locate the following line:

   #local.https.keyStoreFileName="tomcat.keystore"
   

6. Remove the # from the beginning of the previous line.
7. Replace the tomcat.keystore with the relative path to the keystore you created for the keys and certificates that are associated with the Claims WS service. If the relative path to your keystore is ServerCert.jceks, then the edited line would match the following example:

   local.https.keyStoreFileName="ServerCert.jceks"
   

8. Save the file and close text editor.
9. Continue with the next step of generating an SSLConfig.properties file.

Generate an SSLConfig.properties File

The next step of protecting the ClaimsWS service involves generating an SSLConfig.properties file for the keystore.

Follow these steps:

1. On the server hosting your Agent for SharePoint, open a command-line window.
2. If you have not yet created the TrustStore, run the following command:

   GenerateSSLConfig -keystorepass keystore_password
   

3. When prompted, enter the following values:
   • keystore_password (keystore password)
   • false (Enable Client Authentication)

   Important! Do not enable client authentication yet.

Restart the Agent for SharePoint

Starting or stopping the Agent for SharePoint involves the following separate procedures:

1. Changing the value of EnableWebAgent in the WebAgent.conf file.
2. Changing the state of the related services on the computer running the Agent for SharePoint.