Portability | non-portable |
---|---|
Stability | experimental |
Maintainer | me@jspha.com |
Safe Haskell | None |
OAuth tools for using http-client
for authenticated requests.
The functions here form the simplest basis for sending OAuthenticated
Request
s. In order to generate credentials according to the OAuth
three-legged workflow use actions in the Network.OAuth.ThreeLegged
module.
- oauthSimple :: Cred ty -> Server -> Request -> IO Request
- oauth :: CPRG gen => Cred ty -> Server -> Request -> gen -> IO (Request, gen)
- sign :: Oa ty -> Server -> Request -> Request
- emptyOa :: Cred ty -> Oa ty
- freshOa :: CPRG gen => Cred ty -> gen -> IO (Oa ty, gen)
- emptyPin :: OaPin
- freshPin :: CPRG gen => gen -> IO (OaPin, gen)
- data Token ty = Token !Key !Secret
- data Cred ty
- data Client
- data Temporary
- data Permanent
- clientCred :: Token Client -> Cred Client
- temporaryCred :: Token Temporary -> Cred Client -> Cred Temporary
- permanentCred :: Token Permanent -> Cred Client -> Cred Permanent
- fromUrlEncoded :: ByteString -> Maybe (Bool, Token ty)
- data Server = Server {}
- defaultServer :: Server
- data ParameterMethod
- data SignatureMethod
- data Version
Authenticating a request
The oauthSimple
function can be used to sign a Request
as it
stands. It should be performed just before the Request
is used as
it uses the current timestamp and thus may only be valid for a limited
amount of time.
oauthSimple
creates a new random entropy pool every time it is
called, thus it can be both slow and cryptographically dangerous to
use it repeatedly as it can drain system entropy. Instead, the plain oauth
function should be used which allows for threading of the random
source.
oauth :: CPRG gen => Cred ty -> Server -> Request -> gen -> IO (Request, gen)Source
Sign a request with a fresh set of parameters.
Lower-level and pure functionality
When necessary to control or observe the signature more
carefully, the lower level API can be used. This requires generating
a fresh set of Oa
parameters from a relevant or deterministic
OaPin
and then using sign
to sign the Request
.
Generating OAuth parameters
An "empty" pin useful for testing. This OaPin
is referentially
transparent and thus has none of the necessary security features---it should
never be used in an actual transaction!
freshPin :: CPRG gen => gen -> IO (OaPin, gen)Source
Creates a new, unique, unpredictable OaPin
. This should be used quickly
as dependent on the OAuth server settings it may expire.
OAuth Credentials
Typeable1 Token | |
Eq (Token ty) | |
Data ty => Data (Token ty) | |
Ord (Token ty) | |
Show (Token ty) | |
ToJSON (Token ty) | Produces a JSON object using keys named |
FromJSON (Token ty) | Parses a JSON object with keys |
Temporary
Token
s and Cred
entials are created during authorization
protocols and are rarely meant to be kept for more than a few minutes.
Typically they are authorized to access only a very select set of server
resources. During "three-legged authorization" in OAuth 1.0 they are used
to generate the authorization request URI the client sends and, after that,
in the Permanent
Token
request.
Creating Credentials
fromUrlEncoded :: ByteString -> Maybe (Bool, Token ty)Source
Parses a www-form-urlencoded
stream to produce a Token
if possible.
The first result value is whether or not the token data is OAuth 1.0a
compatible.
>>>
fromUrlEncoded "oauth_token=key&oauth_token_secret=secret"
Just (False, Token "key" "secret")
>>>
fromUrlEncoded "oauth_token=key&oauth_token_secret=secret&oauth_callback_confirmed=true"
Just (True, Token "key" "secret")
OAuth Configuration
The Server
information contains details which parameterize how a
particular server wants to interpret OAuth requests.
The default Server
parameterization uses OAuth recommended parameters.
data ParameterMethod Source
The OAuth spec suggest that the OAuth parameter be passed via the
Authorization
header, but allows for other methods of
transmission (see section 3.5. Parameter Transmission) so we
select the 'Server'\'s preferred method with this type.
AuthorizationHeader | Place the |
RequestEntityBody | Augment the |
QueryString | Augment the |
data SignatureMethod Source
OAuth has progressed through several versions since its inception. In particular, there are two community editions "OAuth Core 1.0" (2007) and "OAuth Core 1.0a" (2009) along with the IETF Official version RFC 5849 (2010) which is confusingly named OAuth 1.0.
/Servers which only implement the obsoleted community edition "OAuth Core 1.0" are susceptible to a session fixation attack./
If at all possible, choose the RFC 5849 version (the OAuth1
value) as
it is the modern standard. Some servers may only be compliant with an
earlier OAuth version---this should be tested against each server, in
particular the protocols defined in Network.OAuth.ThreeLegged.
OAuthCommunity1 | OAuth Core 1.0 Community Edition |
OAuthCommunity1a | OAuth Core 1.0 Community Edition, Revision A |
OAuth1 | RFC 5849 |