|
| 1 | +## Using the OAuth2Client |
| 2 | + |
| 3 | +### Create an instance of NXOAuth2Client |
| 4 | + |
| 5 | +To create an NXOAuth2Client instance you need OAuth2 credentials (client id & secret) and endpoints (authorize & |
| 6 | +token URL) for your application. You usually get them from the service you want to connect to. You also need to |
| 7 | +pass in an *delegate* which is discussed later. |
| 8 | + |
| 9 | +<pre> |
| 10 | + // client is a ivar |
| 11 | + client = [[NXOAuth2Client alloc] initWithClientID:@"xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx" |
| 12 | + clientSecret:@"xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx" |
| 13 | + authorizeURL:[NSURL URLWithString:@"https://myHost/oauth2/authenticate"] |
| 14 | + tokenURL:[NSURL URLWithString:@"https://myHost/oauth2/token"] |
| 15 | + delegate:self]; |
| 16 | +</pre> |
| 17 | + |
| 18 | +Once you got your instance of the client you can check if you already have a valid token. |
| 19 | + |
| 20 | +<pre> |
| 21 | + [client requestAccess]; |
| 22 | +</pre> |
| 23 | + |
| 24 | +This method triggers the authentication flow and will invoke one or more of the callback methods implemented in the clients delegate. |
| 25 | + |
| 26 | + |
| 27 | +### The Delegate |
| 28 | +<a name="TheDelegate"></a> |
| 29 | +The Authentication Delegate is the place to get callbacks on the status of authentication. It defines following methods: |
| 30 | + |
| 31 | +<pre> |
| 32 | +@required |
| 33 | + - (void)oauthClientNeedsAuthentication:(NXOAuth2Client *)client; |
| 34 | + |
| 35 | +@optional |
| 36 | + - (void)oauthClientDidGetAccessToken:(NXOAuth2Client *)client; |
| 37 | + - (void)oauthClientDidLoseAccessToken:(NXOAuth2Client *)client; |
| 38 | + - (void)oauthClient:(NXOAuth2Client *)client didFailToGetAccessTokenWithError:(NSError *)error; |
| 39 | +</pre> |
| 40 | + |
| 41 | +#### The optional delegate methods |
| 42 | + |
| 43 | +The first three delegate methods inform you when authentication is gained or lost, as well as when an error occurred during the process. |
| 44 | +`-oauthClientDidGetAccessToken:` for example is called when the authorization flow finishes with an access token or when your app was |
| 45 | +authorized in a previous session and the access token has been found in the keychain. |
| 46 | + |
| 47 | +`-oauthClientDidLoseAccessToken:` is called whenever the token is lost. This might be the case when the token expires and there has been |
| 48 | +an error refreshing it, or when the user revokes access on the service your connecting to. |
| 49 | + |
| 50 | +`-oauthClient:didFailToGetAccessTokenWithError:` returns the error that prevented the client from getting a valid access token. See the |
| 51 | +constants header file (`NXOAuth2Constants.h`) and the [section about errors](http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-3.2.1) |
| 52 | +in the OAuth2 spec for more information which errors to expect. Besides errors in the `NXOAuth2ErrorDomain` you should also handle NSURL errors |
| 53 | +in the `NSURLErrorDomain`. |
| 54 | + |
| 55 | +#### The required delegate method |
| 56 | + |
| 57 | +The fourth method needs to be implemented by your app and is responsible for choosing the OAuth2 authorization flow. The wrapper supports |
| 58 | +the user-agent & the user credentials flow of OAuth2 draft 10. The following two sections show you example implementations for both type of flows. |
| 59 | + |
| 60 | + |
| 61 | +##### User-agent flow |
| 62 | + |
| 63 | +In the user-agent flow your app opens an internal user-agent (an embedded web view) or an external user-agent (the default browser) to open a |
| 64 | +site on the service your connecting to. The user enters his credentials and is redirected to an URL you define. This URL should open your |
| 65 | +application or should be intercepted if you're using an internal web view. Pass this URL to the `-authorizationURLWithRedirectURL:` method |
| 66 | +of your NXOAuth2Client instance, and it will get the access token out of it. |
| 67 | + |
| 68 | +<pre> |
| 69 | +- (void)oauthClientRequestedAuthorization:(NXOAuth2Client *)aClient; |
| 70 | +{ |
| 71 | + // webserver flow |
| 72 | + |
| 73 | + // this is your redirect url. register it with your app |
| 74 | + NSURL *authorizationURL = [client authorizationURLWithRedirectURL:[NSURL URLWithString:@"x-myapp://oauth2"]]; |
| 75 | + #if TARGET_OS_IPHONE |
| 76 | + [[UIApplication sharedApplication] openURL:authorizationURL]; // this line quits the application or puts it to the background, be prepared |
| 77 | + #else |
| 78 | + [[NSWorkspace sharedWorkspace] openURL:authorizationURL]; |
| 79 | + #endif |
| 80 | +} |
| 81 | +</pre> |
| 82 | + |
| 83 | +##### User credentials flow |
| 84 | + |
| 85 | +The user credentials flow allows your app do present the user a custom login form. Please consider that this flow is *generally discouraged* |
| 86 | +since the user has to enter his credentials in an untrusted environment and can't control what your app does with the entrusted credentials. |
| 87 | + |
| 88 | +<pre> |
| 89 | +- (void)oauthClientRequestedAuthorization:(NXOAuth2Client *)aClient; |
| 90 | +{ |
| 91 | + // user credentials flow |
| 92 | + [client authorizeWithUsername:username password:password]; |
| 93 | + // you probably don't yet have username & password. |
| 94 | + // if so, open a view to query them from the user & call this method with the results asynchronously. |
| 95 | +} |
| 96 | +</pre> |
| 97 | + |
| 98 | +### Sending requests |
| 99 | + |
| 100 | +Create your request as usual but don't use NSURLConnection but `NXOAuth2Connection`. It has a similar delegate protocol but signs the request |
| 101 | +when an `NXOAuth2Client` is passed in. If you don't pass in the client but nil, the connection will work standalone but not sign any request. Make |
| 102 | +sure to retain the connection for as long as it's running. The best place for doing so is it's delegate. You can also cancel the connection if |
| 103 | +the delegate is deallocated. |
| 104 | + |
| 105 | +<pre> |
| 106 | + NSURLRequest *request = [NSURLRequest requestWithURL:[NSURL URLWithString:@"https://myHost/someResource"]]; |
| 107 | + // retain the connection for as long as it's running. |
| 108 | + NXOAuth2Connection *connection = [[NXOAuth2Connection alloc] initWithRequest:request oauthClient:aClient delegate:self]; |
| 109 | +</pre> |
0 commit comments