ACOAuth

#Why ACOAuth? ACOAuth is a new client library for handling OAuth requests. It's lightweight and easy to implement. It handles the OAuth handshake and then can "sign" regular request objects so that they are authenticated by the web server. It also works great as a request modifier for the ACHTTP client library.

The reason for writing a new client library is to simplify the use of OAuth for iOS developers. I felt that the current implementations were overly complex. Code should be concise and easy-to-use. I hope you'll agree that ACOAuth is easy to understand and use.

#Using ACOAuth To use OAuth, you need a consumer key and secret. You will get those from your application service provider. For instance, if you are integrating with Twitter, you would receive these by setting up a new application on Twitter. OAuth authenticates you application to access protected resources on the application service provider's site. You may also need the OAuth endpoints for requesting tokens, accessing tokens and authorizing users.

You start by creating a configuration. This holds all the information about the OAuth request such as the tokens, secrets and URL endpoints. To create a new configuration, just do this:

ACOAuthConfiguration* config = [ACOAuthConfiguration configurationWithConsumerKey:consumerKey 
                                                                        andSecret:consumerSecret
                                                                       forBaseURL:[NSURL URLWithString:@"http://api.twitter.com/oauth"]];

Of course, you will need to set your consumer key/secret as variables, or enter them directly into this call. Once you have a configuration, you create a new session. Typically you want to hang on to this session because you will be using it to sign all your URL requests. To create a session, just do this:

session = [ [ACOAuthSession alloc] initWithConfiguration:config];

When you create a session, ACOAuth will handle all the dirty work for you such as getting your permanent tokens. One thing that it will need to do is to open up a UIWebView browser to handle the authorization part of the OAuth process. You can set some parameters on the configuration to help control how that happens. For instance, you may want the web view to appear in a certain color, size, or as a modal window. You can set some properties on the configuration to make that happen like this:

config.parentViewController = self.navigationController;
config.tintColor = [UIColor blackColor];

If you make the parent view controller a UINavigationController, ACOAuth will push a view controller onto the navigation stack. Otherwise, ACOAuth will open a model dialog. You can set the tint color of the navigation bar as well as the modal presentation style.

Once you get everything ready to go, ACOAuth is used to sign your requests. You can create a new NSMutableURLRequest and just sign it with this nifty method:

NSMutableURLRequest* request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http://api.twitter.com/statuses/mentions"]];
[session signRequest:request];

That's it. Now just take that request and do what you like with it. One thing that I forgot... once you've authenticated and got a token, ACOAuth stores those tokens and secrets securely in the keychain. There are methods to forget about those values if you want to reauthorize from scratch like this one:

[session.configuration removeFromKeyChain];

If you want to use the ACHTTP client library, you could do all of this with one line of code once you have your session setup:

[ACHTTPRequest get:@"http://api.twitter.com/statuses/mentions" delegate:self action:@selector(handleMentions:) modifiers:session];

Why would you do this? Because ACHTTP will parse the JSON for you and give you arrays and dictionaries that you can use by accessing the "results" property of the request.