From OpenLiberty.org Wiki

Contents 1 Overview 2 Actions 2.1 Entities 2.1.1 Adding Entities 2.1.2 Adding Known Entities 2.1.3 Removing Entities 2.1.4 Membership 2.2 Collections (Groups) 2.2.1 Creating Collections 2.2.2 Removing Collections 2.2.3 Adding To a Collection 2.2.4 Removing From a Collection 2.2.5 Listing the Members of a Collection 2.3 Objects 2.3.1 Get Object Info 2.3.2 Set Object Info 2.3.3 Query Object 2.3.4 Resolve Identifier 3 Questions

Overview

The ID-WSF People Service ("PS") provides a principal with the ability to manage online relationships with other entities which have relevance in the ID-WSF identity circle. These entities may be people, devices, or any entity with an identity. A PS enables a principal to manage groupings of entities, create groups, add and remove entities from these groups, and update information on a group or member entity level.

The ClientLib will model interaction with any ID-WSF 2.0 PS. A WSC using the ClientLib with the proper identity and security will have access.

At the moment HP, NTT, and Symlabs have developed and tested LIOP their PS services. Lasso (Entr'ouvert) is planning to support PS by July 2007.

• Subscription Support (?) - The ability to include Subscription info in a query to indicate that the WSC would like to be notified when the subscription is acknowledged.
• Notification Support (?) - The ability to process Notifications which may contain identity tokens of invited users.

Actions

The ClientLib will facilitate the following transactions. It should be noted that the PS specification has separate calls for creating entity and collection objects, and adding entities and collections to existing collections. It is likely that the ClientLib has a unified approach to managing this. For example, it seems that you should be able to use a call like:

Given:

class WSFClientFactory;
class PSClient;
abstract class PSObject;
class PSEntity extends PSObject;
class PSCollection extends extends PSObject;

This same code could be used to add a single entity, collection, or a tree containing many of entities and collections.

WSFClientFactory factory = WSFClientFactory.newInstance();
PSClient client = factory.newPSClient(epr); 
client.addObjectsToPS(PSCollection parentCollection, <PSObject>List objectsToAdd);

Entities

(urn:liberty:ps:entity)

Adding Entities

(urn:liberty:ps:2006-08:AddEntity*) - The ClientLib will provide a mechanism for adding entities to the PS. The PS may optionally return an URL and saml artifact that are used by the "invited" entity when responding to the "invitation"

• DisplayName will be required
• Subscription will be supported, with TokenPolicy for requirements of the new identity's subscription

PSEntity entity = new PSEntity("Asa Hardcastle");
client.addEntity(entity, optionalSubscription);

Adding Known Entities

(urn:liberty:ps:2006-08:AddKnownEntity*) - The WSC sends an identity token to the PS to attempt the addition of a known entity.

• DisplayName and Subscription as in Adding Entities
• CreatePSObject - will be enabled, indicating that the WSC wants an object created representing the inviting user at the invited user's PS.

PSEntity entity = new PSEntity( anIdentityToken );
client.addKnownEntity(entity, false, optionalSubscription);

Removing Entities

(urn:liberty:ps:2006-08:RemoveEntity*) - Enable the WSC to simply specify the entity id(s) in a request to the PS to delete the entity(ies).

client.removeEntities(<PSEntityRefs>List entitieRefs);

Membership

(urn:liberty:ps:2006-08:TestMembership*) The PS Client will provide a method for discovering whether an Entity is a member of a Collection. This requires a Token.

boolean isMember = client.isEntityAMemberOf(PSEntityRef entityRef, SecurityToken entityToken, PSCollection collection, optionalSubscription) 

Collections (Groups)

(urn:liberty:ps:collection)

Collections(groups) contain entities (members) and other collections.

Creating Collections

(urn:liberty:ps:2006-08:AddCollection*) - Like Entity, DisplayName is required

• Subscription to notify the WSC when the collection changes

PSCollection collection = new PSCollection("Family");
client.addCollection(collection, optionalSubscription);

Removing Collections

(urn:liberty:ps:2006-08:RemoveCollection*) - By specifying the target collection id(s), the WSC can request the removal of 1...n collections. A WSP will not allow for the removal of a collection if it contains children who are not explicitly specified in the call.

client.removeCollections(<PSCollectionRefs>List collectionRefs);

Adding To a Collection

(urn:liberty:ps:2006-08:AddToCollection*) The PS Client will provide a facility for adding 1...n existing members (of heterogeneous type, entity and/or collection) to an existing collection.

client.addObjectsToCollection(<PSObject>List objects, collection, optionalSubscription);

Removing From a Collection

(urn:liberty:ps:2006-08:RemoveFromCollection*) The PS Client will provide a facility for removing 1...n existing members (of heterogeneous type, entity and/or collection) from an existing collection.

client.removeObjectsFromCollection(<PSObjectReference>List objectRefs, collection, optionalSubscription);

Listing the Members of a Collection

(urn:liberty:ps:2006-08:ListMembers) The PS Client will provide a facility for a ClientLIb user to list the members of a collection. If no collection is indicated, then the root collection is assumed.

client.listCollectionMembers(aCollection, structure, count, offset, optionalSubscription);

• structure can be "children" "tree" or "entities"
  • children indicates only the direct child entities and collections
  • tree indicates return the full tree structure
  • entities indicates a flat view of the full tree, with no collections
• count and offset are used to paginate the response tree/list

Objects

Get Object Info

(urn:liberty:ps:2006-08:GetObjectInfo*) The PS Client will provide a method for retrieving the object info for a specific object.

PSObject object = client.getObjectInfo(PSObjectReference objectRef, optionalSubscription);

Set Object Info

(urn:liberty:ps:2006-08:SetObjectInfo*) The PS Client will provide a method for updating the object info for a list of existing objects (1...n)

 client.setObjectInfo(<PSObject>List objects, optionalSubscription);

• can't modify objects with children - so forget about renaming a collection with members buddy ;)

Query Object

(urn:liberty:ps:2006-08:QueryObjects*) The PS Client will provide a mechanism for creating an xpath base query to the PS, which will return 0...n Objects in a flat list (no tree).

• The query is constructed using XPath syntax, always beginning with //Object

XPathFactory factory = XPathFactory.newInstance();
XPath xpath = factory.newXPath();
PathExpression pathExpression = xpath.compile("//Object[@NodeType=’urn: liberty:ps:entity’]");
<PSObjectRef>List objectRefs = client.findObjects(pathExpression, count, offset, optionalSubscription)

Resolve Identifier

(urn:liberty:ps:2006-08:ResolveIdentifier*) The PS Client will provide a simple mechanism for retrieving stored identity tokens from an object identifier list 1...n. Each object identifier may specify the requirements of the identity token through the use of sec:TokenPolicy.

client.resolveIdentifiers(<PSEntityResolutionRequest>List );

Questions

• A WSC can contact a PS to get the security tokens necessary to access a service that a principal has set aside for an entity by presenting the identity tokens of that entity and a reference to the principal identity -- or does a DS use the PS in this way?

• Is a valid SS needed to enable this? Is the WSC expected to have the ability to handle notifications?
• Adding known entities can take place with arbitrary identity tokens, like an email address?? How does a WSC know that a PS will have the ability to interpret this?

• Is TestMembership only for testing the membership of an entity?
  • If you have a collection called Favorites with a subcollection of Mammals, could you also add the Mammals collection to another collection called Animals?