My favorites | Sign in
Project Home Downloads Wiki Issues Source
Checkout   Browse   Changes  
Changes to /wiki/OAuthSignInControllers.wiki
r555 vs. r628 Compare: vs.  Format:
Revision r628
Go to: 
Project members, sign in to write a code review
/wiki/OAuthSignInControllers.wiki   r555 /wiki/OAuthSignInControllers.wiki   r628
1 #summary OAuth Controllers for iPhone and Mac Apps 1 #summary OAuth Controllers for iPhone and Mac Apps
2 #labels Featured 2 #labels Featured
3 3
4 = Using the OAuth Controllers = 4 = Using the OAuth Controllers =
5 5
6 <wiki:toc max_depth="3" /> 6 <wiki:toc max_depth="3" />
7 7
8 == Introduction == 8 == Introduction ==
9 9
10 [http://oauth.net/ OAuth] is a protocol allowing your application to obtain authorization to read or modify a user’s files or data on an external server. 10 [http://oauth.net/ OAuth] is a protocol allowing your application to obtain authorization to read or modify a user's files or data on an external server.
11 11
12 The server generates a web page for the user to sign in with her name and password, including a button explicitly granting access to some of her data. Upon successful authentication, the server gives tokens to your application representing the user's authorization. 12 The server generates a web page for the user to sign in with her name and password, including a button explicitly granting access to some of her data. Upon successful authentication, the server gives tokens to your application representing the user's authorization.
13 13
14 With the Objective-C OAuth controllers, the web page can be presented as an iPhone view or a Mac sheet within your application. The controllers also provide authentication objects that simplify your application's future requests for the user's data. 14 With the Objective-C OAuth controllers, the web page can be presented as an iPhone view or a Mac sheet within your application. The controllers also provide authentication objects that simplify your application's future requests for the user's data.
15 15
16 == Using the iPhone and Mac OAuth Controllers == 16 == Using the iPhone and Mac OAuth Controllers ==
17 17
18 The OAuth controllers are part of the Google Data APIs Objective-C Client Library, but you can easily use them independent of the library as well. You can also use them for authenticating via OAuth to servers and services other than Google's. 18 The OAuth controllers are part of the Google Data APIs Objective-C Client Library, but you can easily use them independent of the library as well. You can also use them for authenticating via OAuth to servers and services other than Google's.
19 19
20 There are example iPhone and Mac applications using the OAuth controllers in the library's [http://code.google.com/p/gdata-objectivec-client/source/browse/#svn/trunk/Examples Examples directory]. 20 There are example iPhone and Mac applications using the OAuth controllers in the library's [http://code.google.com/p/gdata-objectivec-client/source/browse/#svn/trunk/Examples Examples directory].
21 21
22 For iPhone developers, there is also a project for building a static library, called GDataOAuthTouchStaticLibrary.xcodeproj 22 For iPhone developers, there is also a project for building a static library, called GDataOAuthTouchStaticLibrary.xcodeproj
23 23
24 The source files required are: 24 The source files required are:
25 25
26 ||_iPhone and Mac_||_iPhone_||_Mac_|| 26 ||_iPhone and Mac_||_iPhone_||_Mac_||
27 ||GDataOAuthAuthentication.h/m<br>GDataOAuthSignIn.h/m<br>GDataHTTPFetcher.h/m||GDataOAuthViewControllerTouch.h/m<br>GDataOAuthViewTouch.xib (optional)||GDataOAuthWindowController.h/m<br>GDataOAuthWindow.xib|| 27 ||GDataOAuthAuthentication.h/m<br>GDataOAuthSignIn.h/m<br>GDataHTTPFetcher.h/m||GDataOAuthViewControllerTouch.h/m<br>GDataOAuthViewTouch.xib (optional)||GDataOAuthWindowController.h/m<br>GDataOAuthWindow.xib||
28 28
29 These source files are in the OAuth and Networking groups of the library's [http://code.google.com/p/gdata-objectivec-client/source/browse/#svn/trunk/Source/ Source directory]. 29 These source files are in the OAuth and Networking groups of the library's [http://code.google.com/p/gdata-objectivec-client/source/browse/#svn/trunk/Source/ Source directory].
30 30
31 *Note*: Because the OAuth classes were developed recently and are still being refined for compatibility with multiple services, applications should use the OAuth classes from the top-of-trunk sources, not from the 1.10 library release. 31 *Note*: Because the OAuth classes were developed recently and are still being refined for compatibility with multiple services, applications should use the OAuth classes from the top-of-trunk sources, not from the 1.10 library release.
32 32
33 === System Requirements === 33 === System Requirements ===
34 34
35 The Mac controller is compatible with Mac OS X 10.5 and later. The iPhone controller is compatible with iPhone OS 2 and later. 35 The Mac controller is compatible with Mac OS X 10.5 and later. The iPhone controller is compatible with iPhone OS 2 and later.
36 36
37 The OAuth controllers require linking to the system frameworks Security.framework and SystemConfiguration.framework. 37 The OAuth controllers require linking to the system frameworks Security.framework and SystemConfiguration.framework.
38 38
39 === Signing In === 39 === Signing In ===
40 40
41 To display a sign-in view, your iPhone application makes these calls to push the view: 41 To display a sign-in view, your iPhone application makes these calls to push the view:
42 {{{ 42 {{{
43 #import "GDataOAuthViewControllerTouch.h" 43 #import "GDataOAuthViewControllerTouch.h"
44 44
45 static NSString *const kAppServiceName = @”My Application: Google Contacts”; 45 static NSString *const kAppServiceName = @”My Application: Google Contacts”;
46 46
47 NSString *scope = @"http://www.google.com/m8/feeds/"; // scope for Google Contacts API 47 NSString *scope = @"http://www.google.com/m8/feeds/"; // scope for Google Contacts API
48 48
49 GDataOAuthViewControllerTouch *viewController; 49 GDataOAuthViewControllerTouch *viewController;
50 viewController = [[[GDataOAuthViewControllerTouch alloc] initWithScope:scope 50 viewController = [[[GDataOAuthViewControllerTouch alloc] initWithScope:scope
51 language:nil 51 language:nil
52 appServiceName:kAppServiceName 52 appServiceName:kAppServiceName
53 delegate:self 53 delegate:self
54 finishedSelector:@selector(viewController:finishedWithAuth:error:)] autorelease]; 54 finishedSelector:@selector(viewController:finishedWithAuth:error:)] autorelease];
55 55
56 [[self navigationController] pushViewController:viewController animated:YES]; 56 [[self navigationController] pushViewController:viewController animated:YES];
57 }}} 57 }}}
58 58
59 A Mac application would display sign-in as a sheet on the current window, like this: 59 A Mac application would display sign-in as a sheet on the current window, like this:
60 60
61 {{{ 61 {{{
62 #import "GDataOAuthWindowController.h" 62 #import "GDataOAuthWindowController.h"
63 63
64 GDataOAuthWindowController *windowController; 64 GDataOAuthWindowController *windowController;
65 windowController = [[[GDataOAuthWindowController alloc] initWithScope:scope 65 windowController = [[[GDataOAuthWindowController alloc] initWithScope:scope
66 language:nil 66 language:nil
67 appServiceName:kAppServiceName 67 appServiceName:kAppServiceName
68 resourceBundle:nil] autorelease]; 68 resourceBundle:nil] autorelease];
69 [windowController signInSheetModalForWindow:currentWindow 69 [windowController signInSheetModalForWindow:currentWindow
70 delegate:self 70 delegate:self
71 finishedSelector:@selector(windowController:finishedWithAuth:error:)]; 71 finishedSelector:@selector(windowController:finishedWithAuth:error:)];
72 }}} 72 }}}
73 The *scope* is a string identifying what access is being requested. For access to more than one scope, separate the scopes with a space. 73 The *scope* is a string identifying what access is being requested. For access to more than one scope, separate the scopes with a space.
74 74
75 If your application uses the Google Data APIs Objective-C Client Library, it should get scopes from the service classes. For example, the scope of the Contacts API shown above is available as 75 If your application uses the Google Data APIs Objective-C Client Library, it should get scopes from the service classes. For example, the scope of the Contacts API shown above is available as
76 {{{ 76 {{{
77 scope = [GDataServiceGoogleContacts authorizationScope]; 77 scope = [GDataServiceGoogleContacts authorizationScope];
78 }}} 78 }}}
79 79
80 The *application service name* is used to save the token on the user’s keychain, and should identify both your application name and the service name(s). If appServiceName is nil, the token will not be saved, and the user will have to sign in again the next time the application is run. 80 The *application service name* is used to save the token on the user’s keychain, and should identify both your application name and the service name(s). If appServiceName is nil, the token will not be saved, and the user will have to sign in again the next time the application is run.
81 81
82 When the user signs in successfully or cancels signing in, the view or window controller will invoke your finishedSelector’s method: 82 When the user signs in successfully or cancels signing in, the view or window controller will invoke your finishedSelector’s method:
83 {{{ 83 {{{
84 - (void)viewController:(GDataOAuthViewControllerTouch *)viewController 84 - (void)viewController:(GDataOAuthViewControllerTouch *)viewController
85 finishedWithAuth:(GDataOAuthAuthentication *)auth 85 finishedWithAuth:(GDataOAuthAuthentication *)auth
86 error:(NSError *)error { 86 error:(NSError *)error {
87 if (error != nil) { 87 if (error != nil) {
88 // Authentication failed 88 // Authentication failed
89 } else { 89 } else {
90 // Authentication succeeded 90 // Authentication succeeded
91 } 91 }
92 } 92 }
93 }}} 93 }}}
94 94
95 If `[error code]` is kGDataOAuthErrorWindowClosed (-1000), then the user closed the sign-in view before completing authorization. Otherwise, any error reflects the server response in validating the user's access. 95 If `[error code]` is kGDataOAuthErrorWindowClosed (-1000), then the user closed the sign-in view before completing authorization. Otherwise, any error reflects the server response in validating the user's access.
96 96
97 === Using the Authentication Tokens === 97 === Using the Authentication Tokens ===
98 98
99 If authentication succeeds, your application should retain the authentication object. It can be either stored into a library service object to authorize future API requests: 99 If authentication succeeds, your application should retain the authentication object. It can be either stored into a library service object to authorize future API requests:
100 100
101 {{{ 101 {{{
102 [[self contactService] setAuthorizer:auth]; 102 [[self contactService] setAuthorizer:auth];
103 }}} 103 }}}
104 104
105 or used directly to authorize NSMutableURLRequest objects: 105 or used directly to authorize NSMutableURLRequest objects:
106 106
107 {{{ 107 {{{
108 [auth authorizeRequest:myNSURLMutableRequest] 108 [auth authorizeRequest:myNSURLMutableRequest]
109 }}} 109 }}}
110 110
111 === Retrieving Authorization from the Keychain === 111 === Retrieving Authorization from the Keychain ===
112 112
113 If your application saves the authorization to the keychain (by setting the controller's appServiceName), it can be retrieved the next time the application launches: 113 If your application saves the authorization to the keychain (by setting the controller's appServiceName), it can be retrieved the next time the application launches:
114 114
115 {{{ 115 {{{
116 GDataOAuthAuthentication *auth; 116 GDataOAuthAuthentication *auth;
117 auth = [GDataOAuthViewControllerTouch authForGoogleFromKeychainForName:kAppServiceName]; 117 auth = [GDataOAuthViewControllerTouch authForGoogleFromKeychainForName:kAppServiceName];
118 }}} 118 }}}
119 119
120 If no authorization was saved, then “auth” will still be a valid authorization object but will be unable to authorize requests: 120 If no authorization was saved, then “auth” will still be a valid authorization object but will be unable to authorize requests:
121 121
122 {{{ 122 {{{
123 BOOL isSignedIn = [auth canAuthorize]; // returns NO if auth cannot authorize requests 123 BOOL isSignedIn = [auth canAuthorize]; // returns NO if auth cannot authorize requests
124 }}} 124 }}}
125 125
126 === Signing Out === 126 === Signing Out ===
127 127
128 To completely discard the user’s authorization, use the view or window controller calls to remove the keychain entry and to ask the Google server to revoke the token: 128 To completely discard the user’s authorization, use the view or window controller calls to remove the keychain entry and to ask the Google server to revoke the token:
129 {{{ 129 {{{
130 [GDataOAuthViewControllerTouch removeParamsFromKeychainForName:kAppServiceName]; 130 [GDataOAuthViewControllerTouch removeParamsFromKeychainForName:kAppServiceName];
131 131
132 [GDataOAuthViewControllerTouch revokeTokenForGoogleAuthentication:auth]; 132 [GDataOAuthViewControllerTouch revokeTokenForGoogleAuthentication:auth];
133 }}} 133 }}}
134 134
135 Finally, release the authorization object. 135 Finally, release the authorization object.
136 136
137 == More Information == 137 == More Information ==
138 138
139 You can learn more about the OAuth protocol for desktop and mobile applications at [http://code.google.com/apis/accounts/docs/OAuthForInstalledApps.html Google's documentation]. 139 You can learn more about the OAuth protocol for desktop and mobile applications at [http://code.google.com/apis/accounts/docs/OAuthForInstalledApps.html Google's documentation].
Powered by Google Project Hosting