Implementation Guide › Product Integrations › CA DataMinder Content Classification Service Integration

CA DataMinder Content Classification Service Integration

A CA SiteMinder® integration with the CA DataMinder Content Classification Service (CCS) lets the Policy Server use CCS content assessments to make content–aware authorization decisions.

Consider the following items before you begin:

• The integration requires a minimum version of CA SiteMinder®, the CCS, and the CA SiteMinder® Agent for SharePoint.

  Note: For more information, see the CA SiteMinder® Platform Support Matrix.

• Multiple organizational roles are required to enable the integration. Coordinate the integration with the following people:
  • A CCS administrator
  • A CA SiteMinder® administrator
  • The owner of the CA SiteMinder® agent for SharePoint

The purpose of the following diagram is to:

• Illustrate the general relationship between the CCS and CA SiteMinder® components in an integrated environment. The diagram is not intended to represent workflow or represent every component deployed in the integrated environment.
• Associate the individuals responsible for installing or configuring a required component.

  

CA DataMinder Content Classfication Service

The role of the CCS in the integration is to make available predefined content classifications to the CA SiteMinder® Policy Server. The classifications correspond to document types commonly found in a corporate environment. The Policy Server uses the classifications to make content–aware authorization decisions.

As the dotted line in CA DataMinder Content Classification Service illustrates, if a content classification is unavailable at the time of the Policy Server authorization decision, the CCS can request the resource directly to classify or re–classify it. The CCS:

• Passes the result to the Policy Server to make the authorization decision.
• Adds the result to the CCS classification cache for future authorization decisions.

Note: For more information about the CCS and content classifications, see the CA DataMinder Content Classification Service Integration Guide. The guide is included in the CA DataMinder Content Classification Service bookshelf.

CA DataMinder Content Classification Service Preclassification Agent

The role of the CA DataMinder CCS preclassification agent in the integration is to scan and classify SharePoint documents offline. Classifying documents offline avoids the need to retrieve a document classification as part of the Policy Server authorization decision.

Note: For more information about the preclassification agent and classification service scans, see the CA DataMinder Content Classification Service Integration Guide. The guide is included in the CA DataMinder Content Classification Service bookshelf.

CA SiteMinder® Policy Server

The role of the CA SiteMinder® Policy Server in the integration is to act as the Policy Decision Point (PDP). The Policy Server:

• Maintains all authentication and authorization services in the integrated environment.
• Communicates with the CA SiteMinder® agent for SharePoint to retrieve the resource information of the protected document.
• Communicates with the CA DataMinder CCS to retrieve the content classification of the protected document. The Policy Server uses the results to make a content–aware authorization decision.

If configured to do so, the Policy Server can create a single use security token for the CA DataMinder CCS. The CA DataMinder CCS uses the token to request the resource directly. The CCS requests a resource when it must classify or re–classify it as part of the authorization decision.

Note: For more information about applying content classifications to an Enterprise Policy Management application, see the Policy Server Configuration Guide.

CA SiteMinder® Agent for SharePoint

The role of the CA SiteMinder® agent for SharePoint in the integration is to act as the Policy Enforcement Point (PEP). The agent for SharePoint:

• Intercepts the request for the SharePoint document.
• Extracts the resource information of the document.
• Passes the resource information to the Policy Server.

CA SiteMinder® Session Store

The role of the CA SiteMinder® session store is to make available single use security tokens to all Policy Servers in a clustered environment. If configured to do so, a Policy Server creates a security token for the CA DataMinder CCS. The token serves as credentials for the CA DataMinder CCS when it requires access to the protected document.

The CA DataMinder CCS requires access to a protected document when it cannot provide the content classification to the Policy Server. Requesting the resource lets the CCS:

• Classify or re–classify the document.
• Provide the content classification to the Policy Server.
• Add the content classification to the CA DataMinder classification cache for future Policy Server authorization requests.

As part of the process, the agent for SharePoint returns the token to a Policy Server to validate authenticity. If the agent for SharePoint sends the validation request to a Policy Server that did not create the token and the environment:

• Includes a session store, the Policy Server retrieves the token, validates it, and authorizes the CA DataMinder CCS.
• Does not include a session store, the Policy Server cannot validate the token and denies the authorization request.

CA DataMinder Content Classification Service Integration Roadmap

The following diagram:

• Illustrates a sample CA DataMinder and CA SiteMinder® integration.
• Lists the order in which each component is installed and configured.

  

The following table includes each step in the figure and lists the individual responsible for the task.

CA DataMinder CCS Administrator Tasks

The CA DataMinder CCS administrator is responsible for:

• Installing one or more CA DataMinder Content Classification Services and configuring each instance to communicate over SSL. The integration requires that the CA DataMinder Content Classification Service and the CA SiteMinder® Policy Server communicate securely.

  A CA SiteMinder® administrator requires the CCS server certificate file to enable SSL on Policy Server host systems.

  Important! Use the same certificate and password for all CCS instances when configuring them to communicate securely.

• Installing a CA DataMinder CCS preclassification agent to the SharePoint environment and scheduling classification service scans. The CA DataMinder CCS Administration console is installed with the preclassification agent.

Note: For more information, see the CA DataMinder Content Classification Service Integration Guide. The guide is included in the CA DataMinder Content Classification Service bookshelf.

CA SiteMinder® Administrator Tasks

The CA SiteMinder® administrator is responsible for enabling the CA SiteMinder® environment for the integration. Complete the integration steps in the following order:

1. Enable SSL for the integration.
2. Configure the connection to the CA DataMinder CCS.
3. Modify the SharePoint agent configuration object.
4. Enable the DLP exclusion list parameter.
5. Enable an authorization failure message.

Enable SSL for the Integration

The integration requires that the CA DataMinder CCS and the CA SiteMinder® Policy Server communicate securely.

• A CA DataMinder CCS administrator is required to configure all CA DataMinder CCS instances to communicate securely. Request the CCS server certificate from the CA DataMinder administrator before you begin. The server certificate is required to enable SSL for the integration.
• Enabling SSL is a local setting. Complete the following procedure for each Policy Server that is protecting SharePoint documents.

Follow these steps:

1. Create a client certificate chain file. A chain file is a single file that contains the certificate file and the respective private key.

   Important! The file must be in PEM format.

2. Log in to the Policy Server host system.
3. Deploy the CCS server certificate and client certificate chain file.
4. Navigate to siteminder_home\bin\thirdparty\axis2c.
5. Open the following file:

   axis2.xml
   

6. Locate the SERVER_CERT parameter. Replace the sample value with the path to the CCS server certificate file.
7. Locate the KEY_FILE parameter. Replace the sample value with the path to the client certificate chain file.
8. Locate the SSL_PASSPHRASE parameter. Replace the sample value with the passphrase used to encrypt the private key in the client certificate chain file.
9. Save the file.

Configure a Connection to a CA DataMinder Content Classification Service

The Policy Server requires a connection to a CA DataMinder CCS to:

• Retrieve the content classification of a protected document.
• User the content classification to make a content–aware authorization decision.

Configuring the connection is a local setting. Complete the following procedure for every Policy Server that is protecting the SharePoint documents.

Follow these steps:

1. Log in to the Administrative UI with a superuser administrator account.
2. Click Policies, Configure DLP.
3. Select True from the CA SiteMinder® DLP Integration Enabled list.
4. Enter the IP address or fully qualified domain name of the primary CA DataMinder CCS.
5. (Optional) Enter additional configuration parameters.

   Note: For more information about the parameters, click Help.

6. Click Save.
7. Restart the Policy Server to enable the Policy Server for the integration and to configure the connection to the CA DataMinder CCS.
8. Restart any Administrative UI that is registered with the Policy Server that has been restarted.

Modify the SharePoint Agent Configuration Object

Modifying the SharePoint agent configuration object configures the agent to extract resource information from the protected document. The agent passes the information to the Policy Server as part of the authorization process.

Follow these steps:

1. Log in to the Administrative UI.
2. Click Infrastructure, Agent Configuration Objects.
3. Locate the agent configuration object for your SharePoint 2010 agents.
4. Click the edit icon to open the object.
5. Enter the following value for the DLPSupportEnabled parameter:

   SHAREPOINT
   

6. Click Submit.

   The agent configuration object is enabled for the integration.

7. Contact the agent for SharePoint owner. The agent configuration object is the Policy Server counterpart to the web agent configuration file. A separate procedure is required on the web tier to complete the integration for the agent for SharePoint. The agent for SharePoint owner is responsible for completing the task.

Enable the DLP Exclusion List Parameter

The SharePoint 2010 agent configuration object includes the DLP exclusion list parameter. This parameter contains a set of default resources that the Policy Server excludes from CA DataMinder CCS content classifications. Excluding resources from content classifications indicates to SharePoint agents that the resource can be automatically authorized.

The integration requires that you enable the parameter.

Follow these steps:

1. Log in to the Administrative UI.
2. Click Infrastructure, Agent Configuration Objects.
3. Locate the agent configuration object for your SharePoint 2010 agents.
4. Click the edit icon to open the object.
5. Locate the following parameter:

   #DlpExclusionList
   

6. Click the edit icon to open the parameter.
7. Remove the pound sign from the parameter name.
8. If you want to exclude additional resources from content classifications, add the extension to the default set.

   Note: Separate the values with a comma.

9. Click OK.
10. Click Submit.

    The agent configuration object is enabled.

Enable an Authorization Failure Message

By default, when users fail a DLP content check during authorization, they are redirected to a standard HTTP 403 error message.

Enable authorization failure messages to return an alternate, user–friendly message.

Follow these steps:

1. Create the custom error page using either a text file or an HTML file. Consider the following items:
   • You can only redirect users to a custom error page. Applications are not supported.
   • If your environment uses Internet Explorer and you are deploying a custom HTML file, include:
     • A style element in the head element.
     • A trailing line before you close the body element.

     The HTML file requires these items to prevent Internet Explorer from displaying the standard error message, instead of your custom page.

2. Log in to the Administrative UI.
3. Click Infrastructure, Agent Configuration Objects.
4. Locate the agent configuration object for your SharePoint 2010 agents.
5. Click the edit icon to open the object.
6. Locate the following parameter:

   #DlpErrorFile
   

7. Click the edit icon to open the parameter.
8. Remove the pound sign from the parameter name.
9. Enter the location of the custom error page in the Value field.

   Example:

   C:\custompages\dlperror.txt
   

10. Click OK.
11. Click Submit.

    The user–friendly message is enabled.

CA Agent for SharePoint Owner Tasks

The CA Agent for SharePoint administrator is responsible for enabling the SharePoint agent environment for the integration. Complete the integration steps in the following order:

1. If SharePoint is configured for multi–authentication mode, modify the proxy rules.
2. Enable the DLP plug–in.

Modify the Proxy Rules for SharePoint Multi–Authentication

If SharePoint is configured for multi–authentication, specific CA SiteMinder Agent for SharePoint proxy rules are required to ensure that the CA DataMinder CCS classifies your SharePoint resources properly.

Contact the Sharepoint administrator to determine if multi–authentication is configured. If multi–authentication is configured, complete the following procedure.

Important! Do not use any other proxy rule settings when the SharePoint environment is configured for multi–authentication. The CA DataMinder CCS request for resources uses an HTTP header for proper forwarding by the CA SiteMinder Agent for SharePoint. If the CA SiteMinder Agent for SharePoint does not properly forward these requests using the following proxy rules, unauthorized access and disclosure of your protected information is possible.

Follow these steps:

1. Locate the following file on your CA SiteMinder Agent for SharePoint:

   Agent-for-SharePoint_home\proxy-engine\conf\proxyrules.xml
   

2. Rename the previous file using a name similar to the following example:

   proxyrules_xml_default.txt
   

3. Open the following file on your CA SiteMinder Agent for SharePoint with a text editor:

   Agent-for-SharePoint_home\proxy-engine\examples\proxyrules\proxyrules_example2.xml
   

4. Save the previous file as a new file in the following location:

   Agent-for-SharePoint_home\proxy-engine\conf\proxyrules.xml
   

5. Locate the following text in the updated proxyrules.xml file:

   :///$$PROXY_RULES_DTD$$"
   

6. Replace the previous text with the following text:

   :///C:\Program Files\CA\Agent-for-SharePoint\proxy-engine\conf\dtd\proxyrules.dtd"
   

7. Locate the following text:

   http://www.company.com
   

8. Change the previous text to the domain of your organization. Use the following example as a guide:

   http:www.example.com
   

9. Locate the following line:

   <nete:cond type="header" criteria="equals" headername="HEADER">
   

10. Edit the previous line to match the following line:

    <nete:cond type="header" headername="SMSERVICETOKEN">
    

11. Locate the following line:

    <nete:case value="value1">
    

12. Edit the previous line to match the following line:

    <nete:case value="DLP">
    

13. Add a line after the previous line.
14. Copy and paste the following xml syntax onto the new line:

    <nete:xprcond>
    

    <nete:xpr>
    

    <nete:rule>^/_login/default.aspx\?ReturnUrl=(.*)</nete:rule>
    <nete:result>http://sharepoint.example.com:port_number/_trust/default.aspx?trust=siteminder_trusted_identity_provider&amp;ReturnUrl=$1</nete:result>
    </nete:xpr>
    

    <nete:xpr-default>
    

    <nete:forward>http://sharepoint.example:port_number$0</nete:forward>
    

    </nete:xpr-default>
    

    </nete:xprcond>
    

15. Replace both instances of the sharepoint.example:port_number in the previous section with one of the following values:
    • The host name, domain and port number of your hardware load balancer. This hardware load balancer operates between your CA SiteMinder Agent for SharePoint server and the SharePoint servers.
    • host name, domain and port number of your single web front end. In this context, this web front end (WFE) refers a web server that operates in front of your "back end" SharePoint servers.
16. Replace the instance of siteminder_trusted_identity_provider in the previous section with the name of your CA SiteMinder® trusted identity provider.
17. Locate the following line in the file:

    <nete:forward>http://home.company.com</nete:forward>
    

18. Replace the home.company.com in the previous line with one of the following values:
    • The host name, domain and port number of your hardware load balancer. This hardware load balancer operates between your CA SiteMinder Agent for SharePoint server and the SharePoint servers.
    • host name, domain and port number of your single web front end. In this context, this web front end (WFE) refers a web server that operates in front of your "back end" SharePoint servers.
19. Save the file and close your text editor.

    The proxy rules are set.

Enable the DLP Plug–in

Enabling the DLP plug–in configures the agent to extract the resource information from the protected document. The agent passes the information to the Policy Server as part of the authorization process.

Important! A separate procedure is required in the application tier to enable the integration. Do not modify the web agent configuration file before the SharePoint agent configuration object is modified. The CA SiteMinder® administrator is responsible for completing the task.

Follow these steps:

1. Log in to the system hosting your CA SiteMinder Agent for SharePoint.
2. Go to the following location:

   Agent-for-SharePoint_Home\proxy-engine\conf\defaultagent
   

   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

3. Open the following file:

   WebAgent.conf
   

4. Uncomment (remove the # sign to the left of) the line that loads the disambiguation plug–in.

   Example: (Windows [32-bit]) LoadPlugin="C:\Program Files\CA\Agent-for-SharePoint\agentframework\bin\DisambiguatePlugin.dll"

   Example: (Windows [64-bit]) LoadPlugin="C:\CA\Agent-for-SharePoint\agentframework\bin\DisambiguatePlugin.dll"

   Example: (UNIX/Linux) LoadPlugin="/opt/CA/Agent-for-SharePoint/agentframework/bin/DisambiguatePlugin.so"

5. Save the file.
6. Restart the web server.

   The CA SiteMinder Agent for SharePoint is configured for the CA DataMinder integration.

Microsoft SharePoint Administrator Task

The SharePoint Administrator is responsible for providing the CA DataMinder CCS with read access to the SharePoint applications that CA SiteMinder® is protecting. The CA DataMinder CCS requires read access to determine the types of content that protected documents contain.

Providing read access to the CA DataMinder CCS is local to each application. Complete the following procedure for every application that CA SiteMinder® is protecting.

Follow these steps:

1. If the CA CA SiteMinder® Claims provider is configured, the SharePoint loopback search feature is required. If the feature is not enabled, follow these steps:
   1. Click Start, All Programs, Microsoft SharePoint 2010 Products, SharePoint 2010 Management Shell.
   2. Use the management shell to go to the following directory:

      C:\Program Files\CA\SharePointClaimsProvider\scripts
      

   3. Enter the following command:

      .\Set-SMClaimProviderConfiguration.ps1 -EnableLoopBackSearch
      

   4. Loopback search is enabled.
2. Log in to SharePoint Central Administration.
3. Locate the Application Management section and click Manage web applications.

   A list of applications appears.

4. Select an application and click User Policy in the Web Applications ribbon.

   The Policy for Web Application dialog appears.

5. Click Add Users.

   The Add Users wizard appears.

6. Select a Time Zone and click Next.
7. Locate the Users field and click the browse icon.

   The Select People and Groups – Web Page dialog appears.

8. Locate the CA SiteMinder® trusted identity provider. Under the trusted identity provider, click the associated identifier claim.
9. Enter the following value in the Find field and click the search icon:

   caservice
   

10. Double–click the following user icon and click OK.

    caservice
    

    The Add Users dialog appears.

11. Select the following permission and click Finish:

    Full Read - Has full read-only access.
    

    The Policy for Web Application dialog appears.

12. Click OK.

    The CA DataMinder CCS has read access to the application.

Troubleshoot CA DataMinder Content Classifications

Symptom:

One or more of the following symptoms has occurred:

• My users are not getting access to protected document resources.
• My users are experiencing intermittent timeouts or error messages.
• Policy Server performance has degraded.

Solution:

A number of factors can cause the Policy Server to deny access to a document resource. The following checklist can help you identify the problem:

• Be sure that CA SiteMinder® is properly integrated with the CA DataMinder CCS. For more information, see the CA DataMinder CCS integration roadmap.
• Determine if the users are failing normal CA SiteMinder® access. CA SiteMinder® can be protecting a resource (URL) to which the users do not have access.
• Contact the CA DataMinder CCS administrator to determine if the CA DataMinder CCS server is down.
• Review the CA SiteMinder® Policy Server log (smps.log) to determine if the CA DataMinder CCS is down.
• Review the role to which the users are members.

  If the role does not include all content classifications that apply to the document resource, the Policy Server denies access. Do one of the following steps:

  • Add the content classifications to the role.
  • If you want the Policy Server to ignore a content classification when making an authorization decision, remove the classification from the application.
• Review the document for content changes.

  If the content of a document changes, the changes can result in the CA DataMinder CCS classifying it with new content classifications. If the role does not include all content classifications that apply to the document, the Policy Server denies access.

• A CA DataMinder CCS administrator added a content classification to the environment.

  By default, all content classifications are automatically added to CA SiteMinder® applications. New content classifications can inadvertently affect user access. Do one of the following steps:

  • Add the content classification to the role.
  • If you want the Policy Server to ignore a content classification when making an authorization decision, remove the classification from the application.
• The content classification for the requested resource is unavailable during the Policy Server authorization decision. If a content classification is unavailable, the Policy Server denies access. You can configure the Policy Server to request that the CCS classify the document. Follow these steps:
  1. Log in to the Administrative UI with a superuser administrator account.
  2. Click Policies, Configure DLP.
  3. Verify that Request CA DLP Content Classification is set to True.
• In a typical transaction:
  • The web agent request for the protected document requires a Policy Server worker thread.
  • The CA DLP CCS request to classify the protected document requires a Policy Server worker thread.

  There can be insufficient worker threads in the thread pool to handle all requests. We recommend that you increase the maximum number of worker threads, up to twice the current value. For more information about configuring thread settings, see the Policy Server Management Console help system.