Citrix Share File Connector
The Citrix ShareFile connector implements the Identity Java Connector Integration Framework’s DxmConnector interface and connects to a Citrix ShareFile through the HTTP interface. It can be used for real-time workflows in the Java-based (IdS-J) Server. Like all framework-based agents, it gets SPML requests from the Identity side and converts them to the appropriate Citrix ShareFile calls and vice versa. The Citrix ShareFile connectivity is based on HTTP protocol. The connector supports membership stored on groups.
Overview
The connector implements the API methods "add(…)", "modify(…)", "delete(…)" and "search(…)". They represent the corresponding SPML requests "AddRequest", "ModifyRequest", "DeleteRequest" and "SearchRequest".
add(…) - internally uses addUser(…) and addGroup(…)
modify(…) - internally uses modifyUser(…) and modifyGroup(…)
search(…) - internally uses searchUser(…), searchAllUsers(…), searchGroup(…), searchAllGroups(…)
The connector uses the open() method to open a connection to the Citrix ShareFile service. Because communication with the Citrix ShareFile service is through the HTTP protocol (stateless calls), no activities are performed on the close() method.
Limitations
By default, the isemployee attribute is set to true in the workflow mapping, so the default workflow only creates employees. To change it, create a custom Java mapping for the isemployee attribute.
Depending on the type of Citrix subscription, limitations related to the maximum number of employees that can be managed by DirX Identity are possible.
DirX Identity Manager Limitations
It is not possible to change a group’s name using the GUI in the DirX Identity Manager.
Known Issues
Due to a constraint in the DirX Identity workflow engine, the user’s e-mail address is used instead of the Citrix ID to identify the user inside an SPML modify or add request when handling membership for a user without an existing account in Citrix. For example:
<modifications> <modification name="member" operation="add"> <value type="string">john.doe@dirx.de</value> </modification> </modifications>
If there is already a Citrix account for the user, the Citrix ID is used to identify the user inside an SPML modify or add request. For example:
<modifications> <modification name="member" operation="add"> <value type="string">7b1fc236-8d5b-44dc-92bc-44b5757c3c4e</value> </modification> </modifications>
The Citrix ShareFile API does not allow creating a user with the same e-mail address as an existing user. Such an attempt fails. The Citrix ShareFile connector returns the ID of the existing user with the specified e-mail address in the error SPML response.
On the other hand, the Citrix ShareFile API allows creating a group with the same name as an existing group. This action is handled by the Citrix ShareFile connector itself. It does not forward this type of request to the Citrix API, but returns an error.
Request and Response Handling
This section describes the supported requests and attributes for the Citrix ShareFile connector. All attributes allowed by the Citrix ShareFile API can be added.
The connector supports the following attributes of users and groups:
Users:
-
email
-
firstname
-
lastname
-
company
-
isemployee (true or false)
-
state (ENABLED or DISABLED)
Groups:
-
name
-
isShared (true or false)
Membership:
-
member - the membership attribute
The connector supports following operational attributes:
-
objtype - mandatory, the value can be user or group. It specifies for all request types (add, modify, delete, search) whether it is a user or group request.
If a user who belongs to two groups should be deleted from one of them, a modify request is performed for the membership change. If a user belongs to only one group and should be deleted from it, a modify request for deleting the user from the group and a modify request for suspending the user is performed.
Add Request
In the add request for user or group, the identifier must not be specified. Citrix generates the identifier automatically and returns it in the response.
Groups
For groups, the name attribute is mandatory and represents the name of the group to be created. The following example request creates the group TestGroup.
<?xml version="1.0" encoding="UTF-8"?>
<addRequest requestID="req-id">
<operationalAttributes>
<attr name="objType">
<value type="string">group</value>
</attr>
</operationalAttributes>
<attributes>
<attr name="name">
<value type="string">TestGroup</value>
</attr>
</attributes>
</addRequest>
Users
The attributes firstname, lastname, email and isemployee are mandatory. The state attribute is optional. If not present, the Citrix connector creates the user in the ENABLED state.
The following example request creates a user object for John Doe. His e-mail address is also specified for the id attribute:
<?xml version="1.0" encoding="UTF-8"?>
<addRequest requestID="req-id">
<operationalAttributes>
<attr name="objType">
<value type="string">user</value>
</attr>
</operationalAttributes>
<attributes>
<attr name="lastname">
<value type="string">Doe</value>
</attr>
<attr name="firstname">
<value type="string">John</value>
</attr>
<attr name="email">
<value type="string">john.doe@dirx.com</value>
</attr>
<attr name="isemployee">
<value type="string">true</value>
</attr>
<attr name="state">
<value type="string">ENABLED</value>
</attr>
</attributes>
</addRequest>
Modify Request
A modify request allows for changing attributes of a user or a group. At the group level, it allows for changing the membership.
The attributes firstname, lastname, email, company and state can be changed for users. The attributes name and isshared can be changed for groups.
When changing an attribute, a mandatory parameter in the SPML request is the Citrix ID of the user / group returned by the SPML add response.
In the following example request, the e-mail address of the user John Doe is changed:
<modifyRequest requestID="req-id">
<operationalAttributes>
<attr name="objType">
<value type="string">user</value>
</attr>
</operationalAttributes>
<identifier type="urn:oasis:names:tc:SPML:1:0#GUID">
<id>g9163393-df09-42d9-b19d-d62e9468a83e</id>
</identifier>
<modifications>
<modification name="id" operation="replace">
<value type="string">52cc6788-efd0-4647-a269-6784a92a425e</value>
</modification>
<modification name="email" operation="replace">
<value type="string">john.doe@dirx.de</value>
</modification>
<modification name="isemployee" operation="replace">
<value type="string">true</value>
</modification>
</modifications>
</modifyRequest>
The following example request changes the name of the group TestGroup to TestGroup.changed:
<modifyRequest requestID="modify-01">
<operationalAttributes>
<attr name="objType">
<value type="string">group</ value>
</attr>
</operationalAttributes>
<identifier type="urn:oasis:names:tc:SPML:1:0#GUID">
<id>g9163393-df09-42d9-b19d-d62e9468a83e</id>
</identifier>
<modifications>
<modification name="name" operation="replace">
<value>TestGroup.changed</value>
</modification>
</modifications>
</modifyRequest>
The following example request performs a membership change. It adds a user who does not have a Citrix account to a group. The user’s e-mail address is specified in the modification tag under modifications → add. These fields are both mandatory:
<modifyRequest requestID="req-id">
<operationalAttributes>
<attr name="objType">
<value type="string">group</value>
</attr>
</operationalAttributes>
<identifier type="urn:oasis:names:tc:SPML:1:0#GUID">
<id>g9163393-df09-42d9-b19d-d62e9468a83e</id>
</identifier>
<modifications>
<modification name="member" operation="add">
<value type="string">test.user@dirx.com</value>
</modification>
</modifications>
</modifyRequest>
The following example request performs a membership change. It adds a user who has a Citrix account to a group. The Citrix group ID is specified in the request identifier and the user ID is specified in the modification tag under modifications → add. These fields are both mandatory:
<modifyRequest requestID="req-id">
<operationalAttributes>
<attr name="objType">
<value type="string">group</value>
</attr>
</operationalAttributes>
<identifier type="urn:oasis:names:tc:SPML:1:0#GUID">
<id>g9163393-df09-42d9-b19d-d62e9468a83e</id>
</identifier>
<modifications>
<modification name="member" operation="add">
<value type="string">2fc7f4e9-2d5a-41c4-bde0-818f9373944b</value>
</modification>
</modifications>
</modifyRequest>
Delete Request
In a delete request, the identifier is mandatory and represents the ID received from Citrix when creating the user or the group.
The following example request deletes a user:
<deleteRequest requestID="delete-01">
<operationalAttributes>
<attr name="objType">
<value type="string">user</value>
</attr>
</operationalAttributes>
<identifier type="urn:oasis:names:tc:SPML:1:0#DN">
<id>f58688fa-1e36-4514-b506-e0fd0dc07541</id>
</identifier>
</deleteRequest>
The following example request deletes a group:
<deleteRequest requestID="delete-01">
<operationalAttributes>
<attr name="objType">
<value type="string">group</value>
</attr>
</operationalAttributes>
<identifier type="urn:oasis:names:tc:SPML:1:0#DN">
<id>g1af88a7-4311-418c-a969-e0759e535f2e</id>
</identifier>
</deleteRequest>
Search Request
In the search request, the Citrix ShareFile connector supports the standard element searchBase and the operational attribute scope.
The following table shows valid searchBase / scope combinations in a search request:
| searchBase / scope | BASE | ONELEVEL | SUBTREE |
|---|---|---|---|
object ID |
OK |
INVALID |
INVALID |
"all" |
INVALID |
INVALID |
OK |
In a search request, searchBase is a mandatory parameter that specifies the Citrix ID for the user or the group or the "all" string to list all users / groups. The attributes contained under the attributes tag are returned with their values in the response if available.
Example request for group:
<searchRequest requestID="req-id">
<operationalAttributes>
<attr name="objType">
<value type="string">group</value>
</attr>
<attr name="scope">
<value type="string">Base</value>
</attr>
</operationalAttributes>
<searchBase type="urn:oasis:names:tc:SPML:1:0#DN">
<id>g80ab8d5-da94-4360-b159-952f2561e5ee</id>
</searchBase>
<attributes>
<attribute name="name"/>
<attribute name="member"/>
</attributes>
</searchRequest>
Example request for user:
<searchRequest requestID="req-id">
<operationalAttributes>
<attr name="objType">
<value type="string">user</value>
</attr>
<attr name="scope">
<value type="string">Base</value>
</attr>
</operationalAttributes>
<searchBase type="urn:oasis:names:tc:SPML:1:0#DN">
<id>2fc7f4e9-2d5a-41c4-bde0-818f9373944b</id>
</searchBase>
<attributes>
<attribute name="lastname"/>
<attribute name="firstname"/>
<attribute name="email"/>
<attribute name="isemployee"/>
<attribute name="state"/>
</attributes>
</searchRequest>
Specify the value all in the searchBase if you search for all users or all groups.
The following sample request searches for all groups that contain a user with a specific Citrix ID. The Citrix ID of the user is specified in the filter tag and the value all is specified in the id of the searchBase tag:
<searchRequest requestID="req-id">
<operationalAttributes>
<attr name="objType">
<value type="string">group</value>
</attr>
<attr name="scope">
<value type="string">subtree</value>
</attr>
<attr name="noattrs">
<value type="string">true</value>
</attr>
</operationalAttributes>
<searchBase type="urn:oasis:names:tc:SPML:1:0#GenericString">
<id>all</id>
</searchBase>
<filter>
<equalityMatch name="member">
<value type="string">7b1fc236-8d5b-44dc-92bc-44b5757c3c4e</value>
</equalityMatch>
</filter>
</searchRequest>
Configuration
Here is a sample job configuration snippet for the Citrix ShareFile connector:
<connector role="connector" className="net.atos.dirx.dxi.connector.citrix.sharefile.ShareFileConnector" name="Citrix ShareFile Connector"> <connection type="CitrixShareFile" user="user@mycompany.com" password="dirx" server="mycompany.sharefile.com"> <property name="useSystemProxy" value="false"/> <property name="proxy" value="myproxy.domain.com:8080"/> </connection> </connector>
Supported Connection Parameters
The connector supports the following standard properties of the <connection> element of the XML configuration file:
server - name of the Citrix ShareFile server. It is used to build the Citrix ShareFile Access URL in form https://server/.
user - user e-mail address for authentication.
password - password for authentication to the Citrix ShareFile server.
It also supports the following properties:
useSystemProxy - (optional) boolean (default is false). If configured, the connector uses the operating system’s default proxy. This parameter is supported only on some Microsoft operating systems.
proxy - (optional) string. If configured, the connector uses an HTTP proxy for connections to Citrix ShareFile. The format is host:[port].