OAuth2Client

An OAuth2 library for Mac OS X & iOS (Cocoa & Cocoa touch).

Description

This library is based on draft 10 of the OAuth2 spec. It implements the native application profile and supports the end-user authorization endpoint via an internal or an external user-agent. Furthermore it also supports the user credentials flow by prompting the end-user for their username and password and use them directly to obtain an access token. See the description of the delegate for more information how to choose the authentication flow.

Getting started

Get the sources

Getting the sources is as easy as doing a:
git clone git://github.com/nxtbgthng/OAuth2Client.git

Adding the library to your project using CocoaPods

CocoaPods is a dependency manager for Xcode projects. It manages the above installation steps automatically.

In order to install the library this way add the following line to your Podfile:

pod 'NXOAuth2Client', '~> 1.2.8'

and run the following command pod install.

Note: CocoaPods is now the preferred way to integrate NXOAuth2Client into Xcode

Manually including the library in your Xcode project

iOS projects

• Place the OAuth2Client folder within your source root
• Drag the OAuth2Client.xcodeproj into your project
• Under your build target, select the Build Phases tab.
  • Under Target Dependencies add OAuth2Client
  • Under Link Binary With Libraries, add libOAuth2Client.a
• Under Build Settings,
  • Add $(SRCROOT)/path/to/OAuth2Client Header Search Paths, set as recursive
  • Add -ObjC to Other Linker Flags
• #import "NXOAuth2.h"
• add the Security.framework as a build dependency

Desktop Mac projects

• drag the OAuth2Client.xcodeproj into your project
• add OAuth2Client.framework as a build dependency
• add the Security.framework as a build dependency
• add $(CONFIGURATION_BUILD_DIR)/$(CONTENTS_FOLDER_PATH)/Frameworks to your targets Framework Search Path
• link your target against OAuth2Client (drag the OAuth2Client.framework product from OAuth2Client.xcodeproj to your targets Link Binary With Libraries)
• #import <OAuth2Client/NXOAuth2.h>

Using the library as a framework in desktop applications is fairly untested. Please report any issues and help in making the library better.

Using the OAuth2Client

Configure your Client

The best place to configure your client is +[UIApplicationDelegate initialize] on iOS or +[NSApplicationDelegate initialize] on Mac OS X. There you can call -[NXOAuth2AccountStore setClientID:secret:authorizationURL:tokenURL:redirectURL:forAccountType:] on the shared account store for each service you want to have access to from your application. The account type is a string which is used as an identifier for a certain service.

<pre> + (void)initialize; { [[NXOAuth2AccountStore sharedStore] setClientID:@"xXxXxXxXxXxX" secret:@"xXxXxXxXxXxX" authorizationURL:[NSURL URLWithString:@"https://...your auth URL..."] tokenURL:[NSURL URLWithString:@"https://...your token URL..."] redirectURL:[NSURL URLWithString:@"https://...your redirect URL..."] forAccountType:@"myFancyService"]; } </pre>

Take a look at the Wiki for some examples.

Unless otherwise specficied, the token request will be called with a HTTP Header 'Content-Type' set to 'multipart/form-data'. If you wish that header to be set to 'application/x-www-form-urlencoded', the custom header fields must be modified.

<pre> NSMutableDictionary *configuration = [NSMutableDictionary dictionaryWithDictionary:[[NXOAuth2AccountStore sharedStore] configurationForAccountType:kOAuth2AccountType]]; NSDictionary *customHeaderFields = [NSDictionary dictionaryWithObject:@"application/x-www-form-urlencoded" forKey:@"Content-Type"]; [configuration setObject:customHeaderFields forKey:kNXOAuth2AccountStoreConfigurationCustomHeaderFields]; [[NXOAuth2AccountStore sharedStore] setConfiguration:configuration forAccountType:kOAuth2AccountType]; </pre>

Consult the documentation of the OAuth2 provider to determine acceptable Content-Type header values.

Requesting Access to a Service

Once you have configured your client you are ready to request access to one of those services. The NXOAuth2AccountStore provides three different methods for this:

• Username and Password

<pre> [[NXOAuth2AccountStore sharedStore] requestAccessToAccountWithType:@"myFancyService" username:aUserName password:aPassword]; </pre>

• External Browser

<pre> [[NXOAuth2AccountStore sharedStore] requestAccessToAccountWithType:@"myFancyService"]; </pre>

If you are using an external browser, your application needs to handle the URL you have registered as an redirect URL for the account type (e.g. a custom URL scheme like myfancyscheme://oauth). The service will redirect to that URL after the authentication process.

In -[AppDelegate application: openURL: sourceApplication: annotation:] pass the redirect URL to

<pre> [[NXOAuth2AccountStore sharedStore] handleRedirectURL: url]; </pre>

• Provide an Authorization URL Handler

<pre> [[NXOAuth2AccountStore sharedStore] requestAccessToAccountWithType:@"myFancyService" withPreparedAuthorizationURLHandler:^(NSURL *preparedURL){ // Open a web view or similar }]; </pre>

Using an authorization URL handler gives you the ability to open the URL in an own web view or do some fancy stuff for authentication. Therefore you pass a block to the NXOAuth2AccountStore while requesting access.

One method for receiving a code and exchanging it for an auth token requires the following:

1. Load the preparedURL into an existing UIWebView as part of the block code above. Be certain to set the delegate for the UIWebView.

<pre> [_webView loadRequest:[NSURLRequest requestWithURL:preparedURL]]; </pre>

2. In the webViewDidFinishLoad: delegate method, you will need to parse the URL for your callback URL. If there is a match, pass that URL to -[NXOAuth2AccountStore handleRedirectURL:]

<pre> if ([webView.request.URL.absoluteString rangeOfString:kOAuth2RedirectURL options:NSCaseInsensitiveSearch].location != NSNotFound) { [[NXOAuth2AccountStore sharedStore] handleRedirectURL:[NSURL URLWithString:webView.request.URL.absoluteString]]; } </pre>

This is a very basic example. In the above, it is assumed that the code being returned from the OAuth2 provider is in the query parameter of the webView.request.URL (i.e. http://myredirecturl.com?code=<verylongcodestring>). This is not always the case and you may have to look elsewhere for the code (e.g. in the page content, web page title). You must prepare a URL in the format described above to pass to -[NXOAuth2AccountStore handleRedirectURL:].

On Success

After a successful authentication, a new NXOAuth2Account object is in the list of accounts of NXOAuth2AccountStore. You will receive a notification of type NXOAuth2AccountStoreAccountsDidChangeNotification, e.g., for updating your UI.

<pre> [[NSNotificationCenter defaultCenter] addObserverForName:NXOAuth2AccountStoreAccountsDidChangeNotification object:[NXOAuth2AccountStore sharedStore] queue:nil usingBlock:^(NSNotification *aNotification){ // Update your UI }]; </pre>

If an account was added the userInfo dictionary of the notification will contain the new account at the NXOAuth2AccountStoreNewAccountUserInfoKey. Note though that this notification can be triggered on other events (e.g. account removal). In that case this key will not be set.

On Failure

If the authentication did not succeed, a notification of type NXOAuth2AccountStoreDidFailToRequestAccessNotification containing an NSError will be sent.

<pre> [[NSNotificationCenter defaultCenter] addObserverForName:NXOAuth2AccountStoreDidFailToRequestAccessNotification object:[NXOAuth2AccountStore sharedStore] queue:nil usingBlock:^(NSNotification *aNotification){ NSError *error = [aNotification.userInfo objectForKey:NXOAuth2AccountStoreErrorKey]; // Do something with the error }]; </pre>

Getting a List of all Accounts

The authenticated accounts can be accessed via the NXOAuth2AccountStore. Either the complete list, only a list of accounts for a specific service or an account with an identifier (maybe cached in the user settings).

<pre> for (NXOAuth2Account *account in [[NXOAuth2AccountStore sharedStore] accounts]) { // Do something with the account }; for (NXOAuth2Account *account in [[NXOAuth2AccountStore sharedStore] accountsWithAccountType:@"myFancyService"]) { // Do something with the account }; NXOAuth2Account *account = [[NXOAuth2AccountStore sharedStore] accountWithIdentifier:@"...cached account id..."]; </pre>

Each NXOAuth2Account has a property userData which can be used to store some re