SoundcloudAuth
===========

SoundcloudAuth aims to provide a complete authentication and API access solution for creating SoundCloud applications in Rails. It provides a generator and all of the necessary components to use Soundcloud as the sole authentication provider for an application using OAuth.

### Major Props

SoundcloudAuth is largely influenced and in a lot of ways identical to [Michael Bleigh's](http://github.com/mbleigh) amazing [TwitterAuth](http://github.com/mbleigh/twitter-auth) plugin. I've used TwitterAuth so many times on my Twitter app development that I found it sorely missed when I tried to tackle the SoundCloud platform.  All props and donations should be forwarded to Michael.

Installation
============

You can include SoundcloudAuth as a gem in your project like so:

    config.gem `soundcloud-auth`, :lib => `soundcloud_auth`

Or you can install it as a traditional Rails plugin:

    script/plugin install git://github.com/leemartin/soundcloud-auth.git

Note that because SoundcloudAuth utilizes Rails Engines functionality introduced in Rails 2.3, it will not work with earlier versions of Rails.

Usage
=====

To utilize SoundcloudAuth in your application you will need to run the generator:

    script/generate soundcloud_auth

This will generate a migration as well as set up the stubs needed to use the Rails Engines controllers and models set up by SoundcloudAuth. It will also create a User class that inherits from SoundcloudUser, abstracting away all of the SoundCloud authentication functionality and leaving you a blank slate to work with for your application. 

Finally, it will create a configuration file in `config/soundcloud_auth.yml` in which you should input your OAuth consumer key and secret as well as a custom callback for development (the 'oauth_callback' option is where SoundCloud will send the browser after authentication is complete).

Usage Basics
------------

SoundcloudAuth borrows heavily from [Restful Authentication](http://github.com/technoweenie/restful-authentication) for its API because it's simple and well-known. Here are some of the familiar methods that are available:

* `login_required`: a before filter that can be added to a controller to require that a user logs in before he/she can view the page.
* `current_user`: returns the logged in user if one exists, otherwise returns `nil`.
* `logged_in?`: true if logged in, false otherwise.
* `redirect_back_or_default(url)`: redirects to the location where `store_location` was last called or the specified default URL.
* `store_location`: store the current URL for returning to when a `redirect_back_or_default` is called.
* `authorized?`: override this to add fine-grained access control for when `login_required` is already called.

Accessing the SoundCloud API
-------------------------

The `User` class will have a `soundcloud` method that provides a generic dispatcher with HTTP verb commands available (`get`, `put`, `post`, and `delete`). These are automatically initialized to the `base_url` you specified in the `twitter_auth.yml` file, so you need only specify a path. Additionally, it will automatically append a .json extension and parse the JSON if you don't provide.

    user.soundcloud.get('/me')
    # => {'username' => 'leemartin', 'full_name' => 'Lee Martin' ... }

		user.soundcloud.put('/me', 'user[website]=http://lee.ma/rtin')
		# => {'username' => 'leemartin', 'website' => 'http://lee.ma/rtin'}

If SoundCloud returns something other than a 200 response code, SoundcloudAuth will catch it and try to raise a salient error message. The exception class is `SoundcloudAuth::Dispatcher::Error`.

Customizing SoundcloudAuth
-----------------------

There are a number of hooks to extend the functionality of SoundcloudAuth. Here is a brief description of each of them.

### Controller Methods

SoundcloudAuth provides some default controller methods that may be overridden in your `ApplicationController` to behave differently.

* `authentication_failed(message)`: called when SoundCloud authorization has failed during the process. By default, simply redirects to the site root and sets the `flash[:error]`.
* `authentication_succeeded(message=default)`: called when SoundCloud authorization has completed successfully. By default, simply redirects to the site root and sets the `flash[:notice]`.
* `access_denied`: what happens when the `login_required` before filter fails. By default it stores the current location to return to and redirects to the login process.

Copyright
---------

**SoundcloudAuth** is Copyright (c) 2010 [Lee Martin](http://lee.ma/rtin), released under the MIT License.