13.4 Principals
| As we've seen in ACLs and owner property values, each principal is uniquely identified by a principal URL. That URL is not just an opaque string, because it must be the address of a WebDAV resource that represents that user. The WebDAV resource representing a user or a group is called a principal resource. The principal resource for a user can be used to find more information about the user, particularly the user's displayname. Although the principal URL will not often be displayed to users, it is the official identity of the principal and must be used whenever a principal must be uniquely identified. 13.4.1 Finding Principal InformationOnce we have a principal URL for Alice, what can we do with it? In the WebDAV Access Control specification, a principal is a very simple WebDAV resource. Thus, we can ask that resource for its properties. Listing 13-6 shows a request for all of the properties that are defined by ACL on a principal resource. The response has values for all these properties, naturally. Listing 13-6 PROPFIND request and response with principal properties.Request: PROPFIND /principals/ids/alice HTTP/1.1 Host: www.example.com Content-Type: text/xml Content-Length: 200 Depth: 0 <?xml version="1.0" encoding="utf-8" ?> <D:propfind xmlns:D="DAV:"> <D:prop> <D:resourcetype/><D:displayname/><D:principal-URL/> <D:alternate-URI-set/><D:group-membership/> </D:prop> </D:propfind> Response: HTTP/1.0 207 Multi-Status Content-Type: text/xml; charset=UTF-8 Content-Length: 654 Date: Mon, 27 May 2002 17:23:25 GMT Server: Tomcat Web Server/3.3.1 Final (JSP 1.1; Servlet 2.2) <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://localhost/xythoswfs/principals/ids/alice </D:href> <D:propstat> <D:prop> <D:resourcetype><D:principal/></D:resourcetype> <D:displayname>Alice Wetherill</D:displayname> <D:principal-URL><D:href> http://www.example.com/principals/ids/alice </D:href></D:principal-URL> <D:alternate-URI-set> <D:href>ldap://ldap.example.com/ cn=Alice%20Wetherill, The principal resource has a resourcetype of <D:principal/>. This principal resource has a displayname property value of Alice Wetherill and is a member of the group hr-group. The official principal URL is shown in the principal-URL property; it's the same URL used to query the principal properties. Principal resources can appear elsewhere (e.g., inside a group collection), in which case the principal URL becomes useful to point to the official URL for querying principal properties. The alternate-URI-set property is used to show if there is more information about the principal that can be looked up elsewhere. This could be an address to a Lightweight Directory Access Protocol (LDAP) [RFC2251] directory entry. If the company in our example had a SunONE directory server [LDAP03] (previously the Netscape directory server [LDAP02]), the URL to the directory entry corresponding to Alice might look something like it does in Listing 13-6. 13.4.2 Finding Group MembershipGroup principal resources have some of the same properties as user principal resources: displayname, resourcetype, and alternate-URI-set. In addition, groups have a group-member-set property to list the principals within a group. This property has the same format as the group-membership property: It contains any number of href elements, and each href element contains the URI of a principal. A PROPFIND to a group resource principal, asking for the group-member-set property, would return a value as shown in Listing 13-7. Listing 13-7 PROPFIND request and response with principal properties.<D:group-member-set> <D:href>http://www.example.com/principals/ids/alice</ D:href> <D:href>http://www.example.com/principals/ids/bob</D:href> <D:href>http://www.example.com/principals/ids/carl</D:href> </D:group-member-set> 13.4.3 Shortcut for Displaying Principals from ACLsThe principal URL is great for uniquely identifying principals, but it isn't very friendly for displaying to users. Section 13.4.1 showed how to query a principal resource to find out the properties of a principal, like the display name. That's great for one principal, like the principal found in the owner property. However, it will be very common for a client to want properties (like displayname) for all the principals listed in an acl property, and it's not very efficient to have to issue one PROPFIND for each principal. To make this more efficient, there is a special report, acl-principal-prop-set, to query the server for information on all the principals named in an acl property. The REPORT method for retrieving reports is defined in DeltaV (introduced in this book in Section 11.10.1), and the ACL specification defines four new reports that servers must support. The acl-principal-prop-set report allows the client to quickly retrieve properties for all the principals referred to in an ACL. The REPORT method is defined so that the REPORT request is addressed to a particular resource supporting that type of report. In this case, any resource that has an ACL should support this report. In the body of the REPORT request, the client may specify what properties to return. The response is a multi-status, in exactly the same format as a PROPFIND response with one response element for each principal resource. Listing 13-8 shows only the request, in which the client asks for the displayname property for every principal listed in the ACL. Listing 13-8 REPORT request for acl-principal-prop-set report.REPORT /index.html HTTP/1.1 Host: www.webdav.org Content-Type: text/xml; charset="utf-8" Content-Length: xxxx 13.4.4 Who Am I?The principal-match report (which also uses the DeltaV REPORT method) is a multipurpose report. First, it allows the client to find what principal matched the user's authentication credentials. It also allows the client to make many more general queries based on the current user's principal URL. Basically, the report looks for resources in a certain scope, where a specified property contains the current user's principal URL. The REPORT request identifies the scope by addressing a collection and specifies the name of property to examine. Depending on what collection is addressed and what property is examined, this report can be used for a couple of things:
The principal-match report must be requested for a collection, but it can be any kind of collection (collection of principals, groups, or regular resources). The chosen property is specified in a simple XML body. Before the client can query a principal collection to find out "who am I," the client must find out the name of a principal collection. This is done by querying a regular resource, using PROPFIND, to find out the value of the principal-collection-set property. Let's assume that this property value returns only one principal collection URL: http://www.example.com/principals/, so only one REPORT request is needed to find out who is the current user. Note that reports are always requested with a Depth: 0 header or no depth header, even if child collections are searched as part of the report processing (see Listing 13-9). Listing 13-9 Principal-match report used to find out "who am I?"REPORT /principals/ HTTP/1.1 Host: www.example.com Authorization: Digest username="alice", realm="example.com", nonce="...", uri="/hr/", response="...", opaque="..." Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Depth: 0 Listing 13-9 shows how the question "who am I?" is answered. A PROPFIND request to the principal resource would be required to find out more information, such as the user's full name. In the body of the REPORT request, the principal-match root element must contain a principal-property element. The principal-property element must contain the name of a property that is known to contain principal URLs. Since the principal-match report can match any property known to contain principal URLs, the report could be used for any number of purposes. However, only two such purposes are mentioned in the ACL specification. The first is to find out the current user, and the second is to find out what resources the current user owns. The specification doesn't say which properties the server must support with this report, so the client can only try naming the property and see if the report works. A server could neglect to implement the report for the group-member-set property, for example. The request to find out what resources Alice owns is very similar. The client addresses a regular collection (not a principal collection) and asks the server to match the owner property (see Listing 13-10). Listing 13-10 Request for principal-match report to find out resources owned by current user.REPORT /hr/ HTTP/1.1 Host: www.example.com Authorization: Digest username="alice", realm="example.com", nonce="...", uri="/hr/", response="...", opaque="..." Content-Type: text/xml; charset="utf-8" Content-Length: xxxx The successful response to this request is a 207 Multi-Status response, where there is a response element and URL for each resource under /hr/ that Alice owns. 13.4.5 Browsing PrincipalsWe've shown how to alter ACLs on resources but not how to figure out what principals can be granted privileges or how to identify them. WebDAV ACLs defines two basic ways to do this: browsing and searching. The client can browse collections of principals the same way regular collections are browsed; the client can issue PROPFIND requests to navigate starting from the root principal collection. The structure of the principal collection is up to the server implementation. It's likely that many implementations will put users into one collection and groups into another collection (both within the principals root collection) but the names for these collections are left up to the server. A server implementation could also divide the user collection into subcategories. For example, a university may choose to put professors, staff, and students each in separate principal collections for ease of administration. 13.4.6 Searching PrincipalsWhen many principals exist (some companies have hundreds of thousands of employees and a similar number of groups in the company directory), browsing becomes less feasible, even after users are divided into subcollections. Although the server must still allow browsing, it may allow searching for principals as well. In WebDAV ACLs, the client requests searches with the principal-property-search report, after getting the principal-search-property-set report to figure out what kinds of searches are allowed. If a complete standard existed for searching WebDAV resources based on property values, this report would not be needed. A proposal is in the works, but it was still some way from standardization when WebDAV ACLs were submitted for RFC status. First, the client uses the principal-search-property-set report to find out what properties may be searched. The server's response might look like Listing 13-11. Listing 13-11 Body of response to principal-search-property-set report.<?xml version="1.0" encoding="utf-8" ?> <principal-search-property-set xmlns="DAV:"> <principal-search-property> <prop><displayname/></prop> <description xml:lang="en">Full name</description> </principal-search-property> <principal-search-property> <prop xmlns:a="http://www.example.com/"><a:title/></ prop> <description xml:lang="en">Job title</description> </principal-search-property> </principal-search-property-set> In Listing 13-11, the server advertises search support only for principals' full names and job titles. Note that it's not clear whether the server could support different properties for different kinds of principals. For example, the job title property described here might be supported for searching on users, but it surely wouldn't return results on groups. Now that the client knows what properties it can search on, it can submit the search request (see Listing 13-12). Listing 13-12 Search for principals by matching substrings.REPORT /principals/ HTTP/1.1 Host: www.example.com Content-Type: text/xml; charset=utf-8 Content-Length: xxxx Note that the displayname property is named twice in Listing 13-12. The first time, it specifies what property to search on: The displayname property will be searched for the substring alice. The second time, it specifies what property to return. The client wants the full displayname value for every principal matching the caseless substring search. We know from previous examples that Alice Wetherill will be one of the values, but any other Alice will also be returned, along with principals whose name contains "alice" in the middle (like "Eduardo Valicenna"). Group display names may also match this search expression. For example, if Alice has a group called "Alice's direct reports," that group would be returned in the same principal search. The server's response is the multi-status PROPFIND response, with one response element per principal resource, so we won't show it here. |
<?xml version="1.0" encoding="utf-8" ?> <D:acl-principal-prop-set xmlns:D="DAV:"> <D:prop><D:displayname/></D:prop> </D:acl-principal-prop-set> 
EAN: N/A
Pages: 146