REST/SOAP/HTTP Bindings
Contents |
Background
Initiated by a thread on the specs list, http://openid.net/pipermail/specs/2006-November/000861.html , regarding the deprecation of HTTP redirects in OpenID Auth 2.0, and its impact on OpenID's usability in a REST/SOAP/HTTP API. It seemed a parallel spec for the use of OpenID with specific non-HTML technologies was needed. While the primary focus of OpenID Auth 2.0 is the maturation of the OpenID spec for modern web browsers operated by human users, this document explores ways OpenID might be used to authenticate consumers of REST, SOAP, XML-RPC, or plain old HTTP APIs.
Nomenclature
For the purposes of this discussion, I'll use the generic term 'web services' to denote REST, SOAP, XML-RPC, or generic HTTP endpoints or services which would benefit from the ability to authenticate OpenID URLs in much the same way a Relying Party can today.
When I mean the OpenID Authentication 2.0 spec, I'll say OidAuth.
Considerations
Compatibility
To the extent possible, the web services bindings should preserve compatibility with OidAuth. Obviously perfect compatibility is not possible, however RPs and OPs should require little or no modification to support the web service bindings. Further, existing OidAuth implementation libraries should be substantively reusable when implementing web service bindings.
Use of Native Idioms
The web service bindings should to the extent possible make use of the idioms already provided by the respective web services technologies. For example, if a web service technology provides an existing extention point for custom authentication logic, this point should be preferred over a completely new extension of the technology.
Ease of Implementation
In order to reflect OpenID's overall design philosophy of simplicity and heterogeneity, incorporating OpenID into web services should be as straightforward as possible both for the developers of web services toolkits as well as web services developers themselves.
Similarity
To the extent similar problems have been solved by other technologies, it may be preferable to utilize a similar solution for OpenID in web services, to leverage familiarity with existing solutions.
Not the Problem
How the user agent authenticates the OP
Without a browser UI and a user to populate it, how the user agent authenticates itself to the OP when replaying the RP's request is an interesting problem. Perhaps another standard API could be established to allow the user to provision keys different user agents could use to provide they were sent by the user. Perhaps the user agent knows the user's credentials. This will necessarily vary with the OP, and while guidance in this area is probably valuable, it's not within the scope of this particular problem.
How browser authentication should work
OpenID Auth 2.0 determines how browser-based authentication should work. That's not the problem we're trying to solve here.
REST/SOAP-enabling the OP
Again, the assumption is that the user agent has some means to authenticate itself to the OP, just as it is assumed in OidAuth that the user has some means of authenticating herself to the OP without stipulating what that something should be.
Related Work
The problem of extending an existing web services protocol to support a new authentication scheme is not a new one; there exists substantial prior art that illustrates possible approaches to the problem.
Atom Authentication
Atom exploits the HTTP authentication extension mechanism described in RFC2617 to establish an additional authentication mechanism for use with the Authorization HTTP header, which is based on the WS-Security 1.0 UserToken profile. A more complete article on the Atom adaptation of WS-Security for use with HTTP authentication is here.
This approach has the advantage of exploiting HTTP's existing framework for authentication, though it also requires an implementation to munge HTTP headers, which may be a lower-level operation than web services toolkits typically perform.
WS-Security 1.0
The Web Services Security core standard and accompanying profiles provide a generalized framework for integrating security idioms into XML web services. WSS Core establishes an XML vocabulary for security communicating SOAP messages, while the profiles describe how specific security technologies such as username/password tokens and X.509 certificates are used with WSS.
WS-Security's goals extend far beyond OpenID's, to include issues of trust and secure communication, and not surprisingly is considerably more complicated. However, the basic principle is the establishment of a wse:Security SOAP header into which security-related payloads are placed. As WS-Security is the sanctioned security abstraction for use with SOAP, an OpenID WSS profile would be consistent with existing SOAP security idioms, though OASIS would likely need to be involved in the establishment of a credible WS-Security profile for OpenID.
SAML Bindings
The OASIS SAML bindings standard (PDF) describes HTTP and SOAP bindings for communicating SAML messages between a SAML requestor and a SAML responder by way of an HTTP agent.
Interestingly, the SAML bindings describe a few means of incorporating SAML into HTTP:
- Sending SAML requests/responses in a SOAP body
- Using 'reverse SOAP' to initiate contact with a SAML requestor, retrieve the requestor's SAML request, and post the SAML response in a subsequent HTTP request to the SAML requestor. If you find that utterly nonsensical, you are not alone.
- HTTP redirect, whereby the SAML request is forwarded to the SAML responder by way of an HTTP redirect. This is conceptually identical to the HTTP redirect used in OpenID Auth 1.1, and now deprecated in OpenID Auth 2.0.
- HTTP post, which is identical to the HTTP post method introduced in OidAuth 2.0. Much like OidAuth2, an HTML forms-capable browser and some means to submit that form are assumed.
- HTTP 'artifact' binding, in which the SAML requestor returns to the HTTP user agent a token which is forwarded to the SAML responder, which in turn uses that token to initiate communication with the SAML requestor to obtain the full request. This latter approach is intriguing.
Yahoo! Browser-Based Authentication (bbAuth)
Yahoo!s bbauth is a simple browser-based authentication scheme, utilizing a centralized authentication authority (Yahoo!), and designed specifically for integration into third-party web sites that need to access Yahoo! services on behalf of Yahoo! users. Its problem domain is considerably simpler, in that there is one auth repository, one authentication method (Yahoo! username and password), and no support for anything but browser redirects.
Possible Solutions
Extend the HTTP Authorization header
Like Atom, we could define a custom authorization type, openid. When an HTTP request is received for a resource requiring authentication, and no such authentication is present, the HTTP server could return a 401 Not Authorized, and specify the openid authentication type in the WWW-Authenticate response header. The RP's message to the OP could be included in the body, indicated by a custom content type, or it could be specified in a custom X-OpenId header.
The user agent, upon recognizing the OpenID authentication requirement, could forward the RP's message to the OP by some means defined by the OP, exchanging whatever authentication tokens the OP requires, at the conclusion of which the OP would provide the user agent with its response for the RP. The user agent would then re-initiate its previous request to the RP, including the OPs response in the Authorization header and possibly a custom X-OpenId header as well.
Advantages
By using HTTP's existing extension point for custom authentication schemes, this solution preserves the elegance of HTTP as an underlying transport. It's based on the Atom authentication approach, which is well understood and widely implemented.
Disadvantages
Implementing this solution requires the RP and user agent to manipulate HTTP headers, which isn't something web services programmers have to do much anymore.
Amazon's AWS supports specifying an API key via the Authorization header, thought also supports encoding it in a query string. I'm not aware of any other REST APIs that exploit Authorization in that way.
To be sure, exploiting HTTP authentication in lieu of a ton of XML markup is certainly at odds with the Tao of SOAP.
HTTP authentication customization is also hard/impossible on shared hosts that don't provide .htaccess support. Without this, Apache/whatever won't pass the Authorization header to the Perl/Ruby/whatever script being invoked. This should be a show-stopper for tools like web logs running on commodity hosting accounts.
WSS Profile for OpenID
We could try to establish a WSS profile for OpenID that could be included in a WSS security header in the SOAP header element, and make the requirement of an OpenID authentication token a part of the policy of each SOAP endpoint. I don't see an example within WSS of a security mechanism that requires multiple request/response cycles to complete negotiation, though that could be an oversight on my part. If that is indeed not handled in any other profile, it may require some contortions to make it consistent with the rest of the WSS profiles.
Advantages
By extending WS-Security, we'd be taking advantage of SOAP's established extension point for custom security logic.
Disadvantages
This doesn't help REST APIs at all. It's not clear how easy it is to implement custom WS-Security profiles in the major WS-Security implementations. There may be an impedance mismatch between the request/response/request cycle of the OpenID indirect communication model and the assumptions made by WSS.
HTTP GET with Artifact Binding
Borrowing from the artifact binding concept in SAML, the OpenID Auth 1.1 HTTP redirect concept could be adapted so that the redirect URL sent by the RP to the user agent doesn't include the RPs request to the OP, but rather a token of some sort that the OP in turn sends to the RP in a secondary HTTP request, to retrieve the RPs original request. The OP would then return its response to the user agent in the form of another redirect, as it currently does.
Advantages
This overcomes the limit imposed on the size of a GET request, without resorting to HTML and (optional) Javascript.
Disadvantages
The RP now has to be reachable by the OP, which is a potential problem if the RP is behind a firewall or otherwise not network-accessible. It requires the RP to maintain additional state, and would require the establishment of some sort of cryptographic token that identifies the RP's URL.
Hand-rolling
Perhaps there's no need to prescribe a binding. Perhaps the developers of each REST/SOAP API can be left to provide a parameter where an OpenID URL can be passed, and a fault code or response indicating an indirect request to the OP.
Advantages
This approach provides limitless flexibility.
Disadvantages
It falls to REST/SOAP toolkits to provide reusable OpenID support. Since no API would be exactly the same as any other, it would increase the effort required to integrate OpenID into disparate APIs.
API key provisioning
Perhaps in the case of REST/SOAP APIs, the authentication needn't be so tightly coupled to the request. Perhaps it would be sufficient to establish a standard means for provisioning an API key with an OpenID URL within a web browser, then existing key-based authentication techniques could be re-used.
Advantages
The OpenID problem simplifies to some interface guidelines and best practices for authenticating API key request with OpenID.
Disadvantages
The OpenID authentication is decoupled from each API request, limiting flexibility and security. The authentication provided becomes a considerably weaker proof that the user agent knows the API key, not that the user agent is known to the OP by whatever security token(s) the OP uses.
The user is also exposed to a rather messy implementation detail, inasmuch as she must request an API key and somehow provide it to her user agent to allow it to act on her behalf.
Keep and use HTTP GET
Maybe the use of HTTP redirects and GET shouldn't be deprecated, so programmatic clients can use that.
Advantages
HTTP redirects are already in OpenID Auth 1.1, and are well understood.
Disadvantages
The reason HTTP GETs were deprecated is they impose a limit on the size of the RP's request. It would be somewhat unfortunate to leave non-browser clients with this limitation.
Analysis
First, I don't feel that OpenID and SOAP are particularly well suited to one another. Perhaps due to my SOAP bigotry, I'm not as interested in making OpenID work with SOAP.
That leaves REST, which I find much more conceptually compatible with OpenID. The extended HTTP authorization header seems the most promising there, and will be the focus of my prototyping efforts. The other approaches are, imho, more complicated and therefore less appealing.
