Jifty::Plugin::OAuth(3pm)				User Contributed Perl Documentation				 Jifty::Plugin::OAuth(3pm)

NAME

       Jifty::Plugin::OAuth - 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:

       o   The consumer establishes a key and a secret with the service provider. This step only happens once, and is currently manual.

       o   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.

       o   The consumer asks the service provider for a request token. The service provider generates one and gives it to the consumer.

       o   The consumer directs the user to the service provider with that request token.

       o   The user logs in and authorizes that request token.

       o   The service provider directs the user back to the consumer.

       o   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.

SEE ALSO

       Net::OAuth::Request, <http://oauth.net/>

AUTHOR

       Shawn M Moore "<sartak@bestpractical.com>"

LICENSE

       Jifty::Plugin::OAuth is Copyright 2007-2008 Best Practical Solutions, LLC.  Jifty::Plugin::OAuth is distributed under the same terms as
       Perl itself.

perl v5.12.4							    2009-11-19						 Jifty::Plugin::OAuth(3pm)