OAuth.AuthorizationCode

The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

This is a 3-step process:

The client asks for an authorization to the OAuth provider: the user is redirected.
The provider redirects the user back and the client parses the request query parameters from the url.
The client authenticate itself using the authorization code found in the previous step.

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

Authorize

type alias Authorization =

{ clientId : String

, url : Url

, redirectUri : Url

, scope : List String

, state : Maybe String

}

Request configuration for an authorization (Authorization Code & Implicit flows)

type AuthorizationResult

= Empty

| Error AuthorizationError

| Success AuthorizationSuccess

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

Empty: means there were nothing (related to OAuth 2.0) to parse
Error: a successfully parsed OAuth 2.0 error
Success: a successfully parsed the response

type alias AuthorizationSuccess =

{ code : String

, state : Maybe String

}

The response obtained as a result of an authorization

code (REQUIRED): The authorization code generated by the authorization server. The authorization code MUST expire shortly after it is issued to mitigate the risk of leaks. A maximum authorization code lifetime of 10 minutes is RECOMMENDED. The client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the authorization server MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorization code. The authorization code is bound to the client identifier and redirection URI.
state (REQUIRED if state was present in the authorization request): The exact value received from the client

type alias AuthorizationError =

{ error : ErrorCode

, errorDescription : Maybe String

, errorUri : Maybe String

, state : Maybe String

}

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

error (REQUIRED): A single ASCII error code.
errorDescription (OPTIONAL) Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the errorDescription parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
errorUri (OPTIONAL): A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the errorUri parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E.
state (REQUIRED if state was present in the authorization request): The exact value received from the client

parseCode : Url -> AuthorizationResult

Parse the location looking for a parameters set by the resource provider server after redirecting the resource owner (user).

Returns AuthorizationResult Empty when there's nothing

makeAuthUrl : Authorization -> Url

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

Authorize (advanced)

parseCodeWith : Parsers -> Url -> AuthorizationResult

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

Authenticate

type alias Authentication =

{ credentials : Credentials

, code : String

, redirectUri : Url

, url : Url

}

Request configuration for an AuthorizationCode authentication

let authentication =
      { credentials =
          -- Only the clientId is required. Specify a secret
          -- if a Basic OAuth is required by the resource
          -- provider
          { clientId = "<my-client-id>"
          , secret = Nothing
          }
      -- Authorization code from the authorization result
      , code = "<authorization-code>"
      -- Token endpoint of the resource provider
      , url = "<token-endpoint>"
      -- Redirect Uri to your webserver
      , redirectUri = "<my-web-server>"
      }

type alias Credentials =

{ clientId : String

, secret : Maybe String

}

Describes at least a clientId and if define, a complete set of credentials with the secret. The secret is so-to-speak optional and depends on whether the authorization server you interact with requires a 'Basic' authentication on top of the authentication request. Provides it if you need to do so.

  { clientId = "<my-client-id>"
  , secret = Just "<my-client-secret>"
  }

type alias AuthenticationSuccess =

{ token : Token

, refreshToken : Maybe Token

, expiresIn : Maybe Int

, scope : List String

}

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

token (REQUIRED): The access token issued by the authorization server.
refreshToken (OPTIONAL): The refresh token, which can be used to obtain new access tokens using the same authorization grant as described in Section 6.
expiresIn (RECOMMENDED): The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value.
scope (OPTIONAL, if identical to the scope requested; otherwise, REQUIRED): The scope of the access token as described by Section 3.3.

type alias AuthenticationError =

{ error : ErrorCode

, errorDescription : Maybe String

, errorUri : Maybe String

}

Describes an OAuth error as a result of a request failure

error (REQUIRED): A single ASCII error code.
errorDescription (OPTIONAL) Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the errorDescription parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
errorUri (OPTIONAL): A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the errorUri parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E.

type alias RequestParts a =

{ method : String

, headers : List Header

, url : String

, body : Body

, expect : Expect a

, timeout : Maybe Float

, withCredentials : Bool

}

Parts required to build a request. This record is given to Http.request in order to create a new request and may be adjusted at will.

makeTokenRequest : Authentication -> RequestParts AuthenticationSuccess

Builds a the request components required to get a token from an authorization code

let req : Http.Request AuthenticationSuccess
    req = makeTokenRequest authentication |> Http.request

Query Parsers

type alias Parsers =

{ codeParser : Parser (Maybe String)

, errorParser : Parser (Maybe ErrorCode)

, authorizationSuccessParser :

String -> Parser AuthorizationSuccess

, authorizationErrorParser : ErrorCode -> Parser AuthorizationError

}

Parsers used in the 'parseCode' function.

codeParser: Looks for an 'code' string
errorParser: Looks for an 'error' to build a corresponding ErrorCode
authorizationSuccessParser: Selected when the tokenParser succeeded to parse the remaining parts
authorizationErrorParser: Selected when the errorParser succeeded to parse the remaining parts

defaultParsers : Parsers

Default parsers according to RFC-6749

defaultCodeParser : Parser (Maybe String)

Default 'code' parser according to RFC-6749

defaultErrorParser : Parser (Maybe ErrorCode)

Default 'error' parser according to RFC-6749

defaultAuthorizationSuccessParser : String -> Parser AuthorizationSuccess

Default response success parser according to RFC-6749

defaultAuthorizationErrorParser : ErrorCode -> Parser AuthorizationError

Default response error parser according to RFC-6749

Json Decoders

defaultAuthenticationSuccessDecoder : Decoder AuthenticationSuccess

Json decoder for a positive response. You may provide a custom response decoder using other decoders from this module, or some of your own craft.

defaultAuthenticationErrorDecoder : Decoder AuthenticationError

Json decoder for an errored response.

case res of
    Err (Http.BadStatus { body }) ->
        case Json.decodeString OAuth.AuthorizationCode.defaultAuthenticationErrorDecoder body of
            Ok { error, errorDescription } ->
                doSomething


            _ ->
                parserFailed


    _ ->
        someOtherError

defaultExpiresInDecoder : Decoder (Maybe Int)

Json decoder for an 'expire' timestamp

defaultScopeDecoder : Decoder (List String)

Json decoder for a 'scope'

lenientScopeDecoder : Decoder (List String)

Json decoder for a 'scope', allowing comma- or space-separated scopes

defaultTokenDecoder : Decoder Token

Json decoder for an 'access_token'

defaultRefreshTokenDecoder : Decoder (Maybe Token)

Json decoder for a 'refresh_token'

defaultErrorDecoder : Decoder ErrorCode

Json decoder for 'error' field