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]
Versions 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
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 Wed Jan 9 19:26:09 UTC 2019
Distributions Debian:0.5.2.0, LTSHaskell:0.6.1.0, NixOS:0.6.1.0, Stackage:0.6.1.0
Executables yesod-auth-oauth2-example
Downloads 9192 total (506 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2019-01-09 [all 1 reports]

Modules

[Index] [Quick Jump]

Flags

NameDescriptionDefaultType
example

Build the example application

DisabledAutomatic

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

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


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