GTMAppAuth Documentation

GTMAppAuth is a library designed for iOS, macOS, tvOS, and watchOS that enables the use of AppAuth alongside Google Toolbox for Mac - Session Fetcher and Google APIs Client Library for Objective-C For REST.

It provides an implementation of the GTMFetcherAuthorizationProtocol to authorize requests using AppAuth.

Key benefits include:

• Security & Usability: It uses the user's default browser for authorization, following modern OAuth best practices for native apps (RFC 8252).
• Session Reuse: Users can leverage existing sessions in their default browser.
• Migration Path: It offers compatibility methods for GTMOAuth2, allowing developers to migrate while preserving previously serialized authorizations so users do not need to re-authenticate.

Prior to version 5.0.0, GTMAppAuth used file-based Keychain storage. Current versions default to data protection Keychain storage. To migrate existing users:

1. Attempt to retrieve the session using the new GTMKeychainStore (data protection).
2. If not found, initialize a GTMKeychainStore with the GTMKeychainAttribute.useFileBasedKeychain attribute.
3. Retrieve the session from the file-based store.
4. If found, remove it from the file-based store and save it into the data protection store.

// Attempt to retrieve from Data Protection Keychain
GTMKeychainStore dataProtectionKeychainStore = [[GTMKeychainStore alloc] initWithItemName:kKeychainName];
NSError *error;
GTMAuthSession *authSession = [keychainStore retrieveAuthSessionWithError:&error];

if (!authSession) {
  // Fallback to file-based
  GTMKeychainAttribute *fileBased = [GTMKeychainAttribute useFileBasedKeychain];
  NSSet *attributes = [NSSet setWithArray:@[fileBased]];
  GTMKeychainStore fileBasedKeychainStore = [[GTMKeychainStore alloc] initWithItemName:kExampleAuthorizerKey keychainAttributes:attributes];
  authSession =[fileBasedKeychainStore retrieveAuthSessionWithError:&error];
  
  if (authSession) {
    [fileBasedKeychainStore removeAuthSessionWithError:&error];
    [dataProtectionKeychainStore saveAuthSession:authSession error:&error];
  }
}

When the authorization flow completes, the platform redirects to your app via a custom URI scheme. You must pass this URL to the active authorization flow session.

iOS

Implement application:openURL:options: in your UIApplicationDelegate. Use resumeExternalUserAgentFlowWithURL: on your stored currentAuthorizationFlow object. If it returns YES, the flow has been resumed and you should return YES to the system.

macOS

Register for kAEGetURL events in applicationDidFinishLaunching:. In your handleGetURLEvent:withReplyEvent: handler, extract the URL string and pass it to resumeExternalUserAgentFlowWithURL:.

// iOS Example
- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<NSString *, id> *)options {
  if ([_currentAuthorizationFlow resumeExternalUserAgentFlowWithURL:url]) {
    _currentAuthorizationFlow = nil;
    return YES;
  }
  return NO;
}

The macOS example requires manual configuration of the Client ID and Redirect URI. Follow these three steps in order:

1. Update Client ID: In GTMAppAuthExampleViewController.m, update the kClientID constant with your copied Client ID.
2. Update Redirect URI: In GTMAppAuthExampleViewController.m, update kRedirectURI using the reverse DNS notation of your Client ID plus the path component :/oauthredirect.
   • Example: If your Client ID is YOUR_CLIENT.apps.googleusercontent.com, the kRedirectURI should be com.googleusercontent.apps.YOUR_CLIENT:/oauthredirect.
3. Update Info.plist: Open Info.plist, expand the "URL types" (CFBundleURLTypes) section, and replace the existing identifier with your Client ID's reverse DNS notation (do not include the :/oauthredirect path component).

// In GTMAppAuthExampleViewController.m

// 1. Set your Client ID
static NSString *const kClientID = @"YOUR_CLIENT_ID.apps.googleusercontent.com";

// 2. Set your Redirect URI (Reverse DNS + path)
static NSString *const kRedirectURI = @"com.googleusercontent.apps.YOUR_CLIENT_ID:/oauthredirect";

To use the example, you must provide a valid Google OAuth client ID.

1. Create a Client ID: Visit the Google Cloud Console, create a project, and create an OAuth client ID with the application type set to iOS.
2. Identify Bundle ID: Use your project's Bundle ID. For the default example, it is com.example.GTMAppAuth.Example-iOS. You can change this via PRODUCT_BUNDLE_IDENTIFIER in your configuration.
3. Calculate Redirect Values:
   • OIDC_CLIENT_ID: Your client ID (e.g., YOUR_CLIENT.apps.googleusercontent.com).
   • OIDC_REDIRECT_URI: The reverse DNS notation of your client ID with a path component. Example: If ID is YOUR_CLIENT.apps.googleusercontent.com, the URI is com.googleusercontent.apps.YOUR_CLIENT:/oauthredirect.
   • OIDC_REDIRECT_URI_SCHEME: The reverse DNS notation without the path component. Example: com.googleusercontent.apps.YOUR_CLIENT.

To initiate an authorization flow, follow these steps:

1. Store the session: Maintain a property (typically in your UIApplicationDelegate) of type id<OIDExternalUserAgentSession> to track the in-progress flow.
2. Store the auth state: Maintain a property (e.g., in your controller) of type GTMAuthSession to hold the resulting tokens.
3. Execute the request: Use [OIDAuthState authStateByPresentingAuthorizationRequest:callback:]. This method automatically performs the OAuth token exchange and uses PKCE if supported by the server.

In the callback, if authState is successful, initialize your GTMAuthSession with it.

// 1. Build the request
OIDAuthorizationRequest *request = [[OIDAuthorizationRequest alloc] initWithConfiguration:configuration
                                                                                 clientId:kClientID
                                                                             clientSecret:kClientSecret
                                                                                   scopes:@[OIDScopeOpenID, OIDScopeProfile]
                                                                              redirectURL:redirectURI
                                                                             responseType:OIDResponseTypeCode
                                                                   additionalParameters:nil];

// 2. Perform request and store the flow in your app delegate
self.appDelegate.currentAuthorizationFlow = [OIDAuthState authStateByPresentingAuthorizationRequest:request
    callback:^(OIDAuthState *_Nullable authState, NSError *_Nullable error) {
  if (authState) {
    // 3. Create GTMAuthSession from the state
    self.authSession = [[GTMAuthSession alloc] initWithAuthState:authState];
  } else {
    self.authSession = nil;
  }
}];