<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Service_OAuth Component Proposal

Table of Contents

1. Overview

The OAuth protocol reached final draft during October. It is a protocol allowing websites, web applications or desktop applications to access Service Resources via an API without requiring Users to disclose their credentials. It is an open and decentralised protocol.

A simple use case would be Twitter. At present, Twitter applications such as Spaz.air or Twitterer require a User's login username and password (their credentials) in order to access the timeline of other Users they are following or send updates (tweets). This raises a risk that such applications may use those credentials to change the User's password, send "tweets" without their permission, or other unauthorised actions. Implementing OAuth, such an application would be able to perform limited authorised actions without requiring Users to disclose their credentials. In effect, this is similar to establishing API Key and indeed OAuth builds upon existing standards.

OAuth is therefore perfect also in situations where a Service Provider is not aware of a User's credentials, as is the case when a Provider implements OpenID. In OpenID, credentials are centralised to a single OpenID Provider and implementing Consumers will require an alternate means of allowing authenticated User's to access their Service Resources via an API. OAuth is not an OpenID extension, but does complement it.

2. References

na

3. Component Requirements, Constraints, and Acceptance Criteria

na

4. Dependencies on Other Framework Components

Zend_Http_Request
Zend_Crypt_Hmac
Zend_Crypt_Rsa (proposal pending)

5. Theory of Operation

Hypothetical Example:

A Service Provider engaged in allowing User's to answer one question "What are you NOT doing?" has determined that requiring User credentials to access their Web Service API is unnecessarily risky. To improve User security, and allow for future OpenID adoption, they determine to implement OAuth.

The Service Providers provides to Users details of how to register for a Consumer Key and Consumer Secret, and declares several new URLs including:

Request Token URL:
https://example.com/request_token, using HTTP POST
User Authorization URL:
http://example.com/authorize, using HTTP Authorize Header
Access Token URL:
https://example.com/access_token, using HTTP POST

The Service Provider provides support for HMAC-SHA1 signature authenticated coding. RSA-SHA1 is also a possible alternative (though not for this example! ).

1. Obtaining an initial Request Token (Requesting Approval)

Joe Bloggs, a User, visits a third-party web application from which he wishes to view and post new updates to the Service Provider. The application tries to access the User's posts but receives a HTTP 401 Unauthorized header including the following response header:

WWW-Authenticate: OAuth realm="http://example.com/authorize"

The application sends back a HTTP POST request:

The Service Provider verifies the oauth_signature value and sends back an unauthorised (requires User authorisation) Request Token in the response body:

2. Obtaining User Authorisation of Request (Approve Request)

The application at this point redirects the User to the Service Provider Authorization URL so that Joe can approve the application's access to the Service Provider.

Joe will log in using either his credentials, or via OpenID. He may then approve the application's access. Once approved, the Service Provider will redirect back to the Consuming web application with:

3. Obtaining an Access Token on foot of an approved Request Token (Gaining Access)

Now that the web application is approved for access, they can request an Access Token to replace the Request Token:

The Service Provider will check the signature, and reply an Access Token in the response body:

The Consuming application is now ready to make authorised requests of the Web Service API. If the Web Service API URL is unsecured (not HTTPS) then subsequent requests must be signed using HMAC-SHA1 to protect the Access Token from being intercepted and being used by an unauthorised party.

Security Notes: PLAINTEXT style requests are intended only for use across a secured connection. Otherwise a cryptographic method such as Diffie-Hellman may be utilised (unspecified). Consumer Access Tokens should not be used to assume a Consumer is a User. Access Tokens should allow only limited authorised actions. Phishing remains an issue. Users must be careful that Service Provider URLs they are redirected to for entering credentials are authenticated.

6. Milestones / Tasks

• Milestone 1: Write unit tests capturing the agreed interface and behaviour
• Milestone 2: Write the code required to pass all unit tests
• Milestone 3: Write integration tests to cover various edge cases
• Milestone 4: Verify that code does not compromise backwards compatibility with ZF 1.0.2
• Milestone 5: Complete documentation

Milestones will commence only if proposal has been accepted for development.

7. Class Index

• Zend_Service_OAuth
• Zend_Service_OAuth_Exception
• Others may be determined during development

8. Use Cases

Maybe another day? Next draft...

9. Class Skeletons

Test-Driven Development is intended to be used.