Skip to content
OAuth2 authentication for yesod
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Upgrade to GHC 8.6.3 Jan 9, 2019
example Deprecate improperly-cased Github module Jul 30, 2018
src Add AzureAD provider Mar 9, 2019
test Project setup files Jan 23, 2018
.env.example Bring back example application Feb 13, 2018
.gitignore
.hlint.yaml Address HLint issues Jan 23, 2018
.stylish-haskell.yaml Project setup files Jan 23, 2018
CHANGELOG.md Version bump Mar 9, 2019
LICENSE
Makefile Tweak make targets and CI steps Oct 24, 2018
README.md Typos and grammar in README Oct 24, 2018
Setup.lhs Initial import Jul 14, 2013
package.yaml Version bump Mar 9, 2019
stack-lts-12.2.yaml
stack-lts-13.2.yaml Upgrade to GHC 8.6.3 Jan 9, 2019
stack-nightly.yaml Update nightly build Nov 24, 2018
stack.yaml

README.md

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

You can’t perform that action at this time.