yesod-auth-oauth2: OAuth 2.0 authentication plugins

[ library, mit, web ] [ Propose Tags ]

Library to authenticate with OAuth 2.0 for Yesod web applications.


[Skip to Readme]

Flags

Automatic Flags
NameDescriptionDefault
example

Build the example application

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.0.1, 0.0.2, 0.0.3, 0.0.4, 0.0.5, 0.0.5.1, 0.0.6, 0.0.7, 0.0.8, 0.0.9, 0.0.10, 0.0.11, 0.0.12, 0.1.0, 0.1.1, 0.1.2, 0.1.3, 0.1.4, 0.1.5, 0.1.6, 0.1.7, 0.1.8, 0.1.9, 0.1.10, 0.2.0, 0.2.1, 0.2.2, 0.2.4, 0.3.0, 0.3.1, 0.4.0.0, 0.4.0.1, 0.4.1.0, 0.5.0.0, 0.5.1.0, 0.5.2.0, 0.5.3.0, 0.6.0.0, 0.6.1.0, 0.6.1.1, 0.6.1.2, 0.6.1.3, 0.6.1.4, 0.6.1.5, 0.6.1.6, 0.6.1.7, 0.6.2.0, 0.6.2.1, 0.6.2.2, 0.6.2.3, 0.6.3.0, 0.6.3.1, 0.6.3.3, 0.6.3.4, 0.7.0.0, 0.7.0.1, 0.7.0.2, 0.7.0.3, 0.7.1.0, 0.7.1.1, 0.7.1.2, 0.7.1.3, 0.7.2.0
Change log CHANGELOG.md
Dependencies aeson (>=0.6 && <1.5), aeson-pretty, base (>=4.9.0.0 && <5), bytestring (>=0.9.1.4), containers, errors, hoauth2 (>=1.3.0 && <1.9), http-client (>=0.4.0 && <0.7), http-conduit (>=2.0 && <3.0), http-types (>=0.8 && <0.13), load-env, microlens, random, safe-exceptions, text (>=0.7 && <2.0), uri-bytestring, warp, yesod, yesod-auth (>=1.6.0 && <1.7), yesod-auth-oauth2, yesod-core (>=1.6.0 && <1.7) [details]
License MIT
Author Tom Streller
Maintainer Pat Brisbin <pbrisbin@gmail.com>
Category Web
Home page http://github.com/thoughtbot/yesod-auth-oauth2
Bug tracker https://github.com/thoughtbot/yesod-auth-oauth2/issues
Source repo head: git clone https://github.com/thoughtbot/yesod-auth-oauth2
Uploaded by PatrickBrisbin at 2019-01-09T19:26:09Z
Distributions Debian:0.6.1.2, LTSHaskell:0.7.2.0, NixOS:0.7.1.3, Stackage:0.7.2.0
Reverse Dependencies 1 direct, 0 indirect [details]
Executables yesod-auth-oauth2-example
Downloads 31567 total (158 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2019-01-09 [all 1 reports]

Readme for yesod-auth-oauth2-0.6.1.0

[back to package description]

Yesod.Auth.OAuth2

OAuth2 AuthPlugins for Yesod.

Usage

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:

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:

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:

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

stack setup
stack build --dependencies-only
stack build --pedantic --test

Please also run HLint and Weeder before submitting PRs.


CHANGELOG | LICENSE