MediaWiki  master
MediaWiki\Session\CookieSessionProvider Class Reference

A CookieSessionProvider persists sessions using cookies. More...

Inheritance diagram for MediaWiki\Session\CookieSessionProvider:
Collaboration diagram for MediaWiki\Session\CookieSessionProvider:

Public Member Functions

 __construct ( $params=[])
 
 canChangeUser ()
 Indicate whether the user associated with the request can be changed. More...
 
 getRememberUserDuration ()
 Returns the duration (in seconds) for which users will be remembered when Session::setRememberUser() is set. More...
 
 getVaryCookies ()
 Return the list of cookies that need varying on. More...
 
 persistSession (SessionBackend $session, WebRequest $request)
 Persist a session into a request/response. More...
 
 persistsSessionId ()
 Indicate whether self::persistSession() can save arbitrary session IDs. More...
 
 provideSessionInfo (WebRequest $request)
 Provide session info for a request. More...
 
 setConfig (Config $config)
 Set configuration. More...
 
 suggestLoginUsername (WebRequest $request)
 Get a suggested username for the login form Stable to override. More...
 
 unpersistSession (WebRequest $request)
 Remove any persisted session from a request/response. More...
 
 whyNoSession ()
 Return a Message for why sessions might not be being persisted.For example, "check whether you're blocking our cookies".
Returns
Message|null
Stable to override Stable to override More...
 
- Public Member Functions inherited from MediaWiki\Session\SessionProvider
 __construct ()
 Stable to call. More...
 
 __toString ()
 
 describe (Language $lang)
 Return an identifier for this session type.
Parameters
Language$langLanguage to use.
Returns
string
Stable to override More...
 
 getAllowedUserRights (SessionBackend $backend)
 Fetch the rights allowed the user when the specified session is active. More...
 
 getManager ()
 Get the session manager. More...
 
 getVaryHeaders ()
 Return the HTTP headers that need varying on. More...
 
 invalidateSessionsForUser (User $user)
 Invalidate existing sessions for a user. More...
 
 mergeMetadata (array $savedMetadata, array $providedMetadata)
 Merge saved session provider metadata. More...
 
 newSessionInfo ( $id=null)
 Provide session info for a new, empty session. More...
 
 preventSessionsForUser ( $username)
 Prevent future sessions for the user. More...
 
 refreshSessionInfo (SessionInfo $info, WebRequest $request, &$metadata)
 Validate a loaded SessionInfo and refresh provider metadata. More...
 
 safeAgainstCsrf ()
 Most session providers require protection against CSRF attacks (usually via CSRF tokens) More...
 
 sessionIdWasReset (SessionBackend $session, $oldId)
 Notification that the session ID was reset. More...
 
 setHookContainer ( $hookContainer)
 Set the hook container. More...
 
 setLogger (LoggerInterface $logger)
 
 setManager (SessionManager $manager)
 Set the session manager. More...
 

Protected Member Functions

 cookieDataToExport ( $user, $remember)
 Return the data to store in cookies. More...
 
 getCookie ( $request, $key, $prefix, $default=null)
 Get a cookie. More...
 
 getExtendedLoginCookies ()
 Gets the list of cookies that must be set to the 'remember me' duration, if $wgExtendedLoginCookieExpiration is in use. More...
 
 getLoginCookieExpiration ( $cookieName, $shouldRememberUser)
 Returns the lifespan of the login cookies, in seconds. More...
 
 getUserInfoFromCookies ( $request)
 Fetch the user identity from cookies. More...
 
 sessionDataToExport ( $user)
 Return extra data to store in the session. More...
 
 setForceHTTPSCookie ( $set, ?SessionBackend $backend, WebRequest $request)
 Set the "forceHTTPS" cookie, unless $wgForceHTTPS prevents it. More...
 
 setLoggedOutCookie ( $loggedOut, WebRequest $request)
 Set the "logged out" cookie. More...
 
- Protected Member Functions inherited from MediaWiki\Session\SessionProvider
 describeMessage ()
 Return a Message identifying this session type. More...
 
 getHookContainer ()
 Get the HookContainer. More...
 
 getHookRunner ()
 Get the HookRunner. More...
 
 hashToSessionId ( $data, $key=null)
 Hash data as a session ID. More...
 

Protected Attributes

mixed[] $cookieOptions = []
 
mixed[] $params = []
 
bool $useCrossSiteCookies
 
- Protected Attributes inherited from MediaWiki\Session\SessionProvider
Config $config
 
LoggerInterface $logger
 
SessionManager $manager
 
int $priority
 Session priority. More...
 

Detailed Description

A CookieSessionProvider persists sessions using cookies.

Since
1.27

Definition at line 36 of file CookieSessionProvider.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Session\CookieSessionProvider::__construct (   $params = [])
Parameters
array$paramsKeys include:
  • priority: (required) Priority of the returned sessions
  • callUserSetCookiesHook: Whether to call the deprecated hook
  • sessionName: Session cookie name. Doesn't honor 'prefix'. Defaults to $wgSessionName, or $wgCookiePrefix . '_session' if that is unset.
  • cookieOptions: Options to pass to WebRequest::setCookie():
    • prefix: Cookie prefix, defaults to $wgCookiePrefix
    • path: Cookie path, defaults to $wgCookiePath
    • domain: Cookie domain, defaults to $wgCookieDomain
    • secure: Cookie secure flag, defaults to $wgCookieSecure
    • httpOnly: Cookie httpOnly flag, defaults to $wgCookieHttpOnly
    • sameSite: Cookie SameSite attribute, defaults to $wgCookieSameSite

Definition at line 61 of file CookieSessionProvider.php.

References MediaWiki\Session\CookieSessionProvider\$params, MediaWiki\Session\SessionInfo\MAX_PRIORITY, and MediaWiki\Session\SessionInfo\MIN_PRIORITY.

Member Function Documentation

◆ canChangeUser()

MediaWiki\Session\CookieSessionProvider::canChangeUser ( )

Indicate whether the user associated with the request can be changed.

If false, any session passed to self::persistSession() will have a user that was originally provided by self::provideSessionInfo(). Further, self::provideSessionInfo() may only provide sessions that have a user already set.

If true, the provider may be passed sessions with arbitrary users, and will be expected to manipulate the request in such a way that future requests will cause self::provideSessionInfo() to provide a SessionInfo with that ID. This can be as simple as not passing any 'userInfo' into SessionInfo's constructor, in which case SessionInfo will load the user from the saved session's metadata.

For example, a session provider for OAuth or SSL client certificates would function by matching the OAuth headers or certificate to a particular user, and thus would return false here since it can't arbitrarily assign those OAuth credentials or that certificate to a different user. A session provider that shoves information into cookies, on the other hand, could easily do so.

Note
For use by \MediaWiki\Session\SessionBackend only
Returns
bool

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 194 of file CookieSessionProvider.php.

◆ cookieDataToExport()

MediaWiki\Session\CookieSessionProvider::cookieDataToExport (   $user,
  $remember 
)
protected

Return the data to store in cookies.

Parameters
User$user
bool$remember
Returns
array $cookies Set value false to unset the cookie

Definition at line 379 of file CookieSessionProvider.php.

Referenced by MediaWiki\Session\CookieSessionProvider\persistSession().

◆ getCookie()

MediaWiki\Session\CookieSessionProvider::getCookie (   $request,
  $key,
  $prefix,
  $default = null 
)
protected

Get a cookie.

Contains an auth-specific hack.

Parameters
\\WebRequest$request
string$key
string$prefix
mixed | null$default
Returns
mixed

Definition at line 356 of file CookieSessionProvider.php.

Referenced by MediaWiki\Session\CookieSessionProvider\getUserInfoFromCookies(), MediaWiki\Session\CookieSessionProvider\provideSessionInfo(), MediaWiki\Session\CookieSessionProvider\setLoggedOutCookie(), and MediaWiki\Session\CookieSessionProvider\suggestLoginUsername().

◆ getExtendedLoginCookies()

MediaWiki\Session\CookieSessionProvider::getExtendedLoginCookies ( )
protected

Gets the list of cookies that must be set to the 'remember me' duration, if $wgExtendedLoginCookieExpiration is in use.

Returns
string[] Array of unprefixed cookie keys

Definition at line 428 of file CookieSessionProvider.php.

Referenced by MediaWiki\Session\CookieSessionProvider\getLoginCookieExpiration().

◆ getLoginCookieExpiration()

MediaWiki\Session\CookieSessionProvider::getLoginCookieExpiration (   $cookieName,
  $shouldRememberUser 
)
protected

Returns the lifespan of the login cookies, in seconds.

0 means until the end of the session.

Cookies that are session-length do not call this function.

Parameters
string$cookieName
bool$shouldRememberUserWhether the user should be remembered long-term
Returns
int Cookie expiration time in seconds; 0 for session cookies

Definition at line 442 of file CookieSessionProvider.php.

References MediaWiki\Session\CookieSessionProvider\getExtendedLoginCookies().

Referenced by MediaWiki\Session\CookieSessionProvider\getRememberUserDuration(), MediaWiki\Session\CookieSessionProvider\persistSession(), and MediaWiki\Session\CookieSessionProvider\setForceHTTPSCookie().

◆ getRememberUserDuration()

MediaWiki\Session\CookieSessionProvider::getRememberUserDuration ( )

Returns the duration (in seconds) for which users will be remembered when Session::setRememberUser() is set.

Null means setting the remember flag will have no effect (and endpoints should not offer that option). Stable to override

Returns
int|null

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 417 of file CookieSessionProvider.php.

References MediaWiki\Session\CookieSessionProvider\getLoginCookieExpiration().

◆ getUserInfoFromCookies()

MediaWiki\Session\CookieSessionProvider::getUserInfoFromCookies (   $request)
protected

Fetch the user identity from cookies.

Parameters
\\WebRequest$request
Returns
array (string|null $id, string|null $username, string|null $token)

Definition at line 339 of file CookieSessionProvider.php.

References MediaWiki\Session\CookieSessionProvider\getCookie().

Referenced by MediaWiki\Session\CookieSessionProvider\provideSessionInfo().

◆ getVaryCookies()

MediaWiki\Session\CookieSessionProvider::getVaryCookies ( )

Return the list of cookies that need varying on.

Stable to override

Note
For use by \MediaWiki\Session\SessionManager only
Returns
string[]

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 315 of file CookieSessionProvider.php.

◆ persistSession()

MediaWiki\Session\CookieSessionProvider::persistSession ( SessionBackend  $session,
WebRequest  $request 
)

Persist a session into a request/response.

For example, you might set cookies for the session's ID, user ID, user name, and user token on the passed request.

To correctly persist a user independently of the session ID, the provider should persist both the user ID (or name, but preferably the ID) and the user token. When reading the data from the request, it should construct a User object from the ID/name and then verify that the User object's token matches the token included in the request. Should the tokens not match, an anonymous user must be passed to SessionInfo::__construct().

When persisting a user independently of the session ID, $session->shouldRememberUser() should be checked first. If this returns false, the user token must not be saved to cookies. The user name and/or ID may be persisted, and should be used to construct an unverified UserInfo to pass to SessionInfo::__construct().

A backend that cannot persist sesison ID or user info should implement this as a no-op.

Note
For use by \MediaWiki\Session\SessionBackend only
Parameters
SessionBackend$sessionSession to persist
WebRequest$requestRequest into which to persist the session

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 198 of file CookieSessionProvider.php.

References MediaWiki\Session\CookieSessionProvider\$cookieOptions, MediaWiki\Session\SessionBackend\addData(), MediaWiki\Session\CookieSessionProvider\cookieDataToExport(), MediaWiki\Session\SessionProvider\getHookRunner(), MediaWiki\Session\SessionBackend\getId(), MediaWiki\Session\SessionBackend\getLoggedOutTimestamp(), MediaWiki\Session\CookieSessionProvider\getLoginCookieExpiration(), MediaWiki\Session\SessionBackend\getUser(), WebRequest\response(), MediaWiki\Session\CookieSessionProvider\sessionDataToExport(), MediaWiki\Session\CookieSessionProvider\setForceHTTPSCookie(), MediaWiki\Session\CookieSessionProvider\setLoggedOutCookie(), MediaWiki\Session\SessionBackend\shouldForceHTTPS(), and MediaWiki\Session\SessionBackend\shouldRememberUser().

◆ persistsSessionId()

MediaWiki\Session\CookieSessionProvider::persistsSessionId ( )

Indicate whether self::persistSession() can save arbitrary session IDs.

If false, any session passed to self::persistSession() will have an ID that was originally provided by self::provideSessionInfo().

If true, the provider may be passed sessions with arbitrary session IDs, and will be expected to manipulate the request in such a way that future requests will cause self::provideSessionInfo() to provide a SessionInfo with that ID.

For example, a session provider for OAuth would function by matching the OAuth headers to a particular user, and then would use self::hashToSessionId() to turn the user and OAuth client ID (and maybe also the user token and client secret) into a session ID, and therefore can't easily assign that user+client a different ID. Similarly, a session provider for SSL client certificates would function by matching the certificate to a particular user, and then would use self::hashToSessionId() to turn the user and certificate fingerprint into a session ID, and therefore can't easily assign a different ID either. On the other hand, a provider that saves the session ID into a cookie can easily just set the cookie to a different value.

Note
For use by \MediaWiki\Session\SessionBackend only
Returns
bool

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 190 of file CookieSessionProvider.php.

◆ provideSessionInfo()

MediaWiki\Session\CookieSessionProvider::provideSessionInfo ( WebRequest  $request)

Provide session info for a request.

If no session exists for the request, return null. Otherwise return an SessionInfo object identifying the session.

If multiple SessionProviders provide sessions, the one with highest priority wins. In case of a tie, an exception is thrown. SessionProviders are encouraged to make priorities user-configurable unless only max-priority makes sense.

Warning
This will be called early in the MediaWiki setup process, before $wgUser, $wgLang, $wgOut, $wgTitle, the global parser, and corresponding pieces of the main RequestContext are set up! If you try to use these, things will break.
Note
The SessionProvider must not attempt to auto-create users. MediaWiki will do this later (when it's safe) if the chosen session has a user with a valid name but no ID.
For use by \MediaWiki\Session\SessionManager only
Parameters
WebRequest$request
Returns
SessionInfo|null

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 115 of file CookieSessionProvider.php.

References MediaWiki\Session\CookieSessionProvider\getCookie(), MediaWiki\Session\CookieSessionProvider\getUserInfoFromCookies(), MediaWiki\Session\UserInfo\newAnonymous(), MediaWiki\Session\UserInfo\newFromId(), and MediaWiki\Session\SessionManager\validateSessionId().

◆ sessionDataToExport()

MediaWiki\Session\CookieSessionProvider::sessionDataToExport (   $user)
protected

Return extra data to store in the session.

Parameters
User$user
Returns
array $session

Definition at line 399 of file CookieSessionProvider.php.

Referenced by MediaWiki\Session\CookieSessionProvider\persistSession().

◆ setConfig()

MediaWiki\Session\CookieSessionProvider::setConfig ( Config  $config)

Set configuration.

Parameters
Config$config

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 90 of file CookieSessionProvider.php.

References MediaWiki\Session\SessionProvider\$config, and Config\get().

◆ setForceHTTPSCookie()

MediaWiki\Session\CookieSessionProvider::setForceHTTPSCookie (   $set,
?SessionBackend  $backend,
WebRequest  $request 
)
protected

Set the "forceHTTPS" cookie, unless $wgForceHTTPS prevents it.

Parameters
bool$setWhether the cookie should be set or not
SessionBackend | null$backend
WebRequest$request

Definition at line 277 of file CookieSessionProvider.php.

References MediaWiki\Session\CookieSessionProvider\getLoginCookieExpiration(), WebRequest\response(), and MediaWiki\Session\SessionBackend\shouldRememberUser().

Referenced by MediaWiki\Session\CookieSessionProvider\persistSession(), and MediaWiki\Session\CookieSessionProvider\unpersistSession().

◆ setLoggedOutCookie()

MediaWiki\Session\CookieSessionProvider::setLoggedOutCookie (   $loggedOut,
WebRequest  $request 
)
protected

Set the "logged out" cookie.

Parameters
int$loggedOuttimestamp
WebRequest$request

Definition at line 306 of file CookieSessionProvider.php.

References MediaWiki\Session\CookieSessionProvider\getCookie(), and WebRequest\response().

Referenced by MediaWiki\Session\CookieSessionProvider\persistSession().

◆ suggestLoginUsername()

MediaWiki\Session\CookieSessionProvider::suggestLoginUsername ( WebRequest  $request)

Get a suggested username for the login form Stable to override.

Note
For use by \MediaWiki\Session\SessionBackend only
Parameters
WebRequest$request
Returns
string|null

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 326 of file CookieSessionProvider.php.

References User\getCanonicalName(), and MediaWiki\Session\CookieSessionProvider\getCookie().

◆ unpersistSession()

MediaWiki\Session\CookieSessionProvider::unpersistSession ( WebRequest  $request)

Remove any persisted session from a request/response.

For example, blank and expire any cookies set by self::persistSession().

A backend that cannot persist sesison ID or user info should implement this as a no-op.

Note
For use by \MediaWiki\Session\SessionManager only
Parameters
WebRequest$requestRequest from which to remove any session data

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 246 of file CookieSessionProvider.php.

References WebRequest\response(), and MediaWiki\Session\CookieSessionProvider\setForceHTTPSCookie().

◆ whyNoSession()

MediaWiki\Session\CookieSessionProvider::whyNoSession ( )

Return a Message for why sessions might not be being persisted.For example, "check whether you're blocking our cookies".

Returns
Message|null
Stable to override Stable to override

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 413 of file CookieSessionProvider.php.

References wfMessage().

Member Data Documentation

◆ $cookieOptions

mixed [] MediaWiki\Session\CookieSessionProvider::$cookieOptions = []
protected

◆ $params

mixed [] MediaWiki\Session\CookieSessionProvider::$params = []
protected

◆ $useCrossSiteCookies

bool MediaWiki\Session\CookieSessionProvider::$useCrossSiteCookies
protected

Definition at line 45 of file CookieSessionProvider.php.


The documentation for this class was generated from the following file: