1 | # Simple OAuth2
|
2 |
|
3 | Node.js client library for [Oauth2](http://oauth.net/2/).
|
4 |
|
5 | OAuth2 lets users grant the access to the desired resources to third party applications,
|
6 | giving them the possibility to enable and disable those accesses whenever they want.
|
7 |
|
8 | Simple OAuth2 supports the following flows.
|
9 |
|
10 | * Authorization Code Flow (for apps with servers that can store persistent information).
|
11 | * Password Credentials (when previous flow can't be used or during development).
|
12 |
|
13 | ## Requirements
|
14 |
|
15 | Node client library is tested against Node ~0.8.x
|
16 |
|
17 |
|
18 | ## Installation
|
19 |
|
20 | Install the client library using [npm](http://npmjs.org/):
|
21 |
|
22 | $ npm install simple-oauth2
|
23 |
|
24 | Install the client library using git:
|
25 |
|
26 | $ git clone git://github.com/andrearegianto/simple-oauth2.git
|
27 | $ cd simple-oauth2
|
28 | $ npm install
|
29 |
|
30 |
|
31 | ## Getting started
|
32 |
|
33 | ### Authorization Code flow
|
34 |
|
35 | The Authorization Code flow is made up from two parts. At first your application asks to
|
36 | the user the permission to access their data. If the user approves the OAuth2 server sends
|
37 | to the client an authorization code. In the second part, the client POST the authorization code
|
38 | along with its client secret to the Lelylan in order to get the access token.
|
39 |
|
40 | ```javascript
|
41 | // Set the client credentials and the OAuth2 server
|
42 | var credentials = {
|
43 | clientID: '<client-id>',
|
44 | clientSecret: '<client-secret>',
|
45 | site: 'https://api.oauth.com'
|
46 | };
|
47 |
|
48 | // Initialize the OAuth2 Library
|
49 | var OAuth2 = require('simple-oauth2')(credentials);
|
50 |
|
51 | // Authorization OAuth2 URI
|
52 | var authorization_uri = OAuth2.AuthCode.authorizeURL({
|
53 | redirect_uri: 'http://localhost:3000/callback',
|
54 | scope: '<scope>',
|
55 | state: '<state>'
|
56 | });
|
57 |
|
58 | // Redirect example using Express (see http://expressjs.com/api.html#res.redirect)
|
59 | res.redirect(authorization_uri);
|
60 |
|
61 | // Get the access token object (the authorization code is given from the previous step).
|
62 | var token;
|
63 | OAuth2.AuthCode.getToken({
|
64 | code: '<code>',
|
65 | redirect_uri: 'http://localhost:3000/callback'
|
66 | }, saveToken);
|
67 |
|
68 | // Save the access token
|
69 | function saveToken(error, result) {
|
70 | if (error) { console.log('Access Token Error', error.message); }
|
71 | token = OAuth2.AccessToken.create(result);
|
72 | });
|
73 | ```
|
74 |
|
75 |
|
76 | ### Password Credentials Flow
|
77 |
|
78 | This flow is suitable when the resource owner has a trust relationship with the
|
79 | client, such as its computer operating system or a highly privileged application.
|
80 | Use this flow only when other flows are not viable or when you need a fast way to
|
81 | test your application.
|
82 |
|
83 | ```javascript
|
84 | // Get the access token object.
|
85 | var token;
|
86 | OAuth2.Password.getToken({
|
87 | username: 'username',
|
88 | password: 'password'
|
89 | }, saveToken);
|
90 |
|
91 | // Save the access token
|
92 | function saveToken(error, result) {
|
93 | if (error) { console.log('Access Token Error', error.message); }
|
94 | token = OAuth2.AccessToken.create(result);
|
95 | });
|
96 | ```
|
97 |
|
98 | ### Access Token object
|
99 |
|
100 | When a token expires we need to refresh it. Simple OAuth2 offers the
|
101 | AccessToken class that add a couple of useful methods to refresh the
|
102 | access token when it is expired.
|
103 |
|
104 | ```javascript
|
105 | // Sample of a JSON access token (you got it through previous steps)
|
106 | var token = {
|
107 | 'access_token': '<access-token>',
|
108 | 'refresh_token': '<refresh-token>',
|
109 | 'expires_in': '7200'
|
110 | };
|
111 |
|
112 | // Create the access token wrapper
|
113 | var token = OAuth2.AccessToken.create(token);
|
114 |
|
115 | // Check if the token is expired. If expired it is refreshed.
|
116 | if (token.expired()) {
|
117 | token.refresh(function(error, result) {
|
118 | token = result;
|
119 | })
|
120 | }
|
121 | ```
|
122 |
|
123 |
|
124 | ### Errors
|
125 |
|
126 | Exceptions are raised when a 4xx or 5xx status code is returned.
|
127 |
|
128 | HTTPError
|
129 |
|
130 | Through the error message attribute you can access the JSON representation
|
131 | based on HTTP `status` and error `message`.
|
132 |
|
133 | ```javascript
|
134 | OAuth2.AuthCode.getToken(function(error, token) {
|
135 | if (error) { console.log(error.message); }
|
136 | });
|
137 | // => { "status": "401", "message": "Unauthorized" }
|
138 | ```
|
139 |
|
140 |
|
141 | ### Configurations
|
142 |
|
143 | Simple OAuth2 accepts an object with the following valid params.
|
144 |
|
145 | * `clientID` - Required registered Client ID.
|
146 | * `clientSecret` - Required registered Client secret.
|
147 | * `site` - Required OAuth2 server site.
|
148 | * `authorizationPath` - Authorization path for the OAuth2 server.
|
149 | Simple OAuth2 uses `/oauth/authorize` as default
|
150 | * `tokenPath` - Access token path for the OAuth2 server.
|
151 | Simple OAuth2 uses `/oauth/token` as default.
|
152 |
|
153 | ```javascript
|
154 | // Set the configuration settings
|
155 | var credentials = {
|
156 | clientID: '<client-id>',
|
157 | clientSecret: '<client-secret>',
|
158 | site: 'https://www.oauth2.com',
|
159 | authorizationPath: '/oauth2/authorization',
|
160 | tokenPath: '/oauth2/access_token'
|
161 | };
|
162 |
|
163 | // Initialize the OAuth2 Library
|
164 | var OAuth2 = require('simple-oauth2')(credentials);
|
165 | ```
|
166 |
|
167 |
|
168 | ## Contributing
|
169 |
|
170 | Fork the repo on github and send a pull requests with topic branches. Do not forget to
|
171 | provide specs to your contribution.
|
172 |
|
173 |
|
174 | ### Running specs
|
175 |
|
176 | * Fork and clone the repository (`dev` branch).
|
177 | * Run `npm install` for dependencies.
|
178 | * Run `make test` to execute all specs.
|
179 | * Run `make test-watch` to auto execute all specs when a file change.
|
180 |
|
181 |
|
182 | ## Coding guidelines
|
183 |
|
184 | Follow [github](https://github.com/styleguide/) guidelines.
|
185 |
|
186 |
|
187 | ## Feedback
|
188 |
|
189 | Use the [issue tracker](http://github.com/andreareginato/simple-oauth2/issues) for bugs.
|
190 | [Mail](mailto:andrea.reginato@.gmail.com) or [Tweet](http://twitter.com/andreareginato) us
|
191 | for any idea that can improve the project.
|
192 |
|
193 |
|
194 | ## Links
|
195 |
|
196 | * [GIT Repository](http://github.com/andreareginato/simple-oauth2)
|
197 | * [Documentation](http://andreareginato.github.com/simple-oauth2)
|
198 |
|
199 |
|
200 | ## Authors
|
201 |
|
202 | [Andrea Reginato](http://twitter.com/andreareginato)
|
203 |
|
204 |
|
205 | ## Contributors
|
206 |
|
207 | Special thanks to the following people for submitting patches.
|
208 |
|
209 |
|
210 | ## Changelog
|
211 |
|
212 | See [CHANGELOG](https://github.com/andreareginato/simple-oauth2/blob/master/CHANGELOG.md)
|
213 |
|
214 |
|
215 | ## Copyright
|
216 |
|
217 | Copyright (c) 2013 [Lelylan](http://lelylan.com).
|
218 | See [LICENSE](https://github.com/andreareginato/simple-oauth2/blob/master/LICENSE.md) for details.
|