Utility library to manage client-side OAuth 2.0 authentications
The library contains a main OAuth module exposing types used accross other modules. In practice, you'll only need to use one of the additional modules:
OAuth.AuthorizationCode: The authorization code grant type is used to obtain both access tokens and refresh tokens via a redirection-based flow and is optimized for confidential clients 4.1.
OAuth.AuthorizationCode.PKCE: An extension of the original OAuth 2.0 specification to mitigate authorization code interception attacks through the use of Proof Key for Code Exchange (PKCE).
OAuth.Implicit: The implicit grant type is used to obtain access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI 4.2.
OAuth.Password: The resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client, such as the device operating system or a highly privileged application 4.3
OAuth.ClientCredentials: The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the authorization server (the method of which is beyond the scope of this specification) 4.4.
In practice, you most probably want to use the
OAuth.AuthorizationCode
.
If your authorization server supports it, you should look at the PKCE extension in a second-time!
which is the most commonly used.
Describes the type of access token to use.
Bearer: Utilized by simply including the access token string in the request rfc6750
Mac: Not supported.
useToken : Token -> List Http.Header -> List Http.Header
Use a token to authenticate a request.
tokenToString : Token -> String
Get the String
representation of a Token
to be used in an 'Authorization' header
tokenFromString : String -> Maybe Token
Parse a token from an 'Authorization' header string.
tokenFromString (tokenToString token) == Just token
Describes an OAuth error response 4.1.2.1
InvalidRequest
: The request is missing a required parameter, includes an invalid parameter value,
includes a parameter more than once, or is otherwise malformed.
UnauthorizedClient
: The client is not authorized to request an authorization code using this
method.
AccessDenied
: The resource owner or authorization server denied the request.
UnsupportedResponseType
: The authorization server does not support obtaining an authorization code
using this method.
InvalidScope
: The requested scope is invalid, unknown, or malformed.
ServerError
: The authorization server encountered an unexpected condition that prevented it from
fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status
code cannot be returned to the client via an HTTP redirect.)
TemporarilyUnavailable
: The authorization server is currently unable to handle the request due to
a temporary overloading or maintenance of the server. (This error code is needed because a 503
Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)
Custom
: Encountered a 'free-string' or custom code not specified by the official RFC but returned
by the authorization server.
errorCodeToString : ErrorCode -> String
Get the String
representation of an ErrorCode
.
errorCodeFromString : String -> ErrorCode
Build a string back into an error code. Returns Custom _
when the string isn't recognized from the ones specified in the RFC
The following section can be ignored if you're dealing with a very generic OAuth2.0 implementation. If however, your authorization server does implement some extra features on top of the OAuth2.0 protocol (e.g. OpenID Connect), you will require to tweak response parsers and possibly, response type to cope with these discrepancies. In short, unless you're planning on using makeTokenRequestWith
or makeAuthorizationUrlWith
, you most probably won't need any of the functions below.
Describes the desired type of response to an authorization. Use Code
to ask for an
authorization code and continue with the according flow. Use Token
to do an implicit
authentication and directly retrieve a Token
from the authorization. If need be, you may provide a
custom response type should the server returns a non-standard response type.
responseTypeToString : ResponseType -> String
Gets the String
representation of a ResponseType
.
Describes the desired type of grant to an authentication.
grantTypeToString : GrantType -> String
Gets the String
representation of a GrantType
String
Alias for readability
String
Alias for readability
makeToken : Maybe TokenType -> Maybe TokenString -> Maybe Token
Create a token from two string representing a token type and an actual token value. This is intended to be used in Json decoders or Query parsers.
Returns Nothing
when the token type is Nothing
, different from Just "Bearer"
or when there's no token at all.
makeRefreshToken : TokenType -> Maybe TokenString -> Maybe (Maybe Token)
See makeToken
, with the subtle difference that a token value may or
may not be there.
Returns Nothing
when the token type isn't "Bearer"
.
Returns Just Nothing
or Just (Just token)
otherwise, depending on whether a token is
present or not.