|# Licensed to the Apache Software Foundation (ASF) under one or more
|# contributor license agreements. See the NOTICE file distributed with
|# this work for additional information regarding copyright ownership.
|# The ASF licenses this file to You under the Apache License, Version 2.0
|# (the "License"); you may not use this file except in compliance with
|# the License. You may obtain a copy of the License at
|# Unless required by applicable law or agreed to in writing, software
|# distributed under the License is distributed on an "AS IS" BASIS,
|# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|# See the License for the specific language governing permissions and
|# limitations under the License.
|MCPermissions SharePoint Web Service
|I. SharePoint Web Services Model
|The ManifoldCF SharePoint Connector only communicates with SharePoint
|through web services. SharePoint has a well-developed web services API,
|along with a very convenient deployment model which allows additional,
|custom web services to be easily deployed, even across entire SharePoint
|server farms (their notion of a cluster). The intention by Microsoft was clearly
|to make it straightforward for third parties to develop and sell and/or distribute
|custom web services which augment the capabilities of the SharePoint system.
|SharePoint WebServices are usually written in C#. SharePoint itself runs on the
|.NET platform, so the language choice is not technically limited; however, I
|believe that the primary internal API's for SharePoint are all in C#, which does
|tend to push writers of SharePoint web services towards that language.
|II. SharePoint Hierarchy
|SharePoint defines objects in a hierarchical manner, based on http or https urls
|served by IIS. SharePoint hooks into IIS by taking over an
|IIS "website", and serving all paths for that port. There is always a primary "root site",
|which has an empty path, and there can be (optionally) a number of "virtual paths"
|as well, each one of which functions like a root site in everything but name.
|The path of a virtual path root typically has the form: "sites/xxx", but you can define
|virtual paths with any prefix you want.
|Beneath the primary root site and each virtual path root you can find subsites
|(nested as deep as you like, so there are subsites of subsites etc.), libraries, lists,
|and a bunch of other entities we don't really care about. Documents are found only
|in libraries (as far as we know to date). Within a library you can also have folders,
|which grant further structure to the library.
|Here a simple example of a potential SharePoint url:
|In this case, the url describes a document within a folder within an enclosing folder
|within a library that is part of a subsite that is a child of a parent subsite that is the
|child of a virtual path root.
|SharePoint web service .aspx files are always deployed under the "_vti_bin" path
|underneath each root site and subsite.
|III. SharePoint Security Model
|SharePoint uses Active Directory security exclusively. People with appropriate
|rights can attach AD users or groups to various objects in SharePoint. Rights are
|always additive in SharePoint; there is no "deny" tokens. In general, access rights are
|inherited down the hierarchy, unless a user explicitly chooses to break the
|inheritance and set access rights directly for a particular object (and potentially,
|for its children too.)
|A. SharePoint 2.0 Security Model
|In SharePoint 2.0, sometimes called SharePoint 2003, one can attach AD users or
|groups to the following: The SharePoint website as a whole, sites (subsites too), and
|libraries. You cannot set security on folders or files ("items") directly, however.
|B. SharePoint 3.0+ Security Model
|In SharePoint 3.0, sometimes called SharePoint 2007, and in SharePoint 4.0, sometimes
|called SharePoint 2010, one can attach AD users or groups to folders and files in,
|addition to the functionality provided in SharePoint 2.0.
|IV. SharePoint Connector security
|In order for the SharePoint Connector to ingest documents with the proper security,
|it must obtain the list of AD SIDs that apply to each document, and ingest those along
|with the document. This list must take into account SharePoint's notion of access
|inheritance and override.
|Luckily, SharePoint provides, out of the box, a web service that does precisely that for
|the web site, sites, and libraries, called the "Permissions" web service. You use this
|service by providing an identifier (basically, a path) and a type ("web", "site", or "library"),
|and the web service obtains the SIDs of the users and groups for you. Each acl query
|automatically handled the inheritance of SIDs properly also - so if you asked for the
|SIDs for a library, it would take into account inheritance from sites and the global website.
|This web service was sufficient for the SharePoint Connector's security queries in SharePoint 2.0,
|because there was no ability in that release to set permissions directly on folders or files.
|When SharePoint 3.0 was released, and new folder and item security levels were permitted,
|one would have thought that Microsoft would have augmented the Permissions web
|service accordingly. Unfortunately, however, they did not. Nor has the Permissions web
|service been augmented in SharePoint 40.0 No other out-of-the-box
|web services which performed this necessary functionality were available either. We did
|inquire (through Magenic, MetaCarta's SharePoint contractor) whether Microsoft would be willing to
|release an augmented Permissions service as a patch, but they declined to do so.
|As a result, MetaCarta Inc. asked Magenic to provide a web service that did what was needed: give
|access to item and folder level security information. What they eventually provided
|was a web service that looks identical to the Permissions web service, except that it
|understands the types "folder" and "item" as well as the other types. The MCPermissions
|web service also performs the necessary inheritance so that the SharePoint Connector
|could simply ask for the SIDs for an item, and it would get all the inherited SIDs, as appropriate.
|This web service was granted to the Apache Software Foundation by MetaCarta, Inc. as part of
|the entire ManifoldCF software grant.