diff --git a/.idea/auth_oauth2.iml b/.idea/auth_oauth2.iml new file mode 100644 index 00000000..7fe256fb --- /dev/null +++ b/.idea/auth_oauth2.iml @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 00000000..afb47af5 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 00000000..94a25f7f --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/README.md b/README.md index f3cd0ea8..edb4b7cd 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,106 @@ # auth_oauth2 -[![version 1.0.0](https://img.shields.io/badge/pub-1.0.0-brightgreen.svg)](https://pub.dartlang.org/packages/angel_auth_oauth2) +[![version 1.0.1](https://img.shields.io/badge/pub-1.0.1-brightgreen.svg)](https://pub.dartlang.org/packages/angel_auth_oauth2) -angel_auth strategy for OAuth2 login, i.e. Facebook. +`package:angel_auth` strategy for OAuth2 login, i.e. Facebook or Github. + +# Usage +First, create an options object: + +```dart +configureServer(Angel app) async { + // Load from a Map, i.e. app config: + var opts = new AngelOAuth2Options.fromJson(map); + + // Create in-place: + const AngelAuthOAuth2Options OAUTH2_CONFIG = const AngelAuthOAuth2Options( + callback: '', + key: '', + secret: '', + authorizationEndpoint: '', + tokenEndpoint: ''); +} +``` + +After getting authenticated against the remote server, we need to be able to identify +users within our own application. Use an `OAuth2Verifier` to associate remote users +with local users. + +```dart +/// You might use a pure function to create a verifier that queries a +/// given service. +OAuth2Verifier oauth2verifier(Service userService) { + return (oauth2.Client client) async { + var response = await client.get('https://api.github.com/user'); + var ghUser = JSON.decode(response.body); + var id = ghUser['id']; + + Iterable matchingUsers = await userService.index({ + 'query': {'githubId': id} + }); + + if (matchingUsers.isNotEmpty) { + // Return the corresponding user, if it exists + return User.parse(matchingUsers.firstWhere((u) => u['githubId'] == id)); + } else { + // Otherwise,create a user + return await userService.create({'githubId': id}).then(User.parse); + } + }; +} +``` + +Now, initialize an `OAuth2Strategy`, using the options and verifier. +You'll also need to provide a name for this instance of the strategy. +Consider using the name of the remote authentication provider (ex. `facebook`). + +```dart +configureServer(Angel app) { + // ... + var oauthStrategy = + new OAuth2Strategy('github', OAUTH2_CONFIG, oauth2Verifier(app.service('users'))); +} +``` + +Lastly, connect it to an `AngelAuth` instance, and wire it up to an `Angel` server. +Set up two routes: + 1. Redirect users to the external provider + 2. Acts as a callback and handles an access code + +In the case of the callback route, you may want to display an HTML page that closes +a popup window. In this case, use `confirmPopupAuthentication`, which is bundled with +`package:angel_auth`, as a `callback` function: + +```dart +configureServer(Angel app) async { + // ... + var auth = new AngelAuth(); + auth.strategies.add(oauth2Strategy); + + // Redirect + app.get('/auth/github', auth.authenticate('github')); + + // Callback + app.get('/auth/github/callback', auth.authenticate( + 'github', + new AngelAuthOptions(callback: confirmPopupAuthentication()) + )); + + // Connect the plug-in!!! + await app.configure(auth); +} +``` + +## Custom Scope Delimiter +This package should work out-of-the-box for most OAuth2 providers, such as Github or Dropbox. +However, if your OAuth2 scopes are separated by a delimiter other than the default (`' '`), +you can add it in the `AngelOAuth2Options` constructor: + +```dart +configureServer(Angel app) async { + const AngelOAuth2Options OPTS = const AngelOAuth2Options( + // ... + delimiter: ',' + ); +} +``` \ No newline at end of file diff --git a/pubspec.yaml b/pubspec.yaml index 93b46603..f5eb1aac 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,6 @@ name: angel_auth_oauth2 description: angel_auth strategy for OAuth2 login, i.e. Facebook. -version: 1.0.0 +version: 1.0.1 author: Tobe O environment: sdk: ">=1.19.0"