OpenID.Connect.Client.Flow.AuthorizationCode

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.

Flow

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

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))

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

data RedirectTo

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

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

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

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

Show FlowError

Defined in OpenID.Connect.Client.Flow.AuthorizationCode

Methods

showsPrec :: Int -> FlowError -> ShowS

show :: FlowError -> String

showList :: [FlowError] -> ShowS

Exception FlowError

Defined in OpenID.Connect.Client.Flow.AuthorizationCode

Methods

toException :: FlowError -> SomeException

fromException :: SomeException -> Maybe FlowError

displayException :: FlowError -> String

Ancillary types and re-exports

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

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

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

Show ErrorResponse

Defined in OpenID.Connect.JSON

Methods

showsPrec :: Int -> ErrorResponse -> ShowS

show :: ErrorResponse -> String

showList :: [ErrorResponse] -> ShowS

ToJSON ErrorResponse

Defined in OpenID.Connect.JSON

Methods

toJSON :: ErrorResponse -> Value

toEncoding :: ErrorResponse -> Encoding

toJSONList :: [ErrorResponse] -> Value

toEncodingList :: [ErrorResponse] -> Encoding

FromJSON ErrorResponse

Defined in OpenID.Connect.JSON

Methods

parseJSON :: Value -> Parser ErrorResponse

parseJSONList :: Value -> Parser [ErrorResponse]

module OpenID.Connect.Authentication

module OpenID.Connect.Client.Provider

module OpenID.Connect.Scope