You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README-Phonegap.md
+21-3Lines changed: 21 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,39 @@
1
1
# Using JSO with Phonegap and ChildBrowser
2
2
3
+
4
+
**WARNING: JSO2 beta is not ready for integration with Phonegap and Childbrowser just yet. Stay tuned for updates on this. This document is old and documents integration with phonegap using JSO verson 1**
5
+
6
+
7
+
3
8
Using JSO to perform OAuth 2.0 authorization in WebApps running on mobile devices in hybrid environment is an important deployment scenario for JSO.
4
9
5
10
Here is a detailed instruction on setting up JSO with Phonegap for iOS and configure OAuth 2.0 with Google. You may use it with Facebook or other OAuth providers as well.
6
11
7
12
8
13
# Preparations
9
14
10
-
* Install XCode from App Store, and iOS development kit
**UPDATE March 20th 2013: I just commited [JSO version 2.0, a redesigned library](https://github.com/andreassolberg/jso/tree/version2). It is only in beta state yet, but feel free to test it.**
4
5
5
6
6
7
This library was written by Andreas Åkre Solberg (UNINETT AS) in March 2012.
8
+
=======
9
+
The initial version 1 of this library was written by Andreas Åkre Solberg (UNINETT AS) in March 2012. **This is the beta release of JSO2, and redesigned and not well-tested version of the same library.**[Return to the stable version 1 of JSO](https://github.com/andreassolberg/jso)
10
+
11
+
>>>>>>> version2
7
12
8
13
*[Read the blog of Andreas Åkre Solberg](http://rnd.feide.no)
9
14
*[Follow Andreas Åkre Solberg on twitter](https://twitter.com/erlang)
@@ -20,21 +25,32 @@ If you want to use JSO together with Phonegap to support OAuth 2.0 in a hybrid w
20
25
21
26
*[JSO Phonegap Guide](README-Phonegap.md)
22
27
28
+
## Contributors
29
+
30
+
*[Robbie MacKay](https://github.com/rjmackay)
31
+
23
32
24
33
## Licence
25
34
35
+
<<<<<<< HEAD
26
36
UNINETT holds the copyright of the JSO library. The software can be used free of charge for both non-commercial and commercial projects.
27
37
28
38
The software is dual-licenced with *The GNU Lesser General Public License, version 2.1 (LGPL-2.1)* and *version 3.0*; meaning that you can select which of these two versions depending on your needs.
29
39
30
40
*<http://opensource.org/licenses/lgpl-2.1>
31
41
*<http://opensource.org/licenses/LGPL-3.0>
42
+
=======
43
+
UNINETT holds the copyright of the JSO library. The software can be used free of charge for both non-commercial and commercial projects. The software is licenced with *Simplified BSD License*.
44
+
45
+
*<http://opensource.org/licenses/BSD-2-Clause>
46
+
>>>>>>> version2
32
47
33
48
34
49
## Features
35
50
36
-
* Implements OAuth 2.0 Implicit Flow. All you need is a single javascript file.
37
-
* Supports the `bearer` access token type.
51
+
* Implements OAuth 2.0 Implicit Flow.
52
+
* AMD Loading
53
+
* Supports the `Bearer` access token type.
38
54
* No server component needed.
39
55
* Adds a jQuery plugin extending the `$.ajax()` function with OAuth capabilities.
40
56
* Can handle multilple providers at once.
@@ -45,7 +61,8 @@ The software is dual-licenced with *The GNU Lesser General Public License, versi
45
61
46
62
## Dependencies
47
63
48
-
JSO makes use of jQuery, mostly to plugin and make use of the `$.ajax()` function. If there is an interest for making JSO independent from jQuery, I can do that.
64
+
JSO may make use of jQuery, mostly to plugin and make use of the `ajax()` function.
65
+
49
66
50
67
## Browser support
51
68
@@ -56,167 +73,83 @@ JSO uses JSON serialization functions (stringify and parse). These are supported
56
73
57
74
## Configure
58
75
59
-
First, you must configure your OAuth providers. You do that by calling `jso_configure` with a configuration object as a parameter.
60
76
61
-
The object is a key, value set of providers, where the providerID is an internal identifier of the provider that is used later, when doing protected calls.
77
+
First, load JSO with requirejs:
78
+
79
+
```javascript
80
+
var
81
+
JSO=require('bower_components/jso/build/jso'),
82
+
jQuery =require('jquery');
83
+
OAuth.enablejQuery($);
84
+
```
85
+
86
+
Loading jQuery is optional. If you load jQuery and want the `ajax()` function, you should run the enablejQuery function.
62
87
63
-
In this example, we set the provider identifier to be `facebook`.
88
+
Next is configuring an OAuth object with the configuration of an OAuth Provider.
*`client_id`: The client idenfier of your client that as trusted by the provider. As JSO uses the implicit grant flow, there is now use for a
77
104
*`redirect_uri`: OPTIONAL (may be needed by the provider). The URI that the user will be redirected back to when completed. This shuold be the same URL that the page is presented on.
78
105
*`presenttoken`: OPTIONAL How to present the token with the protected calls. Values can be `qs` (in query string) or `header` (default; in authorization header).
79
106
*`default_lifetime` : OPTIONAL Seconds with default lifetime of an access token. If set to `false`, it means permanent.
80
107
*`permanent_scope`: A scope that indicates that the lifetime of the access token is infinite. (not yet tested.)
81
108
*`isDefault`: Some OAuth providers does not support the `state` parameter. When this parameter is missing, the consumer does not which provider that is sending the access_token. If you only provide one provider config, or set isDefault to `true` for one of them, the consumer will assume this is the provider that sent the token.
82
109
*`scope`: For providers that does not support `state`: If state was not provided, and default provider contains a scope parameter we assume this is the one requested... Set this as the same list of scopes that you provide to `ensure_tokens`.
110
+
*`scopes.request`: Control what scopes are requested in the authorization request.
83
111
84
112
85
-
The second optional parameter, options, of `jso_configure(providerconfig, options)` allows you to configure these global settings:
86
-
87
-
*`debug`: Default value is `false`. If you enable debugging, JSO will log a bunch of things to the console, using `console.log` - if not, JSO will not log anything.
88
-
89
-
90
-
## Authorization
91
-
92
-
This OPTIONAL step involves an early ensurance that all neccessary access tokens have been retreived.
93
-
94
-
95
-
`jso_ensureTokens` can be used to force user authentication before you really need it; and the reason why you would typically do that is to make it easier to recover the state when you return. Typically if you need an OAuth token in the middle of a complex transaction it would be really difficult if the user is redirected away during that transaction, instead you can use `jso_ensureTokens` before starting with the transaction.
96
113
97
-
Using `jso_ensureTokens` is completely optional, and when you do not want to make sure that you have sufficient tokens before you really need it, then you can call `$.oajax` right away and it will redirect you for authenticationo - if needed.
114
+
## Callback
98
115
99
-
100
-
101
-
102
-
By doing a call like this early in your code:
116
+
At the endpoint where the OAuth provider is redirecting back the user with the access token response, you need to run the callback(). This allows JSO to collect and parse the response.
the library will check its cached tokens, and if it does not have the specified tokens/scopes, it will start a new authorization process.
113
-
114
-
When this code is completed, you know that you have valid tokens for your use cases.
122
+
Be aware to run the `callback()` function before your *router*, and before `o.getToken()` or `o.ajax()`.
115
123
116
-
The `jso_ensureTokens` function takes an object as input, with the providerids as keys, and the values are eigther `false` or an array of required scopes. A value of `false` mean that we do not care about scopes, but we want a valid token.
124
+
The redirect_uri may very well be the same page that initates the authorization request.
117
125
118
126
119
127
## OAuth protected data requests
120
128
121
-
To get data, you eigther use the `jso_getToken("facebook")` function, that returns a valid access token (or `null`), or you may use the `$.oajax()` function.
122
129
123
-
The `$.oajax()` function works very similar to `$.ajax()` ([see documentation](http://api.jquery.com/jQuery.ajax/)), actually the settings parameters are bypassed to the real `$.ajax()` function.
124
-
125
-
In addition to the settings properties allowed by `$.ajax()`, these properties are allowed:
126
-
127
-
* jso_provider: The providerid of the OAuth provider to use.
128
-
* jso_allowia: Allow userinteraction? If you have prepared the tokens, using `jso_ensureTokens()` you might set this value to `false` (default) and it will trow an exception instead of starting a new authorization process.
129
-
* jso_scopes: If this specific call requires one or more scopes, provide it here. It will be used to find a suitable token, if multiple exists.
130
-
131
-
Here is an example of retrieving the Facebook newsstream using OAuth:
130
+
You may use the `o.ajax()` function to perform OAuth protected API calls.
If you load jQuery before the JSO library, it will discover and add the `$.oajax` function. However, loading jQuery is optional, and if you do not load jQuery JSO will not complain, but neigther will if offer the easy to use `$.oajax` function.
150
-
151
-
If you do not use jQuery, you probably want to use the `jso_getToken(providerid, scopes)` function.
152
-
153
-
```javascript
154
-
var accesstoken =jso_getToken("facebook", "read_stream");
155
-
156
-
var authzheader ="Authorization: Authorization "+ accesstoken;
157
-
// Perform the Cross site AJAX request using this custom header with your
158
-
// preferred AJAX library.
159
-
```
160
-
161
-
162
-
163
-
## Using JSO With Phonegap
164
-
165
-
Normal use of JSO involves JSO redirecting to the OAuth authorization endpoint for authentication and authorization, then the user is redirected back to the callback url where JSO autoamtically inspects the hash for an access token, and caches it.
166
-
167
-
When using JSO with phonegap (or similar libraries), you would not perform a normal redirect, but instead open a *childbrowser*. And when the user returns you would need to tell JSO what URL the childbrowser ended up on.
168
-
169
-
170
-
**Register a custom URL redirect handler**
171
-
172
-
```javascript
173
-
jso_registerRedirectHandler(function(url) {
174
-
console.log("About to redirect the user to ", url);
175
-
console.log("Instead we can do whatever we want, such as opening a child browser");
176
-
177
-
// Open a child browser or similar.
178
-
});
179
-
```
180
-
*Please help! I have not used phonegap my self, and if someone could provide exact code examples for use with phonegap I would appreciate that.*
181
-
182
-
183
-
**Tell JSO about the return URL**
184
-
185
-
Use the following function providing the url of the callback page, including the parameters in the hash: `jso_checkfortoken(providerid, url)`
For debugging, open the javascript console. And you might type:
197
-
198
-
199
-
```javascript
200
-
jso_dump();
201
-
```
202
-
203
-
to list all cached tokens, and
204
-
205
-
```javascript
206
-
jso_wipe();
207
-
```
208
-
209
-
to remove all tokens.
210
-
211
-
212
-
213
-
## Upgrade
214
-
215
-
This section will contain useful information if you have been using JSO already, and would like to update to the latest version. API and configuration changes will be listed here.
216
-
217
-
218
-
150
+
`o.ajax()` wraps the `$.ajax()` function with one single additional optional option property `oauth`.
219
151
152
+
Currently, only the `scopes` property is included. It adds to the scopes property in the initial provider configuration.
0 commit comments