Skip to content

Commit 06393a7

Browse files
auserauser
committed
Updated
1 parent 87b3f36 commit 06393a7

16 files changed

+426
-60
lines changed

‎README.md

+156-47
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ manager.authorize('google', {scopes: 'profile email'})
3030

3131
* Isolates the OAuth experience to a few simple methods.
3232
* Atomatically stores the tokens for later retrieval
33-
* Works with many providers and relatively simple to add a provider
33+
* Works with many providers and relatively simple to add a new provider
3434

3535
## Installation
3636

@@ -49,55 +49,62 @@ As we are integrating with react-native, we have a little more setup to integrat
4949
To automatically link our `react-native-oauth` client to our application, use the `rnpm` tool. [rnpm](https://github.com/rnpm/rnpm) is a React Native package manager which can help to automate the process of linking package environments.
5050

5151
```bash
52-
rnpm link
52+
react-native link react-native-oauth
5353
```
5454

55-
#### Manually
55+
Note: due to some restrictions on iOS, this module requires you to install cocoapods. The process has been semi-automated through using the above `react-native link` command. Once you have linked this library, run: `pod install` and then open the created `.xcworkspace` when it's complete.
5656

57-
If you prefer not to use `rnpm`, we can manually link the package together with the following steps, after `npm install`:
57+
### Android setup
5858

59-
1. In XCode, right click on `Libraries` and find the `Add Files to [project name]`.
59+
Coming soon (looking for contributors).
6060

61-
![Add library to project](http://d.pr/i/2gEH.png)
61+
## Handle deep linking loading
6262

63-
2. Add the `node_modules/react-native-oauth/ios/OAuthManager.xcodeproj`
63+
**Required step**
6464

65-
![OAuthManager.xcodeproj in Libraries listing](http://d.pr/i/19ktP.png)
65+
We'll need to handle app loading from a url with our app in order to handle authentication from other providers. That is, we'll need to make sure our app knows about the credentials we're authenticating our users against when the app loads _after_ a provider is authenticated against.
6666

67-
3. In the project's "Build Settings" tab in your app's target, add `libOAuthManager.a` to the list of `Link Binary with Libraries`
67+
### iOS setup
6868

69-
![Linking binaries](http://d.pr/i/1cHgs.png)
69+
We need to add a callback method in our `ios/AppDelegate.m` file and then call our OAuthManager helper method. Let's load the `ios/AppDelegate.m` file and add the following all the way at the bottom (but before the `@end`):
7070

71-
4. Ensure that the `Build Settings` of the `OAuthManager.xcodeproj` project is ticked to _All_ and it's `Header Search Paths` include both of the following paths _and_ are set to _recursive_:
71+
```objectivec
72+
// Add the import at the top:
73+
#import "OAuthManager.h"
74+
// ...
75+
@implementation AppDelegate
76+
// ...
77+
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
78+
return [OAuthManager handleOpenUrl:application
79+
openURL:url
80+
sourceApplication:sourceApplication
81+
annotation:annotation];
82+
}
83+
```
7284
73-
1. `$(SRCROOT)/../../react-native/React`
74-
2. `$(SRCROOT)/../node_modules/react-native/React`
85+
When our app loads up with a request that is coming back from OAuthManager _and_ matches the url pattern, OAuthManager will take over and handle the rest and storing the credentials for later use.
7586
76-
![Recursive paths](http://d.pr/i/1hAr1.png)
87+
### Adding URL schemes
7788
78-
### Android setup
89+
In order for our app to load through these callbacks, we need to tell our iOS app that we want to load them. In order to do that, we'll have to create some URL schemes to register our app. Some providers require specific schemes (mentioned later).
7990
80-
Coming soon (looking for contributors).
91+
These URL schemes can be added by navigating to to the `info` panel of our app in Xcode (see screenshot).
8192
82-
## Handle deep linking loading
93+
![](./resources/info-panel.png)
8394
84-
**Required step**
95+
Let's add the appropriate one for our provider. For instance, to set up twitter, add the app name as a URL scheme in the URL scheme box.
8596
86-
We'll need to handle app loading from a url with our app in order to handle authentication from other providers. That is, we'll need to make sure our app knows about the credentials we're authenticating our users against when the app loads _after_ a provider is authenticated against.
97+
![](./resources/url-schemes.png)
8798
88-
### iOS setup
99+
## Creating the manager
89100
90-
We need to add a callback method in our `ios/AppDelegate.m` file and then call our OAuthManager helper method. Let's load the `ios/AppDelegate.m` file and add the following all the way at the bottom (but before the `@end`):
101+
In our JS, we can create the manager by instantiating a new instance of it using the `new` method and passing it the name of our app:
91102
92-
```objectivec
93-
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
94-
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
95-
{
96-
return [OAuthManager handleOpenUrl:application openURL:url sourceApplication:sourceApplication annotation:annotation];
97-
}
103+
```javascript
104+
const manager = new OAuthManager('firestackexample')
98105
```
99106

100-
When our app loads up with a request that is coming back from OAuthManager _and_ matches the pattern of `[app-name]://oauth-callback/{providerName}`, the OAuthManager will take over and handle the rest and storing the credentials for later use.
107+
We need to pass the name of our app as the oauth manager uses this to create callback keys. This _must_ match the URL route created in your iOS app. For instance, above we created a URL scheme for Twitter. Pass this as the string in the `OAuthManager` constructor.
101108

102109
## Configuring our providers
103110

@@ -115,9 +122,16 @@ const config = {
115122
twitter: {
116123
consumer_key: 'SOME_CONSUMER_KEY',
117124
consumer_secret: 'SOME_CONSUMER_SECRET'
125+
},
126+
facebook: {
127+
client_id: 'YOUR_CLIENT_ID',
128+
client_Secret: 'YOUR_CLIENT_SECRET'
118129
}
119130
}
120-
authManager.configureProvider("twitter", config.twitter);
131+
// Create the manager
132+
const manager = new OAuthManager('firestackexample')
133+
// configure the manager
134+
manager.configure(config);
121135
```
122136

123137
The `consumer_key` and `consumer_secret` values are _generally_ provided by the provider development program. In the case of [twitter](https://apps.twitter.com), we can create an app and generate these values through their [development dashboard](https://apps.twitter.com).
@@ -126,32 +140,127 @@ The `consumer_key` and `consumer_secret` values are _generally_ provided by the
126140

127141
The following list are the providers we've implemented thus far in `react-native-oauth` and the _required_ keys to pass when configuring the provider:
128142

129-
* Twitter
130-
* consumer_key
131-
* consumer_secret
132-
* Facebook (not fully implemented)
133-
* consumer_key
134-
* consumer_secret
143+
#### Twitter
144+
145+
To authenticate against twitter, we need to register a Twitter application. Register your twitter application (or create a new one at [apps.twitter.com](https://apps.twitter.com)).
146+
147+
![](./resources/twitter/app.png)
148+
149+
Once you have created one, navigate to the application and find the `Keys and Access Tokens`. Take note of the consumer key and secret:
150+
151+
![](./resources/twitter/api-key.png)
152+
153+
Twitter's URL scheme needs to be the app name (that we pass into the constructor method). Make sure we have one registered in Xcode as the same name:
154+
155+
![](./resources/twitter/url-scheme.png)
156+
157+
Add these values to the authorization configuration to pass to the `configure()` method as:
158+
159+
```javascript
160+
const config = {
161+
twitter: {
162+
consumer_key: 'SOME_CONSUMER_KEY',
163+
consumer_secret: 'SOME_CONSUMER_SECRET'
164+
}
165+
}
166+
```
167+
168+
#### Facebook
169+
170+
To add facebook authentication, we'll need to have a Facebook app. To create one (or use an existing one), navigate to [developers.facebook.com/](https://developers.facebook.com/).
171+
172+
![](./resources/facebook/dev.facebook.png)
173+
174+
Find or create an application and find the app id. Take note of this app id. Next, navigate to the `Settings` panel and find your client_secret.
175+
176+
![](./resources/facebook/app.png)
177+
178+
Before we leave the Facebook settings, we need to tell Facebook we have a new redirect url to register. Navigate to the bottom of the page and add the following into the `bundle ID` field:
179+
180+
`fb{YOUR_APP_ID}`
181+
182+
For instance, my app ID in this example is: `1745641015707619`. In the `Bundle ID` field, I have added `fb1745641015707619`.
183+
184+
![](./resources/facebook/redirect-url.png)
185+
186+
We'll need to create a new URL scheme for Facebook and (this is a weird bug on the Facebook side) the facebook redirect URL scheme _must be the first one_ in the list. The URL scheme needs to be the same id as the `Bundle ID` copied from above:
187+
188+
![](./resources/facebook/url-scheme.png)
189+
190+
Back in our application, add the App ID and the secret as:
191+
192+
```javascript
193+
const config = {
194+
facebook: {
195+
client_id: 'YOUR_APP_ID',
196+
client_secret: 'YOUR_APP_SECRET'
197+
}
198+
}
199+
```
200+
201+
#### Google
202+
203+
To add Google auth to our application, first we'll need to create a google application. Create or use an existing one by heading to the [developers.google.com/](https://developers.google.com/) page (or the console directly at [https://console.developers.google.com](https://console.developers.google.com)).
204+
205+
![](./resources/google/auth-page.png)
206+
207+
We need to enable the `Identity Toolkit API` API. Click on `Enable API` and add this api to your app. Once it's enabled, we'll need to collect our credentials.
208+
209+
Navigate to the `Credentials` tab and create a new credential. Create a web API credential. Take note of the client id and the URL scheme. In addition, make sure to set the bundle ID as the bundle id in our application in Xcode:
210+
211+
![](./resources/google/creds.png)
212+
213+
Take note of the `iOS URL Scheme`. We'll need to add this as a URL scheme in our app. In the `Info` panel of our app target (in Xcode), add the URL scheme:
214+
215+
![](./resources/google/url-scheme.png)
216+
217+
Finally, add the `client_id` credential as the id from the url page as well as the ios scheme (with any path) in our app configuration:
218+
219+
```javascript
220+
const config = {
221+
google: {
222+
callback_url: `[IOS SCHEME]:/google`,
223+
client_id: 'YOUR_CLIENT_ID'
224+
}
225+
}
226+
```
135227

136228
## Authenticating against our providers
137229

138-
In order to make any authenticated calls against a provider, we need to authenticate against it. The `react-native-oauth` library passes through an easy method for dealing with authentication with the `authorizeWithCallbackURL()` method.
139230

140-
Using the app uri we previous setup, we can call the `authorizeWithCallbackURL()` method to ask iOS to redirect our user to a browser where they can log in to our app in the usual flow. When the user authorizes the login request, the promise returned by the `authorizeWithCallbackURL()` is resolved. If they reject the login request for any reason, the promise is rejected along with an error, if there are any.
231+
We can use the manager in our app using the `authorize()` method on the manager.
232+
233+
The `authorize` method takes two arguments (the first one is required):
234+
235+
* The provider we wish to authenticate against (i.e. twitter, facebook)
236+
* The list of options on a per-provider basis (optional)
237+
238+
For example:
141239

142240
```javascript
143-
authManager.authorizeWithCallbackURL('twitter', 'firebase-example://oauth-callback/twitter')
144-
.then((oauthResponse) => {
145-
// the oauthResponse object is the response returned by the request
146-
// which is later stored by react-native-oauth using AsyncStorage
147-
})
148-
.catch((err) => {
149-
// err is an error object that contains the reason the user
150-
// error rejected authentication.
151-
})
241+
manager.authorize('twitter')
242+
.then(resp => console.log(resp))
243+
.catch(err => console.log(err));
152244
```
153245

154-
When the response is returned, `react-native-oauth` will store the resulting credentials using the `AsyncStorage` object provided natively by React Native. All of this happens behinds the scenes _automatically_. When the credentials are successfully rerequested, `AsyncStorage` is updated behind the scenes automatically. All you have to do is take care of authenticating the user using the `authorizeWithCallbackURL()` method.
246+
This method returns a promise that is resolved once the authentication has been completed. You'll get access to the authentication keys in the `resp` object.
247+
248+
The `resp` object is set as follows:
249+
250+
```javascript
251+
{
252+
status: "ok",
253+
response: {
254+
authorized: true, (boolean)
255+
uuid: "UUID", (user UUID)
256+
credentials: {
257+
access_token: "access token",
258+
refresh_token: "refresh token",
259+
type: 1
260+
}
261+
}
262+
}
263+
```
155264

156265
## Calling a provider's API
157266

0 commit comments

Comments
 (0)