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 amazing TwitterAuth 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 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 interfaces with the SoundCloud Ruby API Wrapper allowing you to easily access the SoundCloud API. Check out the Wiki for more info.

user.soundcloud.User.find_me

user.soundcloud.Track.find(:all)

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.