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:

1. Implement the YesodAuthOIDC class for your Yesod App. See the Haddocks for documentation.

2. Add Yesod.Auth.OIDC.authOIDC to your list of authPlugins.

3. 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.

4. 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.