Siteminder Agent for SharePoint and Microsoft SharePoint Office Client Integration
Article ID: 10037
Updated On:
Products
Issue/Introduction
Microsoft SharePoint allows Microsoft Office Documents stored in SharePoint to be accessed directly via the Microsoft Office Clients/User-Agent (Excel, Word, PowerPoint, etc...) instead of the browser; if configured in SharePoint. The Microsoft Office Clients (Excel, Word, PowerPoint, etc...) do not have access to the Transient Cookies stored in the Browser, so these Office Client requests would fail validation against SiteMinder and SharePoint if only Transient cookies were utilized in the environment. The Office Clients would not be able to present a valid transient SMSESSION cookie in the request resulting in a failure to validate the request and SiteMinder would redirect the request for Authentication based on the Authentication scheme protecting the SiteMinder Realm; the request would not be proxied to SharePoint.
The Microsoft Office Clients (Excel, Word, PowerPoint, etc...) do have access to Persistent cookies stored on disk which is why the SharePoint FEDAUTH cookie should be a Persistent cookie. In order for Microsoft SharePoint Office Client Integration requests to be validated by SiteMinder, SiteMinder allows the Agent to create a Persistent "SPSESSION" cookie that will be stored on disk that can be accessed by Microsoft Office Clients (User-Agent) as well. This allows the Office Clients to present the persistent "SPSESSION" cookie in these requests allowing SiteMinder the ability to validate the session and authorize the request when there is no SMSESSION cookie received in the request.
SiteMinder provides the "SPClientIntegration", "SPDisableClientIntegration", and the "SPAuthorizeUserAgent" ACO parameters to allow fined-grained configuration to define which combinations of VirtualHost and User-Agent requests will create the persistent "SPSESSION" cookie, and will also allow processing of a request based on the received SPSESSION cookie.
If a request is received which contains an SMSESSION cookie, it is the transient SMSESSION cookie that will be utilized by the Agent to process the request; even if the request contains a Persistent SPSESSION cookie. If a request contains a Persistent SPSESSION cookie only and the Resolved Host of the request matches an entry in the "SPClientIntegration" list, and the "User-Agent" for the request is defined in the "SPAuthorizeUserAgent" list, than the Agent will utilize the received "SPSESSION" cookie to process the request. If the Resolved Host of the request does not match an entry in the "SPClientIntegration" list or the "User-Agent" of the request does not match an entry in the "SPAuthorizeUserAgent" list, then the Agent will not use the "SPSESSION" cookie for the request and the request would result in a redirect to authenticate based on the authentication scheme protecting the SiteMinder Realm; the request would not be proxied to SharePoint.
Another issue that affects the Office Client Integration requests is a recent change in functionality of the Microsoft Office Clients following Microsoft WEBDAV Hot Fixes 2563214 and 2647954. Prior to these Hotfixes, Office Clients (User-Agent) would include the Persistent Cookies in all the Office Client requests. After applying these hotfixes, initial WEBDAV request such as OPTIONS, PROPFIND, HEAD, etc.., will not include the persistent cookies, which again would result is SiteMinder not being able to validate the request. and a redirect to authenticate being issued.
Without SiteMinder integrated, the Office Clients (User-Agent)will receive a 403 return from SharePoint, and the Office Client will then include the Persistent cookies in the subsequent requests based on this 403 result.
SiteMinder has provided the new "allowedClientMethods" and "allowedUserAgents" Server.conf configuration parameters to define which WEBBDAV methods and User-Agent requests that SiteMinder will return a "403" response instead of a 302 redirect to authenticate response allowing the subsequent Office Client request to be made with the persistent cookies from disk.
It is a Microsoft SharePoint requirement that the user be logged into SharePoint prior to an Office Client request being made.
Environment
PRODUCT: Siteminder
COMPONENT: Web Agent for SharePoint
VERSION: 12.52; 12.8.7
OPERATING SYSTEM: Windows 2016, 2019;
Red Hat 7 & 8
SHAREPONT: 2016; 2019; 22H2 (Subscription Edition)
Resolution
Update the Agent Type to Include the HTTP Methods for WebDAV
To use the Office Client Integration feature, modify the Agent type to include the methods for WebDAV.
Follow these steps:
1. Click Infrastructure -> Agents -> Agent Type -> Modify Agent Type
The Create Agent Type search pane appears.
2. Highlight the text in the search field, and then type the following:
Web Agent
3. Click Search.
The Web Agent type appears in the list.
4. Click Select.
The Modify Agent Type: Web Agent pane appears.
5. Scroll to the bottom of the Actions section, and then click Create.
A new action field appears at the end of the list.
6. Highlight the text in the New Action field, and then enter the following:
Head
7. Scroll to the bottom of the Actions section, and then click Create.
A new action field appears at the end of the list.
8. Repeat Steps 6 and 7 until all of the following methods are added:
OPTIONS
PROPFIND
PROPPATCH
COPY
DELETE
MOVE
LOCK
UNLOCK
9. Click Submit.
The Modify Agent type task is submitted for processing. A confirmation screen appears.
10. Click OK.
The Agent type settings for your SharePoint resources are updated.
Add the HTTP Methods for WebDAV to Your Existing Rules
To use the Office Client Integration feature with the CA SiteMinder Agent for SharePoint, update the web agent actions in any rules protecting SharePoint sites.
Follow these steps:
1. Click Policies, Domains, Rule, Modify Rule.
The Modify Rule screen appears.
2. Click the option button of the domain that contains the rule you want, and then click Select.
Modify Rule: Name screen appears.
3. In the Action drop-down list, press and hold Ctrl and click the following items:
HEAD
OPTIONS
PROPFIND
PROPPATCH
COPY
DELETE
MOVE
LOCK
UNLOCK
4. Click Submit.
5. Repeat Steps 2 through 4 for any additional rules that you want.
The rule is updated, and the confirmation screen appears.
Update your Agent Configuration Settings for Office Client Integration
The parameter settings in the Agent Configuration Object that is associated with your CA SiteMinder Agent for SharePoint control how Office Client Integration operates on your CA SiteMinder Agent for SharePoint.
Follow these steps:
1. Click Infrastructure -> Agent Configuration -> Modify Agent Configuration
2. Click the edit button for the Agent Configuration object of your CA SiteMinder Agent for SharePoint.
The Modify Agent Configuration: Name pane opens.
3. Change the values of the following parameters:
SPClientIntegration
Specifies the hostnames of the SharePoint servers that the Agent for SharePoint protects on which you want to permit Office Client Integration. The default parameter is blank and listed as plain. If there are multiple host entries, use the multivalue option button to add multiple hosts.
Add a port number to the value if the Agent for SharePoint operates on a nondefault port (any port except 80 or 443).
To use this parameter, verify that the SharePoint resources that CA SiteMinder® protects also have their Office Client Integration enabled on the SharePoint central administration server.
Because Office Client Integration requires a persistent FedAuth cookie, verify that your SharePoint server is not configured to use session cookies. By default, UseSessionCookies in SharePoint is set to NO.
Default: None
Limits: Multiple values are allowed. Use fully qualified domain names for all values.
Example: agent_for_sharepoint_host_name.example.com (default ports of 80 or 443)
Example: agent_for_sharepoint_host_name.example.com:81 (with a nondefault port number for HTTP)
Example: agent_for_sharepoint_host_name.example.com:4343 (with a nondefault port number for HTTPS)
SPDisableClientIntegration
Specifies the hostnames of the SharePoint servers that the Agent for SharePoint protects on which you want to prohibit Office Client Integration. The default parameter is blank and listed as plain. If there are multiple host entries, then switch over to a multi—value parameter. The URL in this parameter requires a port number (even for a default port such as 80 or 443).
This setting prevents SharePoint administrators from circumventing CA SiteMinder® settings regarding Office Client integration.
Limit: Multiple values are allowed.
Example: agent_for_sharepoint_host_name:port_number
4. The following parameter describes the user agent values to which the CA SiteMinder Agent for SharePoint permits access:
SPAuthorizeUserAgent
Specifies a list of Microsoft Office user-agent strings for which the Agent for SharePoint allows access. This list is populated automatically with the default values when the Agent for SharePoint starts. The user-agent strings in this parameter act as a whitelist. Changes to this parameter override the default settings. Access is denied to clients whose user-agent string does not appear in the list.
For example, setting the value to Microsoft Office allows access to all versions of Microsoft Office products that are associated with that user-agent string. Conversely, setting the value to Microsoft Office/12.0 allows access to only those versions of Microsoft Office products that are associated with that user-agent string.
Default: Microsoft Office, MS FrontPage, MSFrontPage, Microsoft Data Access Internet Publishing Provider Protocol Discovery, Test for Web Form Existence, Microsoft-WebDAV-MiniRedir
Limits: Multiple values are allowed.
5. Examine the default values of the previous parameter. Ask your SharePoint or IIS web server administrator if more user-agent values are required.
Note: Microsoft (not CA Technologies) defined the user-agent strings in the previous parameter. For more information about these user-strings, search the Microsoft Developer Network (MSDN) library website for information about the user-string that you want.
6. Change the value of the CSSChecking parameter to no.
Note: Because the CA SiteMinder Agent for SharePoint is a proxy-based solution, this setting is required for Office Client Integration.
7. Click OK.
The new values appear next to the parameters in the list.
8. Click Submit.
The Create Agent Configuration Task is submitted for processing and the confirmation message appears.
Configure Session Cookie Timeouts
Configure the Timeout for the FedAuth cookie in Sharepoint to match the MaxTime value for the Realm. The FedAuth cookie is configured to a default of 5 days. If the Session Timeout for the Realm is shorter and the session times out, the user will go into a loop with any cached sessions.
Configure WebDAV For Microsoft
Modify the server.conf File
Adding new directives to the server.conf file on each CA SiteMinder Agent for SharePoint eliminates the error messages that the Microsoft hot fixes cause.
Follow these steps:
1. Log on to the server hosting your CA SiteMinder Agent for SharePoint.
2. Open the following file with a text editor:
Agent-for-SharePoint_Home/secure-proxy/proxy-engine/conf/server.conf
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. Search the file for the following tag:
<SharePoint>
4. Do one of the following tasks:
If the tag in Step 3 is already in the file, remove any comment marks in the section to accommodate the hotfixes. Go to Step 5.
If the tag does not exist in the file, then go to Step 5.
5. Add the following section:
<SharePoint>
allowedClientMethods=”PROPFIND,OPTIONS”
allowedUserAgents=”WebDAV”
</SharePoint>
6. Save the file and close the text editor.
The server.conf file is modified to accommodate the Microsoft hot fixes.
7. Repeat Steps 1 through 6 on all servers running the CA SiteMinder Agent for SharePoint.
Feedback
