openid-connect- An OpenID Connect library that does all the heavy lifting for you

CopyrightThis file is part of the package openid-connect. It is subject to
the license terms in the LICENSE file found in the top-level
directory of this distribution and at:

No part of this package including this file may be copied
modified propagated or distributed except according to the terms
contained in the LICENSE file.
Safe HaskellNone




The Authorization Code Flow as defined in OpenID Connect 1.0.

Flow outline:

  1. Perform (and optionally cache) the provider's discovery document and keys. This is done with a combination of discovery and keysFromDiscovery.
  2. Send the end-user to the provider for authentication by applying the authenticationRedirect function. It will generate a RedirectTo response with a URI and cookie.
  3. The provider will redirect the end-user back to your site with some query parameters. Bundle those up and apply the authenticationSuccess function. It will respond with a validated identity token if everything checks out.


authenticationRedirect :: MonadRandom m => Discovery -> AuthenticationRequest -> m (Either FlowError RedirectTo) Source #

Step 1: Send the end-user to the provider.

This request will create a URI pointing to the provider's authorization end point and a session cookie that must be set in the end-user's browser.

To create a Discovery value, use the discovery function.

To create an AuthenticationRequest value use the defaultAuthenticationRequest function.

authenticationSuccess :: MonadRandom m => HTTPS m -> UTCTime -> Provider -> Credentials -> UserReturnFromRedirect -> m (Either FlowError (TokenResponse ClaimsSet)) Source #

Step 2. Turn the end-user's authorization token into an identity token.

When the end-user returns from the provider they will make a request to your site with some query parameters and a session cookie. With those values in hand, this function represents a request to receive and validate an identity token from the provider.

In order to create this function you'll need a few records:

data RedirectTo Source #

Send the end-user to this URI after setting a cookie.

The function for generating a cookie accepts the name of the cookie. This allows you to give the cookie any name you choose. Just be sure to retrieve the same cookie from the end-user when creating the UserReturnFromRedirect value.

The returned cookie has all of its security-related features enabled. Depending on your hosting requirements you may need to use the cookie package to loosen these restrictions.

Setting (and retrieving) the given cookie is mandatory. It is used to cryptographically derive the state and nonce values for request forgery protection and replay protection.


RedirectTo URI (ByteString -> SetCookie) 

Authentication settings

defaultAuthenticationRequest Source #


:: Scope

Requested scope.

-> Credentials

Provider assigned credentials.

-> AuthenticationRequest

An AuthenticationRequest.

Create an AuthenticationRequest value for the authorization code flow.


End-user provided details

data UserReturnFromRedirect Source #

Values to collect from the end-user after they return from provider authentication as per §

When the end-user is sent to the ClientRedirectURI they must provide the following values. If any of these fields are not provided by the end-user you should assume the authentication failed.

If the state and/or code parameters are missing in the HTTP request you should look for an error query parameter as specified in §





Errors that can occur

data FlowError Source #

Errors that may occur during the authentication code flow.



ProviderDiscoveryError DiscoveryError

Something is wrong with the discovery document.


The state query parameter provided by the end-user doesn't match their session cookie. It's possible that the current request was forged and therefore didn't originate from an actual end-user.


The nonce claim in the identity token doesn't match the value in the end-user's session cookie. It's possible that the response from the provider is a replay of a previous response.


The provider does not support the Authorization Code flow. To work with this provider you must use another flow type (i.e. implicit or hybrid).

InvalidProviderTokenEndpointError Text

The provider's discovery document includes a token_endpoint which is not a valid URL. The invalid URL is provided for reference.


The provided Credentials do not include any authentication secrets that match what the provider accepts in the tokenEndpointAuthMethodsSupported field. Therefore we can't make a token exchange request with this provider without using a different set of Credentials.

InvalidProviderTokenResponseError ErrorResponse

While exchanging an authorization code for an identity token the provider responded in a way that we couldn't parse. A decoding error message is provided for debugging.

TokenDecodingError Error

The TokenResponse from the provider failed to decode or validate. More information is provided by the jose error.

IdentityTokenValidationFailed JWTError

The identity token from the provider is invalid (i.e. one of the claims is incorrect) or the digital signature on the token doesn't match any of the keys in the provided key set.

Ancillary types and re-exports

type HTTPS m = Request -> m (Response ByteString) Source #

A function that can make HTTPS requests.

Make sure you are using a Manager value from the http-client-tls package. It's imperative that the requests flowing through this function are encrypted.

All requests are set to throw an exception if the response status code is not in the 2xx range. Therefore, functions that take this HTTPS type should be called in an exception-safe way and any exception should be treated as an authentication failure.


data ErrorResponse Source #

A provider response that indicates an error as described in OAuth 2.0 Bearer Token Usage (RFC 6750).