OLD | NEW |
---|---|
(Empty) | |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 /// A client library for authenticating with a remote service via OAuth2 on | |
6 /// behalf of a user, and making authorized HTTP requests with the user's OAuth2 | |
7 /// credentials. | |
8 /// | |
9 /// OAuth2 allows a client (the program using this library) to access and | |
10 /// manipulate a resource that's owned by a resource owner (the end user) and | |
11 /// lives on a remote server. The client directs the resource owner to an | |
12 /// authorization server (usually but not always the same as the server that | |
13 /// hosts the resource), where the resource owner tells the authorization server | |
14 /// to give the client an access token. This token serves as proof that the | |
15 /// client has permission to access resources on behalf of the resource owner. | |
16 /// | |
17 /// OAuth2 provides several different methods for the client to obtain | |
18 /// authorization. At the time of writing, this library only supports the | |
19 /// [AuthorizationCodeGrant] method, but further methods may be added in the | |
20 /// future. The following example uses this method to authenticate, and assumes | |
21 /// that the library is being used by a server-side application. | |
22 /// | |
23 /// import 'dart:io' | |
24 /// import 'dart:uri' | |
25 /// import 'package:oauth2/oauth2.dart' as oauth2; | |
26 /// | |
27 /// // These URLs are endpoints that are provided by the authorization | |
28 /// // server. They're usually included in the server's documentation of its | |
29 /// // OAuth2 API. | |
30 /// final Uri authorizationEndpoint = | |
31 /// new Uri.fromString("http://example.com/oauth2/authorization"); | |
32 /// final Uri tokenEndpoint = | |
33 /// new Uri.fromString("http://example.com/oauth2/token"); | |
Bob Nystrom
2012/11/16 19:53:30
Nit, but I wouldn't bother to type annotate these
nweiz
2012/11/17 01:06:27
Done.
| |
34 /// | |
35 /// // The authorization server will issue each client a separate client | |
36 /// // identifier and secret, which allows the server to tell which client | |
37 /// // is accessing it. Some servers may also have an anonymous | |
38 /// // identifier/secret pair that any client may use. | |
39 /// // | |
40 /// // Note that clients whose source code or binary executable is readily | |
41 /// // available may not be able to make sure the client secret is kept a | |
42 /// // secret. This is fine; OAuth2 servers generally won't rely on knowing | |
43 /// // with certainty that a client is who it claims to be. | |
44 /// final String identifier = "my client identifier"; | |
45 /// final String secret = "my client secret"; | |
46 /// | |
47 /// // This is a URL on your application's server. The authorization server | |
48 /// // will redirect the resource owner here once they've authorized the | |
49 /// // client. The redirection will include the authorization code in the | |
50 /// // query parameters. | |
51 /// final Uri redirectUrl = new Uri.fromString( | |
52 /// "http://my-site.com/oauth2-redirect"); | |
53 /// | |
54 /// var credentialsFile = new File("~/.myapp/credentials.json"); | |
55 /// return credentialsFile.exists().chain((exists) { | |
56 /// // If the OAuth2 credentials have already been saved from a previous | |
57 /// // run, we just want to reload them. | |
58 /// if (exists) { | |
59 /// return credentialsFile.readAsText().transform((json) { | |
60 /// var credentials = new oauth2.Credentials.fromJson(json); | |
61 /// return new oauth2.Client(identifier, secret, credentials); | |
62 /// }); | |
63 /// } | |
64 /// | |
65 /// // If we don't have OAuth2 credentials yet, we need to get the | |
66 /// // resource owner to authorize us. We're assuming here that we're a | |
67 /// // command-line application. | |
68 /// var grant = new oauth2.AuthorizationCodeGrant( | |
69 /// identifier, secret, authorizationEndpoint, tokenEndpoint); | |
70 /// | |
71 /// // Redirect the resource owner to the authorization URL. This will be | |
72 /// // a URL on the authorization server (authorizationEndpoint with some | |
73 /// // additional query parameters). Once the resource owner has | |
74 /// // authorized, they'll be redirected to `redirectUrl` with an | |
75 /// // authorization code. | |
76 /// // | |
77 /// // `redirect` is an imaginary function that redirects the resource | |
78 /// // owner's browser. | |
79 /// return redirect(grant.getAuthorizationUrl(redirectUrl)).chain((_) { | |
80 /// // Another imaginary function that listens for a request to | |
81 /// // `redirectUrl`. | |
82 /// return listen(redirectUrl); | |
83 /// }).transform((request) { | |
84 /// // Once the user is redirected to `redirectUrl`, pass the query | |
85 /// // parameters the the AuthorizationCodeGrant. It will validate them | |
Bob Nystrom
2012/11/16 19:53:30
"the the" -> "to the"
nweiz
2012/11/17 01:06:27
Done.
| |
86 /// // and extract the authorization code to create a new Client. | |
87 /// return grant.handleAuthorizationResponse(request.queryParameters); | |
88 /// }) | |
89 /// }).chain((client) { | |
90 /// // Once you have a Client, you can use it just like any other HTTP | |
91 /// // client. | |
92 /// return client.read("http://example.com/protected-resources.txt") | |
93 /// .transform((result) { | |
94 /// // Once we're done with the client, save the credentials file. This | |
95 /// // ensures that if the credentials were automatically refreshed | |
96 /// // while using the client, the new credentials are available for the | |
97 /// // next run of the program. | |
98 /// return credentialsFile.open(FileMode.WRITE).chain((file) { | |
99 /// return file.writeString(client.credentials.toJson()); | |
100 /// }).chain((file) => file.close()).transform((_) => result); | |
101 /// }); | |
102 /// }).then(print); | |
Bob Nystrom
2012/11/16 19:53:30
Wonderful example. Nicely done.
nweiz
2012/11/17 01:06:27
Thanks! It was kind of a pain, but I'm glad it's t
| |
103 library oauth2; | |
104 | |
105 export 'src/authorization_code_grant.dart'; | |
106 export 'src/client.dart'; | |
107 export 'src/credentials.dart'; | |
108 export 'src/authorization_exception.dart'; | |
OLD | NEW |