Wordpress.Auth

The Wordpress.Auth module is used for checking the validity of various Wordpress authentication schemes.

This is useful if you want a Haskell application to be able to serve authenticated API requests to a Wordpress site without having to devise a Wordpress-to-Haskell authentication system.

You will need some constants from your Wordpress site's wp-config.php, like the NONCE_KEY & NONCE_SALT, you could supply these via environmental variables:

 loggedInScheme <- AuthScheme
     <$> (wpConfigKey . T.pack <$> getEnv "LOGGED_IN_KEY")
     <*> (wpConfigSalt . T.pack <$> getEnv "LOGGED_IN_SALT")

Then you'll want to pull the specific cookie's text out of the Cookie header(see findCookie) & use then parseWordpressCookie to build a WPCookie. You should then use the username field of the cookie to query your Wordpress database for the User's ID(WordpressUserId) & user_pass(WordpressUserPass) fields as well as the session_tokens User Meta(SessionToken).

Equiped with these and the current time(via getPOSIXTime), you can then validate the cookie:

 passwordFragment = WordpressUserPass myUserTablesUserPassFieldValue
 sessionTokens    = decodeSessionTokens myUserMetaTablesSessionTokensMetaValue
 cookieIsValid    = validateCookie loggedInScheme currentTime cookie
                                   passwordFragment sessionTokens

If this is a REST request or a form submission, you should always validate the nonce, even for requests with no auth cookies. The nonce can be pulled out of the X-WP-Nonce header or the _wpnonce query parameter.

 nonceTick     <- wordpressNonceTick (60 * 60 * 24) currentTime
 let validNonce = validateNonce nonceScheme (Just cookie) nonceTick
                                (Just $ WordpressUserId userId)
                                "wp_rest" myNonceText

Request Handling

authorizeWordpressRequest :: forall m a. MonadIO m => WPAuthConfig m a -> RequestHeaders -> [QueryItem] -> m (WPAuthorization a)

The is a generalized authentication verification scheme that authorizes a user if the logged_in cookie is set and valid, & verifies the wp_rest nonce action for both authorized & anonymous users.

The WPAuthConfig failure handler will be used if a Cookie is present but invalid or if the nonce is missing/invalid.

data WPAuthConfig m a

Configuration data specific to your Wordpress site & Haskell application.

Constructors

WPAuthConfig

Fields

• getCookieName :: m CookieName

  A monadic action that generates a CookieName. You can simply return a constant value, or do something more complex like querying your database for the siteurl option.

• loggedInScheme :: AuthScheme

  The LOGGED_IN_KEY & LOGGED_IN_SALT from your wp-config.php.

• nonceScheme :: AuthScheme

  The NONCE_KEY & NONCE_SALT from your wp-config.php.

• nonceLifetime :: NominalDiffTime

  The nonce lifetime of your Wordpress site. Wordpress defaults to 1 day.

• getUserData :: Text -> m (Maybe (UserAuthData a))

  A function to pull your custom data & the user data needed for authentication. See the UserAuthData type.

• onAuthenticationFailure :: WPAuthError -> m (WPAuthorization a)

  How to handle authentication failures. You might want to throw an HTTP error or simply treat the user as unauthenticated.

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)

Defined in Wordpress.Auth

Methods

(==) :: UserAuthData a -> UserAuthData a -> Bool

(/=) :: UserAuthData a -> UserAuthData a -> Bool

Show a => Show (UserAuthData a)

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> UserAuthData a -> ShowS

show :: UserAuthData a -> String

showList :: [UserAuthData a] -> ShowS

data WPAuthorization a

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

Constructors

WPAuthorizedUser a

WPAnonymousUser

Instances

Eq a => Eq (WPAuthorization a)

Defined in Wordpress.Auth

Methods

(==) :: WPAuthorization a -> WPAuthorization a -> Bool

(/=) :: WPAuthorization a -> WPAuthorization a -> Bool

Show a => Show (WPAuthorization a)

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> WPAuthorization a -> ShowS

show :: WPAuthorization a -> String

showList :: [WPAuthorization a] -> ShowS

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

Defined in Wordpress.Auth

Methods

(==) :: WPAuthError -> WPAuthError -> Bool

(/=) :: WPAuthError -> WPAuthError -> Bool

Show WPAuthError

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> WPAuthError -> ShowS

show :: WPAuthError -> String

showList :: [WPAuthError] -> ShowS

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

Defined in Wordpress.Auth

Methods

(==) :: CookieName -> CookieName -> Bool

(/=) :: CookieName -> CookieName -> Bool

Show CookieName

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> CookieName -> ShowS

show :: CookieName -> String

showList :: [CookieName] -> ShowS

cookieName :: CookieName -> Text

Build the name of an authentication cookie from a CookieName, hashing the suffix if present.

findCookie :: CookieName -> RequestHeaders -> Either CookieHeaderError Text

Try to find & decode a Cookie in the headers with the given name.

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.

Instances

Eq CookieHeaderError

Defined in Wordpress.Auth

Methods

(==) :: CookieHeaderError -> CookieHeaderError -> Bool

(/=) :: CookieHeaderError -> CookieHeaderError -> Bool

Show CookieHeaderError

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> CookieHeaderError -> ShowS

show :: CookieHeaderError -> String

showList :: [CookieHeaderError] -> ShowS

findNonce :: RequestHeaders -> [QueryItem] -> Maybe Text

Try to find & decode a Nonce in either the X-WP-Nonce header or the _wpnonce query parameter.

Cookies

data WPCookie

This represents a Cookie set by a Wordpress authentication scheme (auth, auth_sec, & logged_in).

Constructors

WPCookie

Fields

• username :: Text

  The user_login column for the Wordpress User.

• expiration :: POSIXTime

  The expiration time of the Cookie.

• token :: CookieToken

  The Wordpress User's session token.

• hmac :: Text

  A SHA256 HMAC hash of the token & some user data.

Instances

Eq WPCookie

Defined in Wordpress.Auth

Methods

(==) :: WPCookie -> WPCookie -> Bool

(/=) :: WPCookie -> WPCookie -> Bool

Show WPCookie

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> WPCookie -> ShowS

show :: WPCookie -> String

showList :: [WPCookie] -> ShowS

newtype CookieToken

A User's Wordpress Session Token from an auth cookie.

Constructors

CookieToken

Fields

• cookieToken :: Text

Instances

Eq CookieToken

Defined in Wordpress.Auth

Methods

(==) :: CookieToken -> CookieToken -> Bool

(/=) :: CookieToken -> CookieToken -> Bool

Show CookieToken

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> CookieToken -> ShowS

show :: CookieToken -> String

showList :: [CookieToken] -> ShowS

parseWordpressCookie :: Text -> Either CookieParseError WPCookie

Parse a WPCookie from the body text of an auth, auth_sec, or logged_in cookie.

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.

Instances

Eq CookieParseError

Defined in Wordpress.Auth

Methods

(==) :: CookieParseError -> CookieParseError -> Bool

(/=) :: CookieParseError -> CookieParseError -> Bool

Show CookieParseError

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> CookieParseError -> ShowS

show :: CookieParseError -> String

showList :: [CookieParseError] -> ShowS

validateCookie

Arguments

:: AuthScheme

They _KEY & _SALT constants for a WP auth scheme.

-> POSIXTime

The current time.

-> WPCookie

The cookie to validate.

-> WordpressUserPass

The user_pass field for the cookie's user.

-> [SessionToken]

The session_tokens meta for the cookie's user.

-> Either CookieValidationError ()

Validate a Wordpress Authentication Cookie by verifying that the hash & token in the cookie are valid and the expiration time is in the future.

newtype WordpressUserPass

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

Constructors

WordpressUserPass

Fields

• wordpressUserPass :: Text

Instances

Eq WordpressUserPass

Defined in Wordpress.Auth

Methods

(==) :: WordpressUserPass -> WordpressUserPass -> Bool

(/=) :: WordpressUserPass -> WordpressUserPass -> Bool

Show WordpressUserPass

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> WordpressUserPass -> ShowS

show :: WordpressUserPass -> String

showList :: [WordpressUserPass] -> ShowS

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.

Instances

Eq CookieValidationError

Defined in Wordpress.Auth

Methods

(==) :: CookieValidationError -> CookieValidationError -> Bool

(/=) :: CookieValidationError -> CookieValidationError -> Bool

Show CookieValidationError

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> CookieValidationError -> ShowS

show :: CookieValidationError -> String

showList :: [CookieValidationError] -> ShowS

validateCookieHash :: AuthScheme -> WPCookie -> WordpressUserPass -> Bool

Determine if a WPCookie's hash matches the hashed password & token.

A secret is generated by hashing the user, password, expiration, & token. This secret is then used to hash the user, expiration, & token. The resulting hash should match the hmac hash in the WPCookie.

Session Tokens

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.

Constructors

SessionToken

Fields

• sessionToken :: Text
• tokenExpiration :: POSIXTime

Instances

Eq SessionToken

Defined in Wordpress.Auth

Methods

(==) :: SessionToken -> SessionToken -> Bool

(/=) :: SessionToken -> SessionToken -> Bool

Show SessionToken

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> SessionToken -> ShowS

show :: SessionToken -> String

showList :: [SessionToken] -> ShowS

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,
    // ...
  ),
);

validateSessionToken

Arguments

:: POSIXTime

The current time

-> CookieToken

The session token from a WPCookie

-> [SessionToken]

A list of the User's session tokens

-> Bool

Determine if the SHA256 hash of the token matches one of the unexpired session tokens.

Nonces

newtype NonceTick

The tick number of a Wordpress site - required for Nonce verification.

Constructors

NonceTick

Fields

• tickCount :: Integer

Instances

Eq NonceTick

Defined in Wordpress.Auth

Methods

(==) :: NonceTick -> NonceTick -> Bool

(/=) :: NonceTick -> NonceTick -> Bool

Show NonceTick

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> NonceTick -> ShowS

show :: NonceTick -> String

showList :: [NonceTick] -> ShowS

wordpressNonceTick

Arguments

:: NominalDiffTime

The nonce lifetime. Wordpress's default is 1 day.

-> POSIXTime

The current time.

-> NonceTick

A port of the wp_nonce_tick function. Calculates the nonce tick number, where each nonce has a lifetime of two ticks.

validateNonce

Arguments

:: AuthScheme

The Wordpress site's nonce scheme constants - NONCE_KEY & NONCE_SALT.

-> Maybe CookieToken

A token from the logged_in cookie.

-> NonceTick

The current tick number.

-> Maybe WordpressUserId

The ID of the currently logged in User.

-> Text

The action of the nonce (e.g., "wp_rest" for API requests).

-> Text

The nonce to verify.

-> Bool

Determine if the tick-dependent hash of the CookieToken matches the hash of the current or previous tick.

newtype WordpressUserId

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

Constructors

WordpressUserId

Fields

• wordpressUserId :: Integer

Instances

Eq WordpressUserId

Defined in Wordpress.Auth

Methods

(==) :: WordpressUserId -> WordpressUserId -> Bool

(/=) :: WordpressUserId -> WordpressUserId -> Bool

Show WordpressUserId

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> WordpressUserId -> ShowS

show :: WordpressUserId -> String

showList :: [WordpressUserId] -> ShowS

Hashing / Salting

wordpressHash :: AuthScheme -> Text -> Text

A port of the wp_hash function. This performs an hmac hash on some text using a secret derived from the authentication scheme's key & salt constants.

wordpressSalt :: AuthScheme -> Text

A port of the wp_salt function. Builds a secret key for a hashing function using the auth scheme's key & salt.

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.

Constructors

AuthScheme

Fields

• schemeKey :: WordpressKey
• schemeSalt :: WordpressSalt

Instances

Eq AuthScheme

Defined in Wordpress.Auth

Methods

(==) :: AuthScheme -> AuthScheme -> Bool

(/=) :: AuthScheme -> AuthScheme -> Bool

Show AuthScheme

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> AuthScheme -> ShowS

show :: AuthScheme -> String

showList :: [AuthScheme] -> ShowS

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

Defined in Wordpress.Auth

Methods

(==) :: WordpressKey -> WordpressKey -> Bool

(/=) :: WordpressKey -> WordpressKey -> Bool

Show WordpressKey

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> WordpressKey -> ShowS

show :: WordpressKey -> String

showList :: [WordpressKey] -> ShowS

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

Defined in Wordpress.Auth

Methods

(==) :: WordpressSalt -> WordpressSalt -> Bool

(/=) :: WordpressSalt -> WordpressSalt -> Bool

Show WordpressSalt

Defined in Wordpress.Auth

Methods

showsPrec :: Int -> WordpressSalt -> ShowS

show :: WordpressSalt -> String

showList :: [WordpressSalt] -> ShowS

wpConfigKey :: Text -> WordpressKey

Build the _KEY value for an authentiation scheme.

wpConfigSalt :: Text -> WordpressSalt

Build the _SALT value for an authentiation scheme.