webservice/readme.txt - manifoldcf-integration-sharepoint-2013 - Git at Google

 # 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
 #
 # http://www.apache.org/licenses/LICENSE-2.0
 #
 # 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:

 http://servername.domain:port/sites/virtualrootname1/subsitelevel1/subsitelevel2/library/folderlevel1/folderlevel2/document.xls

 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.
	# 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
	#
	# http://www.apache.org/licenses/LICENSE-2.0
	#
	# 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:

	http://servername.domain:port/sites/virtualrootname1/subsitelevel1/subsitelevel2/library/folderlevel1/folderlevel2/document.xls

	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.