truqu / elm-oauth2 / OAuth.Implicit

⚠ (DEPRECATED) ⚠ You should probably look into OAuth.AuthorizationCode instead.

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. These clients are typically implemented in a browser using a scripting language such as JavaScript.

Quick Start

To get started, have a look at the live-demo and its corresponding source code.

Overview

   +---------+                                +--------+
   |         |---(A)- Auth Redirection ------>|        |
   |         |                                |  Auth  |
   | Browser |                                | Server |
   |         |                                |        |
   |         |<--(B)- Redirection Callback ---|        |
   +---------+        w/ Access Token         +--------+
     ^     |
     |     |
    (A)   (B)
     |     |
     |     v
   +---------+
   |         |
   | Elm App |
   |         |
   |         |
   +---------+

After those steps, the client owns a Token that can be used to authorize any subsequent request.

Authorize

makeAuthorizationUrl : Authorization -> Url

Redirects the resource owner (user) to the resource provider server using the specified authorization flow.


type alias Authorization =
{ clientId : String
, url : Url
, redirectUri : Url
, scope : List String
, state : Maybe String 
}

Request configuration for an authorization

parseToken : Url -> AuthorizationResult

Parses the location looking for parameters in the fragment set by the authorization server after redirecting the resource owner (user).

Returns ParseResult Empty when there's nothing or an invalid Url is passed


type alias AuthorizationResult =
AuthorizationResultWith AuthorizationError AuthorizationSuccess

Describes errors coming from attempting to parse a url after an OAuth redirection.


type AuthorizationResultWith error success
    = Empty
    | Error error
    | Success success

A parameterized AuthorizationResult, see parseTokenWith.


type alias AuthorizationError =
{ error : OAuth.ErrorCode
, errorDescription : Maybe String
, errorUri : Maybe String
, state : Maybe String 
}

Describes an OAuth error as a result of an authorization request failure


type alias AuthorizationSuccess =
{ token : OAuth.Token
, refreshToken : Maybe OAuth.Token
, expiresIn : Maybe Basics.Int
, scope : List String
, state : Maybe String 
}

The response obtained as a result of an authentication (implicit or not)

Custom Parsers (advanced)

makeAuthorizationUrlWith : OAuth.ResponseType -> Dict String String -> Authorization -> Url

Like makeAuthorizationUrl, but gives you the ability to specify a custom response type and extra fields to be set on the query.

makeAuthorizationUrl : Authorization -> Url
makeAuthorizationUrl =
    makeAuthorizationUrlWith Token Dict.empty

For example, to interact with a service implementing OpenID+Connect you may require a different token type and an extra query parameter as such:

makeAuthorizationUrlWith
    (CustomResponse "token+id_token")
    (Dict.fromList [ ( "resource", "001" ) ])
    authorization

parseTokenWith : Parsers error success -> Url -> AuthorizationResultWith error success

Like parseToken, but gives you the ability to provide your own custom parsers.

This is especially useful when interacting with authorization servers that don't quite implement the OAuth2.0 specifications.

parseToken : Url -> AuthorizationResultWith AuthorizationError AuthorizationSuccess
parseToken =
    parseTokenWith defaultParsers


type alias Parsers error success =
{ tokenParser : Url.Parser.Query.Parser (Maybe OAuth.Token)
, errorParser : Url.Parser.Query.Parser (Maybe OAuth.ErrorCode)
, authorizationSuccessParser : OAuth.Token -> Url.Parser.Query.Parser success
, authorizationErrorParser : OAuth.ErrorCode -> Url.Parser.Query.Parser error 
}

Parsers used in the parseToken function.

defaultParsers : Parsers AuthorizationError AuthorizationSuccess

Default parsers according to RFC-6749.

defaultTokenParser : Url.Parser.Query.Parser (Maybe OAuth.Token)

Default access_token parser according to RFC-6749.

defaultErrorParser : Url.Parser.Query.Parser (Maybe OAuth.ErrorCode)

Default error parser according to RFC-6749.

defaultAuthorizationSuccessParser : OAuth.Token -> Url.Parser.Query.Parser AuthorizationSuccess

Default response success parser according to RFC-6749.

defaultAuthorizationErrorParser : OAuth.ErrorCode -> Url.Parser.Query.Parser AuthorizationError

Default response error parser according to RFC-6749.