SharePoint Connector

The Java-based SharePoint connector is built with the DirX Identity Connector Integration Framework and can be used for validation workflows in the C++-based Server and real-time workflows in the IdS-J-Server. Like all framework-based agents, it gets SPML requests from the Identity side and converts them to the appropriate SOAP requests on the SharePoint side and vice versa.

The SharePoint connector offers the following functionality:

  • Add a group to a SharePoint site.

  • Modify group information including members and roles.

  • Delete a group from a SharePoint site.

  • Perform searches on SharePoint sites to retrieve group information including members and roles.

Overview

The SharePoint connector implements the API methods "add(…)", "modify(…)", "delete(…)" and "search(…)". They represent the corresponding SPML requests"‘AddRequest", "ModifyRequest", "DeleteRequest" and "SearchRequest".

The connector uses the standard SharePoint Web Service methods for UserGroup handling (http://yourserver/_vti_bin/UserGroup.asmx).These Windows SharePoint Web Services (WSS 3.0) have not changed since SharePoint Server 2010. Although they are no longer maintained, they are still supported.

The SOAP requests and responses are handled via the Axis framework 1.4.

A connection is always made to one specific site on the SharePoint server.

Limitations

This section describes SharePoint connector limitations and restrictions.

Groups

You cannot change the description or the default user login name in a modify request.

Please note that at this time all operations are group based.

Users

You cannot create, modify or delete users in SharePoint. You can only assign users that already exist in the active directory or the SharePoint site to a group or remove them from a group.

Roles

You cannot create, modify or delete roles in SharePoint. You can only assign roles that already exist in the SharePoint site to a group or remove them from a group.

Permissions

You cannot assign permissions for SharePoint Webs or Lists.

Request and Response Handling

This section describes the supported requests and attributes for the SharePoint connector.

AddRequest

The add request creates a new group in the SharePoint site. The following attributes are supported:

  • objectClass (mandatory)
    Must be "Group".

  • groupName (mandatory)
    Name for the new group.

  • ownerType
    The type of the group owner (either "User" or "Group").
    If no ownerType is passed in the request the value is set to "User" and the bind account is used as owner for the new group.

  • ownerIdentifier
    The name of the group owner (either a valid username in the active directory or another group in the same SharePoint site).
    If no ownerIdentifier is passed in the request the value is set to the username of the bind account.

  • defaultUserLoginName
    A valid username in the active directory.
    If no defaultUserLoginName is passed in the request the value is set to the username of the bind account.

  • description
    A short description for the new group.

  • member
    A list of valid usernames in the active directory.

  • role
    A list of valid roles in the SharePoint site.

Example Request:

<?xml version="1.0" encoding="UTF-8" ?>
<batchRequest xmlns="urn:oasis:names:tc:SPML:1:0"
xmlns:spml="urn:oasis:names:tc:SPML:1:0"
xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
  requestID="batch-1"
processing="urn:oasis:names:tc:SPML:1:0#sequential"
  execution="urn:oasis:names:tc:SPML:1:0#synchronous"
onError="urn:oasis:names:tc:SPML:1:0#exit">
  <spml:addRequest requestID="add-1">
<spml:identifier type="urn:oasis:names:tc:SPML:1:0#GenericString">
<spml:id>NewGroupName</spml:id>
</spml:identifier>
<spml:attributes>
<spml:attr name="objectclass" xmlns="urn:oasis:names:tc:DSML:2:0:core">
                    <dsml:value>Group</dsml:value>
</spml:attr>
<spml:attr name="groupName" xmlns="urn:oasis:names:tc:DSML:2:0:core">
 <dsml:value>NewGroupName</dsml:value>
</spml:attr>
<spml:attr name="ownerType" xmlns="urn:oasis:names:tc:DSML:2:0:core">
 <dsml:value>User</dsml:value>
</spml:attr>
<spml:attr name="ownerIdentifier" xmlns="urn:oasis:names:tc:DSML:2:0:core">
 <dsml:value>MOSS2007\ossadm</dsml:value>
</spml:attr>
<spml:attr name="defaultUserLoginName" xmlns="urn:oasis:names:tc:DSML:2:0:core">
 <dsml:value>MOSS2007\ossadm</dsml:value>
</spml:attr>
<spml:attr name="description" xmlns="urn:oasis:names:tc:DSML:2:0:core">
 <dsml:value>Description for the new group</dsml:value>
</spml:attr>
<spml:attr name="member" xmlns="urn:oasis:names:tc:DSML:2:0:core">
 <dsml:value>moss2007\username1</dsml:value>
 <dsml:value>moss2007\username2</dsml:value>
</spml:attr>
<spml:attr name="role" xmlns="urn:oasis:names:tc:DSML:2:0:core">
 <dsml:value>Full Control</dsml:value>
</spml:attr>
</spml:attributes>
</spml:addRequest>
</batchRequest>

ModifyRequest

The modify request can be used to change group information, to add and remove group members and to add and remove roles.

Important: The identifier for each modification request must be set to the group name. If the request modifies the group name then this is the old group name.

The following attributes are supported:

  • groupName (add/replace)
    A new name for the group.

  • ownerType (add/replace)
    The type of the new group owner (either "User" or "Group").

  • ownerIdentifier (add/replace)
    The name of the group owner (either a valid username in the active directory or another group in the same SharePoint site).

  • member (add/remove)
    A list of valid usernames in the active directory.
    No error is raised if an add modification is performed for a username that is already a member of the group.
    No error is raised if a delete modification is performed for a username that is not a member of the group.

  • role (add/remove)
    A list of valid roles in the SharePoint site.
    No error is raised if an add modification is performed for a role that is already assigned to the group.
    No error is raised if a delete modification is performed for a role that is not assigned to the group.

  • The properties "defaultUserLoginName" and "description" cannot be modified and are therefore ignored.

Example Request:

<?xml version="1.0" encoding="UTF-8" ?>
<batchRequest xmlns="urn:oasis:names:tc:SPML:1:0"
xmlns:spml="urn:oasis:names:tc:SPML:1:0"
xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
 requestID="batch-1"
processing="urn:oasis:names:tc:SPML:1:0#sequential"
 execution="urn:oasis:names:tc:SPML:1:0#synchronous"
onError="urn:oasis:names:tc:SPML:1:0#exit">
  <spml:modifyRequest requestID="mod-1">
 <spml:identifier
     type = "urn:oasis:names:tc:SPML:1:0#GenericString">
     <spml:id>GroupName</spml:id>
 </spml:identifier>
 <spml:modifications>
     <spml:modification name="groupName" operation="replace">
         <dsml:value>NewGroupName</dsml:value>
     </spml:modification>
     <spml:modification name="ownerIdentifier" operation="replace">
         <dsml:value>Human Resources Owners</dsml:value>
     </spml:modification>
     <spml:modification name="ownerType" operation="replace">
         <dsml:value>Group</dsml:value>
     </spml:modification>
 <spml:modifications>
     <spml:modification name="member" operation="add">
         <dsml:value>moss2007\username3</dsml:value>
         <dsml:value>moss2007\username4</dsml:value>
     </spml:modification>
     <spml:modification name="role" operation="add">
         <dsml:value>Design</dsml:value>
         <dsml:value>Contribute</dsml:value>
     </spml:modification>
 </spml:modifications>
 </spml:modifications>
</spml:modifyRequest>
</batchRequest>

DeleteRequest

The delete request is used to delete a group from a SharePoint site.

Important: The identifier for each delete request must be set to the group name.

The delete request does not require additional attributes.

Example Request:

<?xml version="1.0" encoding="UTF-8" ?>
<batchRequest xmlns="urn:oasis:names:tc:SPML:1:0"
xmlns:spml="urn:oasis:names:tc:SPML:1:0"
xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
     requestID="batch-1"
processing="urn:oasis:names:tc:SPML:1:0#sequential"
     execution="urn:oasis:names:tc:SPML:1:0#synchronous"
onError="urn:oasis:names:tc:SPML:1:0#exit">
  <spml:deleteRequest requestID="del-1">
<spml:identifier
  type="urn:oasis:names:tc:SPML:1:0#GenericString">
  <spml:id>GroupName</spml:id>
</spml:identifier>
 <spml:attributes>
  <spml:attr name="objectclass" xmlns="urn:oasis:names:tc:DSML:2:0:core">
               <dsml:value>Group</dsml:value>
  </spml:attr>
 </spml:attributes>
</spml:deleteRequest>
</batchRequest>

SearchRequest

The search request is used to retrieve group data such as owner information, members and roles. The search can either be restricted to one specific group or return all groups in the current site.

There are two ways to filter on one specific group:

  • Define a filter with an equality match on the attribute "groupName".

  • Limit the search scope to "base" and set the request identifier to the group name.

If the search is limited to one group name and the group cannot be found in the current site, then the search return the error code NO_SUCH_OBJECT.

Supported attributes for the search result include:

  • objectClass
    Always returns "Group".

  • groupName

  • ownerType
    The type of the group owner (either "User" or "Group").

  • ownerIdentifier
    The name of the group owner (either an active directory user or a group in the same site).

  • description

  • member
    The user names of all group members.

  • role
    A list of all role names assigned to the group.

  • site
    Returns the name of the current site.

Example Request:

<?xml version="1.0" encoding="utf-8"?>
<spml:searchRequest requestID="search-01"
xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core" xmlns:spml="urn:oasis:names:tc:SPML:1:0">
<spml:filter>
 <dsml:and>
   <dsml:equalityMatch name="groupName">
     <dsml:value type="string">SearchGroupName</dsml:value>
   </dsml:equalityMatch>
   <dsml:equalityMatch name="objectclass">
     <dsml:value type="string">Group</dsml:value>
   </dsml:equalityMatch>
 </dsml:and>
</spml:filter>
<spml:attributes>
 <dsml:attribute name="groupName"/>
 <dsml:attribute name="ownerIdentifier"/>
 <dsml:attribute name="ownerType"/>
 <dsml:attribute name="description"/>
 <dsml:attribute name="member"/>
 <dsml:attribute name="role"/>
 <dsml:attribute name="objectclass"/>
 <dsml:attribute name="site"/>
</spml:attributes>
</spml:searchRequest>

Configuration

Here is a sample configuration snippet for the SharePoint connector:

<connector
role="connector"
className=" siemens.dxm.connector.sharepoint.SharePointConnector"
name="ts" version="1.00">
<connection type="Sharepoint"
  server="sharepoint-2016-01"
  port="80"
  user="domain-01\admin"
  password="!xxxYYY123"
  ssl="false"
  <property name="endpoint" value="http://sharepoint-2016-01/sites/DXI_TestSiteCollection/SiteA"/>
  <property name="searchGroupsFromSiteCollection" value="false"/>
  <property name="debugfile" value="dbgOut.xml"/>
</connection>
</connector>

Supported Connection Parameters

The SharePoint connector supports the following standard properties of the XML configuration file’s <connection> element:

server - (mandatory); the SharePoint server name.

port - (mandatory); the SharePoint server port number listening for HTTP requests.

user - (mandatory); the bind user in <domain>\<name> syntax with admin rights in SharePoint.

password - (mandatory); user password.

ssl - (optional); flag whether to connect over SSL to the SharePoint server or not. Default is false.

Supported non-standard properties include:

endpoint - (mandatory); the base site from where the group search starts.

searchGroupsFromSiteCollection - (optional); if set to true, all groups from the complete Site collection – also those from sites parallel to the specified base site- are searched for. If set to false (the default), only the groups from the specified (sub)site are searched for.

debugFile - (optional); if specified, all SPML requests and responses are written to the configured file.