diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,189 @@ +## [*Unreleased*](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.6.0.0...master) + +None + +## [v0.6.0.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.5.3.0...v0.6.0.0) + +- Remove deprecated Github module + +## [v0.5.3.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.5.2.0...v0.5.3.0) + +- Allow aeson-1.4 and hoauth2-1.8 + +## [v0.5.2.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.5.1.0...v0.5.2.0) + +- `InvalidProfileResponse` was replaced with different, situation-specific + constructors; the exception type is considered internal API, but end-users may + see them in logs, or if they (unexpectedly) escape our error-handling +- Errors during log-in no longer result in 4XX or 5XX responses; they now + redirect to `LoginR` with the exception details logged and something + user-appropriate displayed via `setMessage` + +## [v0.5.1.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.5.0.0...v0.5.1.0) + +- Added GitLab provider +- Added properly-named `GitHub` module, deprecated `Github` +- Store `refreshToken` in `credsExtra` + +## [v0.5.0.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.4.1.0...v0.5.0.0) + +- COMPATIBILITY: Allow and require yesod-1.6 +- COMPATIBILITY: Stop testing GHC 8.0 on CI + +## [v0.4.1.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.4.0.1...v0.4.1.0) + +- Check for `error`s in callback query params, as described in the + [spec](https://tools.ietf.org/html/rfc6749#section-4.1.2.1) + +## [v0.4.0.1](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.4.0.0...v0.4.0.1) + +- COMPATIBILITY: Allow `http-types-0.12` + +## [v0.4.0.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.3.1...v0.4.0.0) + +- COMPATIBILITY: Allow `aeson-1.3` +- COMPATIBILITY: Dropped a lot of information from `credsExtra`: + + **TL;DR**: you'll no longer find things like `username` or `email` as keys in + the `credsExtra` map. Instead, you'll find the encoded profile response we + received and the OAuth access token. You can/should do your own decoding or + make your own follow-up requests to get extra data about your users. + + This reduced a lot of complexity, likely duplication between our decoding and + yours, and (I think) makes the library easier to use. + + - [Issue](https://github.com/thoughtbot/yesod-auth-oauth2/issues/71) + - [PR](https://github.com/thoughtbot/yesod-auth-oauth2/pull/100) + +- COMPATIBILITY: Support GHC-8.2 +- COMPATIBILITY: Drop (claimed, but never tested) support for GHC-7.8 & 7.10 +- LICENSE: fixed vague licensing (MIT now) + +## [v0.3.1](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.3.0...v0.3.1) + +- Internal project cleanup + +## [v0.3.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.2.4...v0.3.0) + +- COMPATIBILITY: Use `hoauth2-1.3` + +## [v0.2.4](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.2.1...v0.2.4) + +- FIX: Update Nylas provider +- NEW: Battle.Net provider +- NEW: Bitbucket provider +- NEW: Salesforce provider + +## [v0.2.1](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.2.0...v0.2.1) + +- FIX: Fix collision in GitHub `email` / `public_email` extras value + +## [v0.2.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.10...v0.2.0) + +- NEW: Slack provider ([@jsteiner](https://github.com/thoughtbot/yesod-auth-oauth2/commit/aad8bd88eabf9fcf368d044e7003e5d323985837)) + +## [v0.1.10](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.9...v0.1.10) + +- FIX: `location` is optional in GitHub response + +## [v0.1.9](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.8...v0.1.9) + +- COMPATIBILITY: Allow `transformers-0.5` ([@paul-rouse](https://github.com/thoughtbot/yesod-auth-oauth2/commit/120104b5348808f72877962c329a998434addace)) + +## [v0.1.8](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.7...v0.1.8) + +- COMPATIBILITY: Allow `aeson-0.11` ([@k-bx](https://github.com/thoughtbot/yesod-auth-oauth2/commit/6e940b19e2d56080c7a749aeb29e143a17dad65c)) + +## [v0.1.7](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.6...v0.1.7) + +- NEW: Prefer primary email in GitHub provider +- NEW: Include `public_email` in GitHub extras response +- REMOVED: Remove Twitter provider + +## [v0.1.6](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.5...v0.1.6) + +- NEW: Nicer error message on invalid `code` ([@silky](https://github.com/thoughtbot/yesod-auth-oauth2/commit/7354c36e1326d298e543fa65cf226153ed4a8a0b)) + +## [v0.1.5](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.4...v0.1.5) + +- FIX: Incorrect `state` parameter handling + +## [v0.1.4](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.3...v0.1.4) + +- FIX: Use newer Nylas endpoint + +## [v0.1.3](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.2...v0.1.3) + +- NEW: EveOnline provider ([@Drezil](https://github.com/thoughtbot/yesod-auth-oauth2/pull/33)) +- NEW: Nylas provider ([@bts](https://github.com/thoughtbot/yesod-auth-oauth2/commit/815d44346403af0052a48aa844f506211bdc2863)) + +## [v0.1.2](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.1...v0.1.2) + +- NEW: A more different Google provider ([@ssaavedra](https://github.com/thoughtbot/yesod-auth-oauth2/pull/32)) + +## [v0.1.1](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.1.0...v0.1.1) + +- NEW: Twitter provider + +## [v0.1.0](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.12...v0.1.0) + +- REMOVED: Google provider, use `Yesod.Auth.GoogleEmail2` +- CHANGED: Learn was renamed to Upcase +- COMPATIBILITY: Drop support for GHC-6 +- COMPATIBILITY: Support GHC-7.10 + +## [v0.0.12](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.11...v0.0.12) + +- COMPATIBILITY: Allow `transformers-0.4` ([@snoyberg](https://github.com/thoughtbot/yesod-auth-oauth2/pull/21)) + +## [v0.0.11](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.10...v0.0.11) + +- COMPATIBILITY: Allow `aeson-0.8` ([@gfontenot](https://github.com/thoughtbot/yesod-auth-oauth2/pull/15)) + +## [v0.0.10](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.9...v0.0.10) + +- COMPATIBILITY: Allow Yesod 1.4 ([@gregwebs](https://github.com/thoughtbot/yesod-auth-oauth2/pull/14)) + +## [v0.0.9](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.8...v0.0.9) + +- NEW: Spotify ([@benekastah](https://github.com/thoughtbot/yesod-auth-oauth2/pull/13)) + +## [v0.0.8](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.7...v0.0.8) + +- FIX: Username may be missing in GitHub responses ([@skade](https://github.com/thoughtbot/yesod-auth-oauth2/pull/12)) + +## [v0.0.7](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.6...v0.0.7) + +- NEW: Scope support in GitHub provider ([@skade](https://github.com/thoughtbot/yesod-auth-oauth2/pull/11)) + +## [v0.0.6](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.5.1...v0.0.6) + +- NEW: GitHub provider ([@freiric](https://github.com/thoughtbot/yesod-auth-oauth2/pull/10)) +- COMPATIBILITY: flag-driven `network`/`network-uri` dependency + +## [v0.0.5.1](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.5...v0.0.5.1) + +- DOCUMENTATION: fix data declaration, allows Haddocks to build + +## [v0.0.5](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.4...v0.0.5) + +- COMPATIBILITY: Allow `yesod-core-1.3` and target `yesod-auth-1.3` ([@maxcan](https://github.com/thoughtbot/yesod-auth-oauth2/pull/7)) +- COMPATIBILITY: Target `haouth2-0.4` ([@katyo](https://github.com/thoughtbot/yesod-auth-oauth2/pull/9)) + +## [v0.0.4](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.3...v0.0.4) + +- COMPATIBILITY: Allow `text-1.*` +- COMPATIBILITY: Allow `lifted-base-0.2.*` + +## [v0.0.3](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.2...v0.0.3) + +- FIX: replace `error` crash with `throwIO` exception + +## [v0.0.2](https://github.com/thoughtbot/yesod-auth-oauth2/compare/v0.0.1...v0.0.2) + +- Various documentation fixes. + +## [v0.0.1](https://github.com/thoughtbot/yesod-auth-oauth2/tree/v0.0.1) + +Initial version. Maintainer-ship taken over by +[@pbrisbin](https://github.com/thoughtbot/yesod-auth-oauth2/pull/1). diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,117 @@ +# Yesod.Auth.OAuth2 + +OAuth2 `AuthPlugin`s for Yesod. + +## Usage + +```hs +import Yesod.Auth +import Yesod.Auth.OAuth2.GitHub + +instance YesodAuth App where + -- ... + + authPlugins _ = [oauth2GitHub clientId clientSecret] + +clientId :: Text +clientId = "..." + +clientSecret :: Text +clientSecret = "..." +``` + +Some plugins, such as GitHub and Slack, have scoped functions for requesting +additional information: + +```hs +oauth2SlackScoped [SlackBasicScope, SlackEmailScope] clientId clientSecret +``` + +## Working with Extra Data + +We put the minimal amount of user data possible in `credsExtra` -- just enough +to support you parsing or fetching additional data yourself. + +For example, if you work with GitHub and GitHub user profiles, you likely +already have a model and a way to parse the `/user` response. Rather than +duplicate all that in our library, we try to make it easy for you to re-use that +code yourself: + +```hs +authenticate creds = do + let + -- You can run your own FromJSON parser on the response we already have + eGitHubUser :: Either String GitHubUser + eGitHubUser = getUserResponseJSON creds + + -- Avert your eyes, simplified example + Just accessToken = getAccessToken creds + Right githubUser = eGitHubUser + + -- Or make followup requests using our access token + runGitHub accessToken $ userRepositories githubUser + + -- Or store it for later + insert User + { userIdent = credsIdent creds + , userAccessToken = accessToken + } +``` + +**NOTE**: Avoid looking up values in `credsExtra` yourself; prefer the provided +`get` functions. The data representation itself is no longer considered public +API. + +## Local Providers + +If we don't supply a "Provider" (e.g. GitHub, Google, etc) you need, you can +write your own using our provided `Prelude`: + +```haskell +import Yesod.Auth.OAuth2.Prelude + +pluginName :: Text +pluginName = "mysite" + +oauth2MySite :: YesodAuth m => Text -> Text -> AuthPlugin m +oauth2MySite clientId clientSecret = + authOAuth2 pluginName oauth2 $ \manager token -> do + -- Fetch a profile using the manager and token, leave it a ByteString + userResponse <- -- ... + + -- Parse it to your preferred identifier, e.g. with Data.Aeson + userId <- -- ... + + -- See authGetProfile for the typical case + + pure Creds + { credsPlugin = pluginName + , credsIdent = userId + , credsExtra = setExtra token userResponse + } + where + oauth2 = OAuth2 + { oauthClientId = clientId + , oauthClientSecret = clientSecret + , oauthOAuthorizeEndpoint = "https://mysite.com/oauth/authorize" + , oauthAccessTokenEndpoint = "https://mysite.com/oauth/token" + , oauthCallback = Nothing + } +``` + +The `Prelude` module is considered public API, though we may build something +higher-level that is more convenient for this use-case in the future. + +## Development & Tests + +```console +stack setup +stack build --dependencies-only +stack build --pedantic --test +``` + +Please also run HLint and Weeder before submitting PRs. + +--- + +[CHANGELOG](./CHANGELOG.md) | [LICENSE](./LICENSE) diff --git a/src/Yesod/Auth/OAuth2/Github.hs b/src/Yesod/Auth/OAuth2/Github.hs deleted file mode 100644 --- a/src/Yesod/Auth/OAuth2/Github.hs +++ /dev/null @@ -1,15 +0,0 @@ -module Yesod.Auth.OAuth2.Github - {-# DEPRECATED "Please use Yesod.Auth.OAuth2.GitHub (GitHub, not Github)" #-} - ( oauth2Github - , oauth2GithubScoped - ) where - - -import Yesod.Auth.OAuth2.GitHub -import Yesod.Auth.OAuth2.Prelude - -oauth2Github :: YesodAuth m => Text -> Text -> AuthPlugin m -oauth2Github = oauth2GitHub - -oauth2GithubScoped :: YesodAuth m => [Text] -> Text -> Text -> AuthPlugin m -oauth2GithubScoped = oauth2GitHubScoped diff --git a/yesod-auth-oauth2.cabal b/yesod-auth-oauth2.cabal --- a/yesod-auth-oauth2.cabal +++ b/yesod-auth-oauth2.cabal @@ -4,24 +4,27 @@ -- -- see: https://github.com/sol/hpack -- --- hash: 0411a1ae914befb60e1871e7735c2e7afb87fc0c463cd1142e1c1ecf762a14cb +-- hash: 33e72c75eda94306ce59d50e8f7444f264b8d34e1b1a6ca207a0b4dee9d07cd9 name: yesod-auth-oauth2 -version: 0.5.3.0 +version: 0.6.0.0 synopsis: OAuth 2.0 authentication plugins description: Library to authenticate with OAuth 2.0 for Yesod web applications. category: Web homepage: http://github.com/thoughtbot/yesod-auth-oauth2 -bug-reports: https://github.com/thoughtbot/yesod-auth-oauth2.git/issues +bug-reports: https://github.com/thoughtbot/yesod-auth-oauth2/issues author: Tom Streller maintainer: Pat Brisbin license: MIT license-file: LICENSE build-type: Simple +extra-source-files: + README.md + CHANGELOG.md source-repository head type: git - location: https://github.com/thoughtbot/yesod-auth-oauth2.git + location: https://github.com/thoughtbot/yesod-auth-oauth2 flag example description: Build the example application @@ -58,7 +61,6 @@ Yesod.Auth.OAuth2.EveOnline Yesod.Auth.OAuth2.Exception Yesod.Auth.OAuth2.GitHub - Yesod.Auth.OAuth2.Github Yesod.Auth.OAuth2.GitLab Yesod.Auth.OAuth2.Google Yesod.Auth.OAuth2.Nylas