truqu / elm-oauth2 / OAuth

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:

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.

Token


type Token

Describes the type of access token to use.

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

ErrorCode


type ErrorCode
    = InvalidRequest
    | UnauthorizedClient
    | AccessDenied
    | UnsupportedResponseType
    | InvalidScope
    | ServerError
    | TemporarilyUnavailable
    | Custom String

Describes an OAuth error response 4.1.2.1

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

Response & Grant types (Advanced)

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.


type ResponseType
    = Code
    | Token
    | CustomResponse String

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.


type GrantType
    = AuthorizationCode
    | Password
    | ClientCredentials
    | RefreshToken
    | CustomGrant String

Describes the desired type of grant to an authentication.

grantTypeToString : GrantType -> String

Gets the String representation of a GrantType

Decoders & Parsers Utils (advanced)


type alias TokenType =
String

Alias for readability


type alias TokenString =
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.