From Yadis

Please do not edit this page. This is the frozen text of Yadis Specification Version 0.8. Thank you.

Click here for

Yadis Specification 1.0

2 Normative References

The following specifications contain provisions which, through reference in this text, constitute provisions of this Yadis Specification. At the time of publication, the editions indicated were valid, with the exception of those in Clause 2.3. All specifications are subject to revision, and parties to agreements based on this Specification are encouraged to investigate the possibility of applying the most recent edition of the specifications listed below.

2.1 Requests for Comments

RFC 2119 Key words for use in RFCs to Indicate Requirement Levels, March 1997.

RFC 2616 Hypertext Transfer Protocol -- HTTP/1.1, June 1999.

RFC 3896 Uniform Resource Identifier (URI): Generic Syntax, January 2005.

RFC 3987 Internationalized Resource Identifiers (IRIs), January 2005.

2.2 W3C Recommendations

HTML 4.01 HTML 4.01 Specification, 24 December 1999.

2.3 OASIS Specifications

The following documents have not been adopted by OASIS. They are listed here for two reasons:

• We have followed these drafts in preparing this Yadis Specification.

• Should OASIS adopt such specifications, we want to conform to them and will at that time reference them here as normative references.

XRI Syntax Extensible Resource Identifier (XRI) Syntax V2.0, Committee Specification, 14 November 2005.

XRI Resolution Extensible Resource Identifier (XRI) Resolution V2.0, Working Draft 09, 10 November 2005. (See XRI Resolution 2.0 specification on this wiki.)

3 Terms and Definitions

3.1 Developer Terms

Note: Yadis IDs and the Yadis Protocol are intended to be used not only by persons but also by other parties, such as clubs, crowds, businesses and governments. This terminology does not attempt to be general in this way, but instead focuses on use by persons.

3.2 End-user terms

Yadis User	A person using a Yadis ID as a personal identifier.
Yadis ID	An personal identifier used in one or more Yadis Identity Services. A Yadis ID may be a URL, any URI or IRI usable in an HTTP request, or an XRI resolvable to a URL. A Yadis Resource Descriptor may be obtained by using the Yadis ID in the Yadis Protocol. See REST-ful Yadis URL, Hosted Yadis URL, and Delegating Yadis URL below.
Yadis Page	In case there is a document located by a Yadis ID, that document.
Yadis Identity Service	A computer software process (or system of processes) that provides services located using the Yadis Protocol.
Agent	A computer software process (or system of processes) acting on behalf of a person or organization.
Yadis User Agent	An agent acting on behalf of a Yadis User.
Relying Party	A person or organization responsible for a Relying Party Agent and on whose behalf that Agent acts. A Relying Party is relying on the services provided by a Yadis Identity Service, in particular on data provided by that service concerning the person identified by a Yadis ID.
Relying Party Agent	A role to be fulfilled by an agent that uses a Yadis ID (and the data accessible using that Yadis ID) provided by a Yadis User Agent. The Relying Party Agent discovers the services available for a Yadis ID using the Yadis Protocol, and modifies its own behavior accordingly.
Identity Consumer	A Relying Party Agent.
Identity Server	A role to be fulfilled by a server that hosts one or more Hosted Yadis IDs. The Identity Server may or may not be located by the same URL as the Yadis ID.
REST-ful Yadis ID	A Yadis ID which, in the Yadis Protocol, itself returns a Yadis Resource Descriptor. LID identifiers are REST-full Yadis IDs.
Hosted Yadis ID	A Yadis ID which, in the Yadis Protocol, does not itself return a Yadis Resource Descriptor, but instead specifies an Identity Server, but no delegate Yadis ID. OpenID URLs are either Hosted Yadis URLs, or Delegating Yadis IDs.
Delegating ID URL	A Yadis ID which, in the Yadis Protocol, does not itself return a Yadis Resource Descriptor, but which specifies an Identity Server and a delegate Yadis ID. OpenID URLs are either Hosted Yadis URLs, or Delegating Yadis URLs.

My ID	An identifier a Yadis User uses to identify an individual, such as themselves or somebody else. Same as Yadis ID.
My page	The document located by My URL. Same as Yadis Page.

3.3 Definitions from other specifications

This specification makes use of the following terms as defined in the indicated specifications:

scheme RFC 3968 3.1

URL RFC 3968 1.1.2

4 Abbreviations

These abbreviations are use in this specificaiton:

YRD Yadis Resource Descriptor

(I'll gather the others and list them here. --jm)

5 Conventions

The key words and word pairs, "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL", in this document are to be interpreted as described in RFC 2119.

6. The Yadis Protocol

6.1 Overview of the Yadis Protocol

The purpose of the Yadis protocol is to enable a Relying Party, which has been proffered a Yadis ID, to obtain a Yadis Resource Descriptor that describes the services available using that Yadis ID.

6.1.1 Obtaining the Yadis Resource Descriptor

When a User provides a Yadis ID to a Relying Party, that Relying Party will want to discover which services are available using that Yadis ID. (Is it a LID or OpenID URL? What authentication methods are available?)

To do that, the Relying Party makes an HTTP request. This request may take any one of several forms, discussed later in this document.

In response to the request, the Relying Party obtains either:

1. A Yadis Resource Descriptor.

2. A URL that locates a Yadis Resource Descriptor.

3. Some other response; in this case the identifier is not a Yadis ID or there has been a failure.

If the response is 2, the Relying Party uses that URL to obtain the Yadis Resource Descriptor.

The Resource Descriptor lists the services available using that Yadis ID, including services that can authenticate the User.

For a description of the Yadis Resource Descriptor, see Yadis Resource Descriptor.

Whenever 'HTTP' is specified in this document, a request must use either the HTTP protocol or the HTTPS protocol, according to the scheme name in the URL being used.

6.1.2 Authentication

Yadis delegates authentication to the Identity Services.

The Relying Party uses the information in the Yadis Resource Descriptor to choose an Identity Service suitable to its purposes, and uses that Service to authenticate the user.

6.1.3 Other services

Identity Services offer other services, in addition to authentication. These services are identified in the Yadis Resource Descriptor and each Service operates according to the specification of the particular Identity Service providing that Service.

Example: LID defines a RESTful protocol that allows the structured query of profile information independent of the schema in which that information is expressed.

6.2 Protocol Specification

6.2.1 Yadis ID

A Yadis ID MUST be a URL (or a URI or XRI resolvable to a URL). The scheme name of that URL must be HTTP or HTTPS. In the remainder of this Section 5.2, that URL is called the ‘Yadis URL.’

6.2.2 Alternatives

A Relying Party MAY use the Yadis URL to make an HTTP GET request. This request MAY return an HTML document. If it does, either that document itself or the HTTP response-headers will contain a URL giving the location of the Yadis Resource Descriptor. The Relying Party then obtains the Yadis Service Descriptor using that URL.

The Yadis Protocol also includes two alternatives:

The Relying Party MAY first issue an HTTP HEAD request. In that case, the URL MAY be returned in an HTTP response-header.

The Relying Party MAY include in the HTTP GET request an Accept request-header asking for the Yadis Resource Descriptor to be returned. In that case the Yadis Resource Descriptor MAY be returned in response to that request, instead of an HTML document.

Note: If the resource located by a Yadis ID will be returning a Yadis Resource Descriptor document in response to an Accept request-header, all responses to a request using the Yadis URL need to include a Vary: Accept response-header to indicate to intervening caches that differing values of the Accept header may return different responses. This header needs to be present even in the case where the HTML page is returned (instead of a Yadis Resource Descriptor document).

The following sections specify the steps of the Yadis Protocol.

[I will later provide an illustration for each of the alternatives in the form of UML sequence diagrams. –jm]

6.2.3 Initiation

The Yadis Protocol is initiated by the Relying Party with an initial HTTP (or HTTPS) request using the Yadis URL.

This request MUST be either a GET or a HEAD request.

A GET request MAY include an HTTP Accept request-header [HTTP 14.1] specifying MIME type, application/xrds+xml.

6.2.4 Response

The response to the initial request MUST comply with the HTTP (or HTTPS) protocol.

The response MUST be one of:

1. An HTML document with a element which includes a element with http-equiv attribute, X-Yadis-Location

2. An HTML document with HTTP response-headers which include an X-Yadis-Location response-header

3. HTTP response-headers only, which MAY include an X-Yadis-Location response-header

4. A document of MIME type, application/xrds+xml

Note: Since the response to the initial request MUST comply with the HTTP (or HTTPS) protocol, if the request is a GET and does not include an "Accept: application/xrds+xml" header, the response MUST be of type 1 or 2. This is required because the Relying Party MAY omit the Accept and so might only look for the X-Yadis-Location.

6.2.5 Document

If the response is a document of MIME type, application/xrds+xml, that document MUST be a Yadis Resource Descriptor (see Clause 7).

6.2.6 URL

If the response includes an X-Yadis-Location response header or an HTML element whose http-equiv attribute is X-Yadis-Location the value MUST be an absolute URL. That URL is a Yadis Resource Descriptor locator; it MUST locate a Yadis Resource Descriptor.

The Relying Party MUST issue an HTTP GET to retrieve that Yadis Resource Descriptor document.

6.2.7 Second Request

Unless a Relying Party using an HTTP Accept request-header obtains the Yadis Resource Descriptor in response to that request, that Relying Party MUST examine the response to determine if it contains a Yadis Resource Descriptor Locator in either the HTTP response-headers or the HTML element and request the document as specified in Section 6.2.6.

Unless a Relying Party using an HTTP HEAD request obtains a Yadis Resource Descriptor Locator in response to that request, that Relying Party MUST then issue an HTTP GET request and examine the response to determine if it contains a Yadis Resource Descriptor Locator in either the HTTP response-headers or the HTML element and request the document as specified in Section 6.2.6.

6.2.8 Termination

When a Yadis Resource Descriptor is returned to the Relying Party the Yadis Protocol terminates.

If none of the requests succeed in obtaining a Yadis Resource Descriptor then the URL used in the initial request is not a Yadis URL or there has been a failure.

7. The Yadis Resource Descriptor

7.1 Overview of the Yadis Resource Descriptor

Note: We considered providing both a text and an XML-based format, in order to make it as easy as possible for Relying Parties clients to use service information available through Yadis IDs. However, we came to the conclusion that requiring both a text and an XML based format provides only small additional value, and using an XML based format enables use of standard parsing tools.

We have chosen a simple, extensible XML document called an Extensible Resource Descriptor (abbreviated XRD). The format of XRD documents is being specified by the XRI Technical Committee of OASIS (see XRI Resolution 2.0 specification).

The Yadis Resource Descriptor provides a list of identifiers of Services. These are the Services that know the User identified by the Yadis ID used to obtain the Yadis Resource Descriptor. In the case of some Services, additional data is included for use by the Relying Party in making a request to the Service.

The Resource Descriptor also enables the User to specify which of the Services it prefers be used.

7.2 A simple Yadis Resource Descriptor

Here is an example of a small Yadis Resource Descriptor:

 
 
   
 
     
       http://lid.netmesh.org/sso/2.0b5
     
 
     
       http://lid.netmesh.org/sso/1.0
     
 
   
 

This Resource Descriptor specifies two services.

7.2.1 XRD

A Yadis Resource Descriptor document consists of an XRD container (the XRDS element) with a Yadis Resource Descriptor (the XRD element). A resource descriptor contains a sequence of service descriptions. Each service description is a Service element.

The order of the service descriptions is not significant.

A Yadis Resource Descriptor document MUST include at least one XRD element.

7.2.2 Service

An XRD element in a Yadis Resource Descriptor MAY contain one or more Service elements describing a Yadis service.

Each Yadis Service element consists of a Type element plus optional elements.

Note: We encourage identity protocol designers to be brief.

Note: A Yadis Resource Descriptor that has no Service elements describing a Yadis service is permitted.

7.2.3 Type

Each Yadis Service element MUST contain at least one Type element.

Each Type element MUST contain an identifier of some version of some service. This service identifier MUST be a URI or XRI. It MUST identify a single version of that service.

For each service identified by a Type element there SHOULD be a service specification document. It is RECOMMENDED that the service identifier be resolvable to a locator for that service specification document.

It is RECOMMENDED that each service identifier include an explicit version identifier, in order to facilitate the evolution of the service in the future.

7.2.4 XRDS

A Yadis Resource Descriptor begins with the opening of an XRDS element and two XML namespace declarations:

  
  
          
This is followed by:
          
declarations of any other XML namespaces that will be used
          
  >

          
to close the XRDS element
          
an XRD element with Service elements
          
and
          
  

          
to end the XRDS.
          

            [edit]
          

          
7.3 Other parts of a Yadis Resource Descriptor
          
Here is an example of a larger Yadis Resource Descriptor:
          
 
 
     xmlns:openid="http://openid.net/xmlns/1.0"
 >
   
 
     
       http://openid.net/signon/1.0
       http://www.myopenid.com/server
       http://jimmy.myopenid.com/
     
 
     
       http://openid.net/signon/1.0
       http://www.example.com/openid
       
         http://users.example.com/james.s
       
     
 
     
       http://openid.net/signon/1.0
       http://www.livejournal.com/openid/server.bml
       
         http://www.livejournal.com/users/jimmy/
       
     
 
     
       http://lid.netmesh.org/sso/2.0b5
     
 
     
       http://lid.netmesh.org/sso/1.0
     
 
   
 

          

            [edit]
          

          
7.3.1 URI element
          
A Yadis Service element MAY contain one or more URI elements. Each URI element specifies a resource that will provide the service.
          
Each URI element MUST contain a URI that resolves to a resource providing the service (or services) specified by the Type element(s) of that Service element.
          
That URI MUST be an absolute URL, not a relative URL, URL reference, or other URI.
          
Note: It is our intention that this element may contain any URI or may contain an IRI, as specified by [RFC 3987]. This will be specified in a later version of this specification.
          
If a Relying Party chooses a Service element that contains one or more URI elements, that Relying Party MUST recognize and use a URI element of that Service element.
          
If there is more than one URI element, the URIs in those elements MUST be equivalent for the purpose of using the service. A Relying Party MAY attempt to use any one or all of the URIs.
          
If one or more URI elements has a priority attribute, a Relying Party MAY use the priority values as specified in Clause 2.4.3 of the XRI Resolution 2.0 specification.
          
The order of URI elements is not significant.
          
The URI element is OPTIONAL.
          

            [edit]
          

          
7.3.2 Priority attribute
          
The OPTIONAL priority attribute of the Service element allows the User to specify preferences for the Service to be used. The example above indicates that the User prefers the OpenID protocol using the server, http://www.myopenid.com/server, and that the last choice is LID version 1.0.
          
In keeping with the goal of ease of implementation, a Relying Party MAY ignore the priority attribute. A Relying Party that recognizes and uses the priority attribute in one or more Service elements MUST follow the specification of priority attributes in Clause 2.4.3 of the XRI Resolution 2.0 specification.
          

            [edit]
          

          
7.3.3 Other elements in a Service element
          
Yadis does not specify any other elements for a Service element. A Service MAY define and use other elements.
          
Note: This allows a Service element to indicate things that are specific to that service. As examples, the OpenID specification defines the optional Delegate element, which specifies a URL by which the OpenID server knows the User; the TypeKey specification defines the MemberName element.
          
If a Relying Party intends to chose a particular service, that Relying Party MUST recognize and use all elements specified by a service specification for inclusion in a Service element for that service.
          
A Relying Party MAY ignore all other elements in a Service element. A Relying Party MAY recognize and use any elements in a Service element, which are specified by the XRD schema.
          
A Relying Party using a Yadis Resource Descriptor MAY ignore any element of that document except for the elements specified here and any elements specified by a service specification.
          
Any Relying Party not using a particular service MAY ignore any element of Yadis Resource Descriptor that is specified by the service specification of that service. The use of elements specified by a service specification is determined by that service specification.
          

            [edit]
          

          
7.3.4 Other elements in an XRD
          
An XRD in a Yadis Resource Descriptor document may contain Service elements that do not identify Yadis services. A Relying Party MAY ignore all such Service elements.
          
A Yadis service MUST NOT require the use of a Service element that does not identify that Yadis service in a Type element of that Service element.
          
A Relying Party MAY ignore all other elements in an XRD element.
          
A Relying Party MAY recognize and use any elements in an XRD element, which are specified by the XRD schema.
          
A Yadis service MUST NOT require the use of any elements of an XRD other than the Service elements that identify the services of that Yadis Service.
          

            [edit]
          

          
7.3.5 Other services
          
The examples so far have been for single sign-on services, the scenario described in Section 4.1. A Yadis service MAY offer other services. A Yadis service is NOT REQUIRED to offer a single sign-on service.
          
For example, the following Resource Descriptor specifies a number of LID services available at the resource identified by the users Yadis ID:
          
 
 
   
 
     
       http://lid.netmesh.org/sso/2.0b5
     
 
     
       http://lid.netmesh.org/sso/1.0
     
 
     
       http://lid.netmesh.org/post/sender/2.0b5
     
 
     
       http://lid.netmesh.org/post/receiver/2.0b5
     
 
     
       http://lid.netmesh.org/relying-party/2.0b5
     
 
     
       http://lid.netmesh.org/traversal/2.0b5
     
 
     
       http://lid.netmesh.org/format-negotiation/2.0b5
     
 
   
 

          

            [edit]
          

          
7.3.6 Other XRDs and other elements in the XRDS
          
The XRDS schema permits more than one XRD in an XRDS and permits other elements in an XRDS, in addition to XRD elements. Such documents are valid Yadis Resource Descriptors.
          
A Relying Party MUST examine the last of the XRD elements in an XRDS returned in response to a request for a Yadis Resource Descriptor document.
          
A Relying Party MAY ignore all other elements in an XRDS.
          

            [edit]
          

          
7.4 Schema for the Yadis Resource Descriptor
          
The schemas of the Yadis Resource Descriptor document are the XRDS and XRD schemas contained in Appendix A, XML Schema for XRDS and XRD, of working draft 9 of the XRI Resolution 2.0 specification.
          
A Yadis Resource Descriptor document MUST conform to the XRDS schema. A Yadis Resource Descriptor is an XRD element; it MUST be contained in an XRDS element and MUST conform to the XRD schema.
          
Until such time as those schemas may be adopted by OASIS, we copy them here.
          

            [edit]
          

          
XRDS Schema
          
     
  http://www.w3.org/2001/XMLSchema"
  xmlns:xrds="xri://$xrds">
     
        
     
     
        
           
           
        
     
     
        
           
              
           
           
        
     
  

          


          

            [edit]
          

          
XRD Schema
          
  
  http://www.w3.org/2001/XMLSchema"
  xmlns:xrd="xri://$xrd*($v*2.0)"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
     
        
     
     
        
           
           
        
     
     
        
           
              
           
        
     
     
        
           
              
           
        
     
     
        
           
              
              
              
              
              
              
              
           
           
           
           
        
     
     
     
        
           
              
                 
              
           
        
     
     
     
     
     
        
           
              
              
              
              
              
              
           
           
        
     
     
     
     
     
     
     
     
  

          


          

            [edit]
          

          
Possible Future Schemas
Should XRDS and XRD schemas not be adopted, we intend to include a smaller schema in the Yadis specification, limited to a subset of the elements specified in XRI-resolutoin working draft 9. We intend to modify the Yadis specification to reference subsequent working drafts and committee drafts of the XRI Resolution 2.0 specification as they are published.
          

            Retrieved from "https://yadis.org/wiki/Yadis_0.8"