XRD Provisioning Protocol - Working Draft 01
Jared Hanson
The URL for this draft is:
http://xrdprovisioning.net/specs/1.0/wd01/xrd-provisioning-1.0-wd01.html
This draft is based on the session held at IIW 9, notes from which are
captured on the OASIS XRI Wiki at: http://wiki.oasis-open.org/xri/XrdOne/Provisioning
Special thanks to Will Norris for organizing that session, and to all
the people who attended. I'm hoping this draft formalizes the
protocol further, so we can continue discussions and begin
implementation. Feedback is greatly appreciated.
Thanks.
--
Jared Hanson <http://jaredhanson.net/>
Jared Hanson
link to a thread that has formed on the WebFinger group:
http://groups.google.com/group/webfinger/t/3845136b7ee0b720
Jared
Joseph Holsten
On Mar 15, 2010, at 1:36 PM, Jared Hanson wrote:
>> 1. Given that webfinger defines the access to a user's XRD as via a URI
>> template, why is the recommendation that XRDP have a unique URL for the
>> user's XRD? Could not the same 'lrdd' template be used?
>
> I'm not sure I understand your concern here. My assumption is that if
> you want to provision a user's XRD, you will have already applied the
> transform and fetched the XRD from the resulting URL (whatever it
> is). Within the XRD fetched, the XRDP Service Endpoint will be
> linked, and that is where you send provisioning requests. (That may
> be the same URL that the transform resulted in, per recommendation.)
It seems like George is wondering why have the XRDP endpoint is different from the XRD document itself. But since most XRDs will just be dumb resources, it makes sense to have an explicit link to XRDP to signal support. If the XRD URI is the same as the XRDP URI, great, but let's not require that. Since it may be that the URI is a an XRD but not an XRDP endpoint, it doesn't make sense to double up the semantics of the lrdd relation. It's fine as is.
> I suppose the XRDP rel could be listed in host-meta with a template,
> to advertise how any resource on the host can be provisioned. Off the
> top of my head, I'm not sure that is very useful.
That's nifty, I hadn't thought of putting the link in the host meta. That would be a nice way to create a new XRD entirely, but I imagine that should have a different rel, as one only makes sense for updating a single XRD while the other only seems useful for updating a collection of XRDs. But such a use case is awfully unlikely, so I'd agree that XRDP should just stay out of the host-meta entirely.
>> 2. In provisioning a link, should there be a way for the user to say
>> that the <link> is "private/protected"? For example, if I keep my family
>> photos separate from my public photos. And I want both <Link>'s
>> provisioned in my XRD. Is there a way to restrict the family link to
>> only those people who access the XRD in an authorized state? Or is this
>> use case too contrived to be worthwhile? Maybe a better example would be
>> <Link>'s representing my online health records?
>
> I think having "private" XRDs is an interesting use case, but I
> haven't seen any real consensus form around best practices in this
> area. The resolution specs (LRDD, host-meta) do unauthenticated HTTP
> GETs to retrieve the XRD, so any link within is public knowledge
> (though resolving the link may in fact require authentication). Is it
> worthwhile to return additional links if the HTTP GET for the XRD
> included credentials? Should "protected" XRDs be linked to from a
> "public" XRD? The later case would make it easier to deal with
> provisioning, as you simply wouldn't add protected links to the public
> XRD.
>
> Further discussion in this area would be helpful. Ideas? Anyone?
Great idea, but let's leave it for v2. Since OAuth and similar authn protocols don't have a standard way to express this, I'm not keen on imposing one yet. If the use case does seem useful, it makes more sense to do it in the authn layer. It's really dependent on a solid idea of permissions and groups that we don't need to invent right now.
I don't think it's a critical feature anyway as you can just manage the permissions on the linked resources instead. I don't imagine that you're going to have a link to your health records that is only protected by access permissions to your XRD, you'll need to require authorization to do anything with that resource anyway.
>> 3. There should probably be a security section that talks about if/when
>> to use SSL in provisioning. Since the PUT and DELETE commands pass all
>> the <Link> identifiers in the URL, that information is exposed. I
>> suppose the xml:id could be used in those circumstances.
>>
>
> Agreed. In the first draft I wanted to concentrate on the protocol
> operations. Not to ignore security, but I expect a lot of people to
> chime in on that subject who are more knowledgeable than I am.
I think it makes most sense to just have the put/delete operations use id regardless. The only benefit of including the data with the request is to ensure that the document hasn't been modified since last access. The standard HTTP way to do this is to mark the resource with an ETag, and when the client posts or deletes, they have an If-Match header with the entity-tag for the version they want to modify. If the tag doesn't match, the server should return a 412 Precondition Failed response. There's a similar procedure for Last-Modified and If-Unmodified-Since.
Am I missing some other reason to include the attributes in the request?
Also, section 5.2 Adding a Link doesn't mention where the new link should be added in the document. Similarly, section 5.3 Updating a Link doesn't say whether the updated link should be in the same position as the original link. Since XRDs are an ordered list of links and clients are encouraged to use the first link that matches, that might be an issue. I think it's okay to leave it up to implementations, but could we say that an XRDP service MAY insert new links at any position in the XRD, and that an XRDP service MAY place an updated link in a different order within the XRD?
When I get around to it, my implementation's just going to shove the new one in at the end, and will implement an update as a delete followed by an insert.
Finally, the spec doesn't really say what happens if the request doesn't have a valid link. I'm not even sure it explicitly says that the link must be a valid Link element according to the XRD schema. I think the right code for invalid data would be 406 Not Acceptable since the element isn't valid for the content type. Speaking of which, I think links should have a content-type of application/xrd+xml;type=link, following atompub's application/atom+xml;type=entry.
--
http://josephholsten.com
George Fletcher
> On Mar 15, 2010, at 1:36 PM, Jared Hanson wrote:
>
>
>>> 1. Given that webfinger defines the access to a user's XRD as via a URI
>>> template, why is the recommendation that XRDP have a unique URL for the
>>> user's XRD? Could not the same 'lrdd' template be used?
>>>
>> I'm not sure I understand your concern here. My assumption is that if
>> you want to provision a user's XRD, you will have already applied the
>> transform and fetched the XRD from the resulting URL (whatever it
>> is). Within the XRD fetched, the XRDP Service Endpoint will be
>> linked, and that is where you send provisioning requests. (That may
>> be the same URL that the transform resulted in, per recommendation.)
>>
> It seems like George is wondering why have the XRDP endpoint is different from the XRD document itself. But since most XRDs will just be dumb resources, it makes sense to have an explicit link to XRDP to signal support. If the XRD URI is the same as the XRDP URI, great, but let's not require that. Since it may be that the URI is a an XRD but not an XRDP endpoint, it doesn't make sense to double up the semantics of the lrdd relation. It's fine as is.
>
>
needed to be recommended. But I agree with the comments, that it's
possible to describe the end point in the way that makes the most sense
to the deployer.
To Joseph's point about XRD's being dumb resources, I'm not sure that's
actually easier to deploy (though more efficient). Regardless, since the
XRD defines the XRDP endpoint the point is mute. Sorry for any confusion.
>> I suppose the XRDP rel could be listed in host-meta with a template,
>> to advertise how any resource on the host can be provisioned. Off the
>> top of my head, I'm not sure that is very useful.
>>
> That's nifty, I hadn't thought of putting the link in the host meta. That would be a nice way to create a new XRD entirely, but I imagine that should have a different rel, as one only makes sense for updating a single XRD while the other only seems useful for updating a collection of XRDs. But such a use case is awfully unlikely, so I'd agree that XRDP should just stay out of the host-meta entirely.
>
Actually, I wasn't thinking of putting an XRDP endpoint in the
host-meta. Joseph points out some interesting use cases. But I agree,
for now it probably doesn't make sense there.
>
>>> 2. In provisioning a link, should there be a way for the user to say
>>> that the<link> is "private/protected"? For example, if I keep my family
>>> photos separate from my public photos. And I want both<Link>'s
>>> provisioned in my XRD. Is there a way to restrict the family link to
>>> only those people who access the XRD in an authorized state? Or is this
>>> use case too contrived to be worthwhile? Maybe a better example would be
>>> <Link>'s representing my online health records?
>>>
>> I think having "private" XRDs is an interesting use case, but I
>> haven't seen any real consensus form around best practices in this
>> area. The resolution specs (LRDD, host-meta) do unauthenticated HTTP
>> GETs to retrieve the XRD, so any link within is public knowledge
>> (though resolving the link may in fact require authentication). Is it
>> worthwhile to return additional links if the HTTP GET for the XRD
>> included credentials? Should "protected" XRDs be linked to from a
>> "public" XRD? The later case would make it easier to deal with
>> provisioning, as you simply wouldn't add protected links to the public
>> XRD.
>>
>> Further discussion in this area would be helpful. Ideas? Anyone?
>>
> Great idea, but let's leave it for v2. Since OAuth and similar authn protocols don't have a standard way to express this, I'm not keen on imposing one yet. If the use case does seem useful, it makes more sense to do it in the authn layer. It's really dependent on a solid idea of permissions and groups that we don't need to invent right now.
>
> I don't think it's a critical feature anyway as you can just manage the permissions on the linked resources instead. I don't imagine that you're going to have a link to your health records that is only protected by access permissions to your XRD, you'll need to require authorization to do anything with that resource anyway.
>
True... but knowing that I have online health records could be an
exposure I don't want to make public. For now, the XRD "provider" (i.e.
the service managing the XRD for the user) could enable this via UI as
an advanced feature and this keeps it out of the protocol. It would
likely imply that the XRD Provider would be building the XRDs on the fly
and would require OAuth for access to the "private/protected" <Link>'s.
Doable without requiring a change to the protocol.
>
>>> 3. There should probably be a security section that talks about if/when
>>> to use SSL in provisioning. Since the PUT and DELETE commands pass all
>>> the<Link> identifiers in the URL, that information is exposed. I
>>> suppose the xml:id could be used in those circumstances.
>>>
>>>
>> Agreed. In the first draft I wanted to concentrate on the protocol
>> operations. Not to ignore security, but I expect a lot of people to
>> chime in on that subject who are more knowledgeable than I am.
>>
> I think it makes most sense to just have the put/delete operations use id regardless. The only benefit of including the data with the request is to ensure that the document hasn't been modified since last access. The standard HTTP way to do this is to mark the resource with an ETag, and when the client posts or deletes, they have an If-Match header with the entity-tag for the version they want to modify. If the tag doesn't match, the server should return a 412 Precondition Failed response. There's a similar procedure for Last-Modified and If-Unmodified-Since.
>
> Am I missing some other reason to include the attributes in the request?
>
I agree... using xml:id seems the simplest and safest.
> Also, section 5.2 Adding a Link doesn't mention where the new link should be added in the document. Similarly, section 5.3 Updating a Link doesn't say whether the updated link should be in the same position as the original link. Since XRDs are an ordered list of links and clients are encouraged to use the first link that matches, that might be an issue. I think it's okay to leave it up to implementations, but could we say that an XRDP service MAY insert new links at any position in the XRD, and that an XRDP service MAY place an updated link in a different order within the XRD?
>
This is a good point. The interesting is that ideally the user would be
in control of the order. Maybe this can again be a feature of the "XRD
Provider" rather than a feature of the protocol. That way the user gets
to determine the order rather that the service doing the provisioning.
For example, as a user, I always want flickr as the first photo service
even if I have others listed.
Joseph Holsten
If not, I'm partial to github for hosting. I've also had luck with repurposing the Makefile and scripts from the URI Templates project[1] into my about URI scheme[2]. Just tweak the Makefile constants and copy the tools dir to make it work.
1: http://code.google.com/p/uri-templates
2: http://github.com/josephholsten/about-uri-scheme
--
http://josephholsten.com
Jared Hanson
related to XRD Provisioning. You can browse the spec in Subversion
here:
http://code.google.com/p/xrd-provisioning/source/browse/spec
Thanks for your suggestions before, they are really useful. I'll
reply to them more specifically in an email yet to come. In the
meantime, feel free to submit patches against the spec.
Jared