yesod-auth-oidc: A yesod-auth plugin for multi-tenant SSO via OpenID Connect

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

A yesod-auth plugin for multi-tenant SSO via OpenID Connect, using Authorization Code flow (AKA server flow). Please see the README.md file for more documentation.

[Skip to Readme]

Properties

Versions	0.1.0, 0.1.0, 0.1.1, 0.1.3, 0.1.4
Change log	None available
Dependencies	aeson (>=1.5.6 && <1.6), base (>=4.9.1.0 && <5), base64-bytestring (>=1.1.0 && <1.2), blaze-html (>=0.9.1 && <0.10), broch (>=0.1 && <0.2), bytestring (>=0.10.10 && <0.11), classy-prelude (>=1.5.0 && <1.6), classy-prelude-yesod (>=1.5.0 && <1.6), containers (>=0.6.2 && <0.7), cryptonite (>=0.28 && <0.29), directory (>=1.3.6 && <1.4), email-validate (>=2.3.2 && <2.4), fast-logger (>=3.0.5 && <3.1), hspec (>=2.7.10 && <2.8), http-client (>=0.6.4 && <0.7), http-conduit (>=2.3.8 && <2.4), http-types (>=0.12.3 && <0.13), jose-jwt (>=0.9.2 && <0.10), lens (>=4.19.2 && <4.20), lens-regex-pcre (>=1.1.0 && <1.2), memory (>=0.15.0 && <0.16), monad-logger (>=0.3.36 && <0.4), oidc-client (>=0.6.0 && <0.7), persistent (>=2.11.0 && <=2.13.2), persistent-sqlite (>=2.11.1 && <=2.13), postgresql-simple (>=0.6.4 && <0.7), reroute (>=0.6.0 && <0.7), resource-pool (>=0.2.3 && <0.3), shakespeare (>=2.0.25 && <2.1), sqlite-simple (>=0.4.18 && <0.5), text (>=1.2.4 && <1.3), time (>=1.9.3 && <1.10), unordered-containers (>=0.2.13 && <0.3), wai-app-static (>=3.1.7 && <3.2), wai-extra (>=3.1.6 && <3.2), warp (>=3.3.15 && <3.4), yesod (>=1.6.1 && <1.7), yesod-auth (>=1.6.10 && <1.7), yesod-core (>=1.6.19 && <1.7), yesod-form (>=1.6.7 && <1.7), yesod-persistent (>=1.6.0 && <1.7), yesod-test (>=1.6.12 && <1.7) [details]
License	BSD-3-Clause
Author	Supercede Technology Ltd
Maintainer	Supercede Technology Ltd <support@supercede.com>
Category	Web, Yesod
Home page	https://github.com/SupercedeTech/yesod-auth-oidc
Source repo	head: git clone git@github.com:SupercedeTech/yesod-auth-oidc.git
Uploaded	by tim_supercede at 2021-11-24T15:27:00Z

Modules

Yesod
- Auth
  - Yesod.Auth.OIDC

Downloads

yesod-auth-oidc-0.1.0.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

No current members of group

For package maintainers and hackage trustees

edit package information

Readme for yesod-auth-oidc-0.1.0

[back to package description]

yesod-auth-oidc

A Yesod authentication plugin for multi-tenant Single Sign-on (SSO) via OpenID Connect (OIDC Core 1.0), using Authorization Code flow (defined in §3.1, AKA server flow).

Supports multiple Identity Providers with callbacks based on the login_hint (typically an email).
Each provider can be configured either through OIDC Discovery or manually. (The Dynamic Registration OIDC extension is not supported).
Uses with your Yesod app's session library plus a small middleware. That means there's no need to rely on encrypted JWTs in the browser if you use server-side sessions.
Works well with yesod-auth-simple.

Using the library

This library abstracts many details of OIDC for you, but you may need to understand the basics of OIDC to integrate this with your app. The steps are:

Implement the YesodAuthOIDC class for your Yesod App. See the Haddocks for documentation.
Add Yesod.Auth.OIDC.authOIDC to your list of authPlugins.
Add the Yesod.Auth.OIDC.oidcSessionExpiryMiddleware to your WAI middleware. This ensures the user is logged out upon the token's expiry. You should be able to implement something more fancy than a hard logout without modifying this libary.
Add some extra UI logic for choosing between login methods if you have more than one auth plugin. Yesod provides some defaults here for getting started.

Also see this library's test suite, especially test/ExampleApp.hs and test/Yesod/Auth/OIDCSpec.hs.

Relation to other Haskell libraries

Broch: a Haskell implementation of an OpenID Provider. yesod-auth-oidc implements an OpenID Relying Party (AKA client).
oidc-client: yesod-auth-oidc uses this utility library. It handles important parts such as token validation, and is not tied to Yesod.
yesod-auth, its Yesod.Auth.OpenID module, and the the authenticate library: this appears to be an implementation of OpenID Authentication 2.0, which is the previous "generation" of the OpenID Foundation's efforts. OpenID 2 doesn't seem to be supported by many off-the-shelf SSO Providers (e.g. Azure AD, Auth0), unlike OIDC.
yesod-auth-oauth2: Offers authentication using the authorisation protocol OAuth 2.0. OIDC defines some extras on top of OAuth 2.0 to securely implement authentication.

Limitations

Only Authorization Code flow is supported. This is the most widely compatible version of OIDC, which all compliant providers must support.
Extras such as dynamic registration, single log-out, and automatic session extension via the "prompt" parameter are not implemented.
The algorithm for determining the HTTP cache period of the discovery document and JWK Set is not yet implemented. For now, you could implement most of this yourself in the appropriate callback however (or send.

Development

The maintainers typically run nix-shell and then use GHCi or cabal from there.