Copyright	This 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: https://code.devalot.com/open/openid-connect 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.
License	BSD-2-Clause
Safe Haskell	Safe-Inferred
Language	Haskell2010

OpenID.Connect.Client.Flow.AuthorizationCode

Contents

Flow
Authentication settings
End-user provided details
Errors that can occur
Ancillary types and re-exports

Description

The Authorization Code Flow as defined in OpenID Connect 1.0.

Flow outline:

Perform (and optionally cache) the provider's discovery document and keys. This is done with a combination of discovery and keysFromDiscovery.
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.
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.

Synopsis

authenticationRedirect :: MonadRandom m => Discovery -> AuthenticationRequest -> m (Either FlowError RedirectTo)
authenticationSuccess :: MonadRandom m => HTTPS m -> UTCTime -> Provider -> Credentials -> UserReturnFromRedirect -> m (Either FlowError (TokenResponse ClaimsSet))
authenticationSuccessWithJwt :: MonadRandom m => HTTPS m -> UTCTime -> Provider -> Credentials -> UserReturnFromRedirect -> m (Either FlowError (TokenResponse (ClaimsSet, SignedJWT)))
data RedirectTo = RedirectTo URI (ByteString -> SetCookie)
defaultAuthenticationRequest :: Scope -> Credentials -> AuthenticationRequest
data UserReturnFromRedirect = UserReturnFromRedirect {
}
data FlowError
type HTTPS m = Request -> m (Response ByteString)
data ErrorResponse = ErrorResponse {
- errorCode :: Text
- errorDescription :: Maybe Text
}
module OpenID.Connect.Authentication
module OpenID.Connect.Client.Provider
module OpenID.Connect.Scope

Flow

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:

The current time given as a UTCTime
A Provider record (discovery document and key set)
Your client Credentials
The request details from the end-user in UserReturnFromRedirect

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

Same as authenticationSuccess but return also the original id_token as SignedJWT.

Some endpoints (e.g. the end_session_endpoint) may require the original id_token; this functions allows an application to save it for later use.

Since: 0.2.0

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.

Constructors

RedirectTo URI (ByteString -> SetCookie)

Authentication settings

defaultAuthenticationRequest Source #

Arguments

:: Scope	Requested scope.
-> Credentials	Provider assigned credentials.
-> AuthenticationRequest	An `AuthenticationRequest`.

Create an AuthenticationRequest value for the authorization code flow.

Since: 0.1.0.0

End-user provided details

data UserReturnFromRedirect Source #

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

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 §3.1.2.6.

Since: 0.1.0.0

Constructors

UserReturnFromRedirect

Fields

afterRedirectSessionCookie :: ByteString
The end-user must provide a cookie value set by the RedirectTo response. This is needed to validate the state parameter and the nonce claim in the identity token.
afterRedirectCodeParam :: ByteString
The code parameter which contains the authorization code.
afterRedirectStateParam :: ByteString
The state parameter which is used to prevent request forgery.

Errors that can occur

data FlowError Source #

Errors that may occur during the authentication code flow.

Since: 0.1.0.0

Constructors

ProviderDiscoveryError DiscoveryError	Something is wrong with the discovery document.
InvalidStateParameterError	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.
InvalidNonceFromProviderError	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.
ProviderMissingTokenEndpointError	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.
NoAuthenticationMethodsAvailableError	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.

Instances

Instances details

Exception FlowError Source #
Instance details Defined in OpenID.Connect.Client.Flow.AuthorizationCode Methods toException :: FlowError -> SomeException # fromException :: SomeException -> Maybe FlowError # displayException :: FlowError -> String #
Show FlowError Source #
Instance details Defined in OpenID.Connect.Client.Flow.AuthorizationCode Methods showsPrec :: Int -> FlowError -> ShowS # show :: FlowError -> String # showList :: [FlowError] -> ShowS #

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.

Since: 0.1.0.0

data ErrorResponse Source #

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

Since: 0.1.0.0

Constructors

ErrorResponse
Fields errorCode :: Text errorDescription :: Maybe Text

Instances

Instances details

FromJSON ErrorResponse Source #
Instance details Defined in OpenID.Connect.JSON Methods parseJSON :: Value -> Parser ErrorResponse # parseJSONList :: Value -> Parser [ErrorResponse] #
ToJSON ErrorResponse Source #
Instance details Defined in OpenID.Connect.JSON Methods toJSON :: ErrorResponse -> Value # toEncoding :: ErrorResponse -> Encoding # toJSONList :: [ErrorResponse] -> Value # toEncodingList :: [ErrorResponse] -> Encoding #
Show ErrorResponse Source #
Instance details Defined in OpenID.Connect.JSON Methods showsPrec :: Int -> ErrorResponse -> ShowS # show :: ErrorResponse -> String # showList :: [ErrorResponse] -> ShowS #

module OpenID.Connect.Authentication

module OpenID.Connect.Client.Provider

module OpenID.Connect.Scope