servant-auth-wordpress-1.0.0.0: Authenticate Routes Using Wordpress Cookies

Safe HaskellNone
LanguageHaskell2010

Servant.Auth.Wordpress

Contents

Description

This module presents a Servant AuthHandler that validates a LOGGED_IN Wordpress Cookie & the "wp_rest" Nonce.

You'll need to build a WPAuthConfig for your application to pass to the wpAuthHandler function. The config defines some specifics about your Wordpress site, as well as functions to pull a User's authentication data & to handle authentication failures.

You must define the AuthServerData type instance yourself:

type instance "AuthServerData" ("AuthProtect" \"wp\") = WPAuthorization (Entity User)

For more information, be sure to check out the Generalized Authentication section of the servant tutorial.

If you want to build your own custom AuthHandler, check out the Wordpress.Auth module.

Synopsis

Auth Handlers

wpAuthHandler :: WPAuthConfig Handler a -> AuthHandler Request (WPAuthorization a) Source #

A Servant Authentication Handler that valiates a logged_in Cookie & a wp_rest Nonce.

wpAuthorizedOnlyHandler :: WPAuthConfig Handler a -> (WPAuthError -> Handler a) -> AuthHandler Request a Source #

This is similar to wpAuthHandler but it allows you to throw an error for anonymous users with valid nonces - restricting handlers to only logged in users.

data WPAuthorization a #

The result of the authorizeWordpressRequest function can be an authorized user with some additional data, or an anonymous user.

Instances
Eq a => Eq (WPAuthorization a) 
Instance details

Defined in Wordpress.Auth

Show a => Show (WPAuthorization a) 
Instance details

Defined in Wordpress.Auth

Configs

data WPAuthConfig (m :: Type -> Type) a #

Configuration data specific to your Wordpress site & Haskell application.

Constructors

WPAuthConfig 

Fields

data CookieName #

The name of a Wordpress authentication cookie. Wordpress's frontend uses CookieNameWithMD5 "wordpress_logged_in_" "<your-site-url>" by default.

Constructors

CustomCookieName Text

A constant name for the cookie.

CookieNameWithMD5 Text Text

A cookie name with some text to hash & append. E.g., Wordpress's logged_in auth scheme uses wordpress_logged_in_ suffixed with the MD5 hash of the siteurl option.

Instances
Eq CookieName 
Instance details

Defined in Wordpress.Auth

Show CookieName 
Instance details

Defined in Wordpress.Auth

data AuthScheme #

This represents one of the $schemes that Wordpress's cookie/nonce functions use to salt their hashes.

The built-in Wordpress schemes are auth/auth_sec for HTTP/HTTPS requests to wp-admin, logged_in for authenticated front-end requests, & nonce for form submissions & API requests.

The secret keys & salts are constants found in your wp-config.php file, defined as LOGGED_IN_SALT, LOGGED_IN_KEY, etc.

Instances
Eq AuthScheme 
Instance details

Defined in Wordpress.Auth

Show AuthScheme 
Instance details

Defined in Wordpress.Auth

data WordpressKey #

An auth scheme's _KEY constant, usually defined in your Wordpress site's wp-config.php. E.g., LOGGED_IN_KEY

Instances
Eq WordpressKey 
Instance details

Defined in Wordpress.Auth

Show WordpressKey 
Instance details

Defined in Wordpress.Auth

wpConfigKey :: Text -> WordpressKey #

Build the _KEY value for an authentiation scheme.

data WordpressSalt #

An auth scheme's _SALT constant, usually defined in your Wordpress site's wp-config.php. E.g., LOGGED_IN_SALT

Instances
Eq WordpressSalt 
Instance details

Defined in Wordpress.Auth

Show WordpressSalt 
Instance details

Defined in Wordpress.Auth

wpConfigSalt :: Text -> WordpressSalt #

Build the _SALT value for an authentiation scheme.

data UserAuthData a #

The data needed for authentication, along with some arbitrary data that is returned on success.

Constructors

UserAuthData 

Fields

  • userData :: a

    Arbitrary data that the validation should return. E.g., if you query your users table for the ID & user_pass, you can return your whole User type so you don't have to make another database call in your handler.

  • wpUser :: WordpressUserId

    The ID field of the User.

  • wpPass :: WordpressUserPass

    The user_pass field of the User.

  • wpTokens :: [SessionToken]

    The session_tokens usermeta for the User. You can use decodeSessionTokens to parse the raw meta value.

Instances
Eq a => Eq (UserAuthData a) 
Instance details

Defined in Wordpress.Auth

Show a => Show (UserAuthData a) 
Instance details

Defined in Wordpress.Auth

newtype WordpressUserId #

The ID field from the users table of a Wordpress site.

Constructors

WordpressUserId 

newtype WordpressUserPass #

The user_pass field from the users table of a Wordpress site.

Constructors

WordpressUserPass 

data SessionToken #

A User Session's Token. These can be found in the usermeta Wordpress table for rows where meta_key="session_token".

You'll probably want to use decodeSessionTokens to parse the tables's meta_value instead of constructing them yourself.

Instances
Eq SessionToken 
Instance details

Defined in Wordpress.Auth

Show SessionToken 
Instance details

Defined in Wordpress.Auth

decodeSessionTokens :: Text -> [SessionToken] #

Decode a serialized PHP array containing a User's Session Tokens. These are usually stored as the session_tokens usermeta.

It may be an associative array of tokens to expiration times, or tokens to an associative array of sub-fields:

array(
  'some-random-hex-text' => 192836504,
  // ...
);
array(
  'deadbeef ' => array(
    'expiration' => 9001,
    // ...
  ),
);

Errors

data WPAuthError #

Potential errors during authentication.

Constructors

EHeader CookieHeaderError

Header Error.

EParse CookieParseError

Parsing Error.

EValid CookieValidationError

Validation Error.

UserDataNotFound

The getUserData function returned Nothing.

NoNonce

The Request has no X-WP-Nonce header.

InvalidNonce

The nonce couldn't be validated.

Instances
Eq WPAuthError 
Instance details

Defined in Wordpress.Auth

Show WPAuthError 
Instance details

Defined in Wordpress.Auth

data CookieHeaderError #

Potential errors while searching for a specific cookie in the request headers.

Constructors

NoCookieHeader

The Request has no Cookie header.

NoCookieMatches

No Cookie matched the expected CookieName.

data CookieParseError #

Potential errors we may encounter while parsing a WPCookie.

Constructors

MalformedCookie

The cookie did not have 4 fields separated by `|` characters.

InvalidExpiration

The expiration field of the cookie is not an Integer.

data CookieValidationError #

Potential validation errors for a WPCookie.

Constructors

CookieExpired

The expiration time of the cookie is in the past.

InvalidHash

The hmac hash in the cookie doesn't match the calculated hash.

InvalidToken

The token in the cookie is not valid or expired.