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:

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

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.