man Jifty::Plugin::OAuth (3): secure API authorization

DESCRIPTION

An OAuth web services API for your Jifty app. Users may grant limited authorization to other applications in a secure way.

This plugin adds an "/oauth" set of URLs to your application, listed below. It also adds "is_oauthed" and "oauth_token" to Jifty::CurrentUser, so you may have additional restrictions on OAuth access (such as forbidding OAuthed users to change users' passwords).

/oauth

This lists some basic information about OAuth, and where to learn more. It also tells consumers how they may gain OAuth-ability for your site.

/oauth/request_token

The URL at which consumers POST to get a request token

/oauth/authorize

The URL at which users authorize request tokens

/oauth/authorized

After authorizing or denying a request token, users are directed here before going back to the consumer's site

/oauth/access_token

The URL that consumers POST to trade an authorized request token for an access token, with which they may act on the user's behalf

WARNING

This plugin is beta. Please let us know if there are any issues with it.

USAGE

Add the following to your config:

 framework:
   Plugins:
     - OAuth: {}

GLOSSARY

service provider: A service provider is an application that has users who have private data. This plugin enables your Jifty application to be an OAuth service provider.
consumer: A consumer is an application that wants to access or change users' private data. The service provider (in this case, this plugin) ensures that this happens securely and with users' full approval. Without OAuth (or similar systems), this would be accomplished perhaps by the user giving the consumer her login information. Obviously not ideal.
This plugin does not implement the protocol as a consumer, only as a service provider. You'll likely want more control and flexibility as a consumer.
request token: A request token is a unique, random string that a user may authorize for a consumer.
access token: An access token is a unique, random string that a consumer can use to access private resources on the authorizing user's behalf. Consumers may only receive an access token if they have an authorized request token.

NOTES

You must provide consumers access to "/oauth/request_token" and "/oauth/access_token".

You could restrict "/oauth/request_token" and "/oauth/access_token" to only logged-in users and require consumers to log in. Perhaps you could have a column in your users table that represents whether this user is a consumer and restrict access to these URLs that way. Or, you could let anyone access these URLs. This policy is left you as the developer.

Limiting access is wise because each hit to "/oauth/request_token" and "/oauth/access_token" uses some entropy (so an attacker could run a denial-of-service attack against you)

You should not allow public access to "/oauth/authorize". "/oauth/authorize" will throw a 401 (unauthorized) error if an unauthenticated user accesses it. On unauthenticated access of "/oauth/authorize", you should tangent the user to your login page to improve usability.

You should allow public access to "/oauth". This has some information for consumers.

There is currently no way for consumers to add themselves. This might change in the future, with an OAuth extension. Consumers must contact you and provide you with the following data:

consumer_key: An arbitrary string that uniquely identifies a consumer. Preferably something random over, say, ``Hiveminder''.
secret: A (preferably random) string that is used to ensure that it's really the consumer you're talking to. After the consumer provides this to you, it's never sent in plaintext. It is always, however, included in cryptographic signatures.
name: A readable name to use in displaying the consumer to users. This is where you'd put ``Hiveminder''.
url (optional): The website of the consumer.
rsa_key (optional): The consumer's public RSA key. This is optional. Without it, they will not be able to use the RSA-SHA1 signature method. They can still use HMAC-SHA1 though.

TECHNICAL DETAILS

OAuth is an open protocol that enables consumers to access users' private data in a secure and authorized manner. The way it works is:

The consumer establishes a key and a secret with the service provider. This step only happens once, and is currently manual.
The user is using the consumer's application and decides that she wants to use some data that she already has on the service provider's application.
The consumer asks the service provider for a request token. The service provider generates one and gives it to the consumer.
The consumer directs the user to the service provider with that request token.
The user logs in and authorizes that request token.
The service provider directs the user back to the consumer.
The consumer asks the service provider to exchange his authorized request token for an access token. This access token lets the consumer access resources on the user's behalf in a limited way, for a limited amount of time.

By establishing secrets and using signatures and timestamps, this can be done in a very secure manner. For example, a replay attack (an eavesdropper repeats a request made by a legitimate consumer) is actively defended against.

METHODS

init

This adds an is_oauthed accessor to Jifty::CurrentUser. It also establishes a trigger in Jifty::Record so that only OAuthed consumers with write access can do anything other than read.

AUTHOR

Shawn M Moore "<[email protected]>"