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