iOS and Mac Sign-In Controllers graduate to OAuth 2.0

Thursday, May 26, 2011 at 3:49 PM

by Greg Robbins, Software Engineer

In September, we introduced OAuth 1 sign-in controllers to simplify authenticating users from iOS and Mac applications. As the Internet software industry is converging on a newer standard, Google now offers the Google Toolbox for Mac OAuth 2.0 Controllers. This new library enables Cocoa applications to sign in to Google and other services that conform to the latest draft of the OAuth 2.0 standard.

From the perspective of both users and developers, the new controllers are similar to the old ones, and are just as easy to use. As before, the controllers handle displaying an embedded web view and interacting with the server, and optionally allow saving the authorization token in the keychain. The server takes care of obtaining the user’s password, describing the permissions requested by the application, and asking for captcha responses or 2-step verification or whatever tomorrow’s security requires.

Here is how developers can present the sign-in view for a Google service using the OAuth 2.0 controller:

NSString *scope = @"http://www.google.com/m8/feeds/";
  // scope for accessing a user’s Google Contacts
GTMOAuth2ViewControllerTouch *viewController =
 [[[GTMOAuth2ViewControllerTouch alloc] initWithScope:scope
   clientID:@"9876.apps.googleusercontent.com"
   clientSecret:@"PVYx34Fr"
   keychainItemName:@"My App: Google Contacts"
   delegate:self
   finishedSelector:@selector(viewController:finishedWithAuth:error:)]
     autorelease];

When the user finishes signing in, the controller invokes the application’s callback method:

- (void)viewController:(GTMOAuth2ViewControllerTouch *)viewController
      finishedWithAuth:(GTMOAuth2Authentication *)auth
                 error:(NSError *)error {
  if (error == nil) {
    // Authentication succeeded; retain the auth object
  }
}

There are a few important changes for developers in the new standard. The most prominent is that developers must obtain client ID and client secret strings for an installed application from Google’s API Console. Other API providers supporting OAuth will also have web pages for issuing client ID and client secret strings. The provider may require that the application register an OAuth callback URI string, depending on the details of how they support native applications.

Another difference from the older OAuth protocol is that the step of authorizing a request must be asynchronous. Because OAuth 2.0 access tokens may expire, they must occasionally be refreshed when used to authorize a request. Our OAuth 2.0 authentication class hides the refresh step transparently by fetching refreshed tokens if needed when authorizing the application’s request, invoking a callback method or block once the request is finally authorized, like this:

[auth authorizeRequest:myNSURLMutableRequest
     completionHandler:^(NSError *error) {
       if (error == nil) {
           // the request has been authorized
         }
       }];

Applications using our API library service classes or the GTM HTTP Fetcher class can make authorized requests even more simply by setting the service or fetcher authorizer property:

[fetcher setAuthorizer:auth];

The Google Data APIs Library for Objective-C now integrates the OAuth 2.0 controllers, making it the preferred way for developers to let users sign in to the library’s many supported APIs.

You can learn more about the OAuth 2.0 protocol by checking out Google’s documentation, and about the GTM OAuth 2.0 controllers by reading the introduction at the project site. Suggestions and questions on the controllers are welcome in the GTM OAuth 2.0 discussion group.