|
MediaWiki master
|
The default session provider for MediaWiki which persists sessions using cookies. More...
Inherits MediaWiki\Session\SessionProvider.

Public Member Functions | ||||
| __construct (private JwtCodec $jwtCodec, private UrlUtils $urlUtils, $params=[]) | ||||
| 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.
| ||||
| getOpenApiSecuritySchemes () | ||||
Return OpenAPI security scheme definitions provided by this session provider.Returns an array mapping a scheme suffix to an OpenAPI Security Scheme Object (as an associative array). In the aggregated output of SessionManager::getAllOpenApiSecuritySchemes(), each final key is the provider's name (its string representation, which defaults to the class name, with backslashes replaced by hyphens) followed by a hyphen and the suffix.For example, a provider whose class is MediaWiki\Session\CookieSessionProvider returning [ 'Session' => [...] ] will produce the key "MediaWiki-Session-CookieSessionProvider-Session" in the aggregated output of SessionManager::getAllOpenApiSecuritySchemes().
| ||||
| 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).
| ||||
| getVaryCookies () | ||||
Return the list of cookies that need varying on.
| ||||
| persistSession (SessionBackend $session, WebRequest $request) | ||||
| Persist a session into a request/response. | ||||
| 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.
| ||||
| 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.
| ||||
| suggestLoginUsername (WebRequest $request) | ||||
Get a suggested username for the login form.This is usually null, but may return the user name of a previous login session from the same device. This is meant to reduce login friction by reminding infrequent editors about their chosen username.The default CookieSessionProvider stores the last username in a dedicated cookie that, unlike the "Token" session ID cookie, is not removed during logout (via User::doLogout, SessionBackend::unpersist, SessionBackend::save, and finally CookieSessionProvider::unpersistSession).
| ||||
| unpersistSession (WebRequest $request) | ||||
| Remove any persisted session from a request/response. | ||||
| whyNoSession () | ||||
Return a Message for why sessions might not be being persisted.For example, "check whether you're blocking our cookies".
| ||||
Public Member Functions inherited from MediaWiki\Session\SessionProvider | ||||
| __construct () | ||||
| __toString () | ||||
| allowSecuritySensitiveOperationIfCannotReauthenticate (SessionBackend $session, WebRequest $request) | ||||
| Whether security-sensitive operations that require reauthentication should be allowed when canChangeUser() returns false (meaning reauthentication is not supported). | ||||
| canAlwaysAutocreate () | ||||
| Returns true if this provider is exempt from autocreate user permissions check. | ||||
| describe (Language $lang) | ||||
Return an identifier for this session type.
| ||||
| getAllowedUserRights (SessionBackend $backend) | ||||
| Fetch the rights allowed the user when the specified session is active. | ||||
| getManager () | ||||
| Get the session manager. | ||||
| getRestrictions (?array $providerMetadata) | ||||
| Fetch any restrictions imposed on logins or actions when this session is active. | ||||
| getVaryHeaders () | ||||
| Return the HTTP headers that need varying on. | ||||
| init (LoggerInterface $logger, Config $config, SessionManager $manager, HookContainer $hookContainer, UserNameUtils $userNameUtils) | ||||
| Initialise with dependencies of a SessionProvider. | ||||
| invalidateSessionsForUser (User $user) | ||||
| Invalidate existing sessions for a user. | ||||
| mergeMetadata (array $savedMetadata, array $providedMetadata) | ||||
| Merge saved session provider metadata. | ||||
| newSessionInfo ( $id=null) | ||||
| Provide session info for a new, empty session. | ||||
| preventSessionsForUser ( $username) | ||||
| Prevent future sessions for the user. | ||||
| refreshSessionInfo (SessionInfo $info, WebRequest $request, &$metadata) | ||||
| Validate a loaded SessionInfo and refresh provider metadata. | ||||
| safeAgainstCsrf () | ||||
| Most session providers require protection against CSRF attacks (usually via CSRF tokens) | ||||
| sessionIdWasReset (SessionBackend $session, $oldId) | ||||
| Notification that the session ID was reset. | ||||
| sessionWasAttachedToRequest (SessionInfo $sessionInfo, WebRequest $request) | ||||
| Notification that the session provider was selected to handle a given request. | ||||
Protected Member Functions | |
| cookieDataToExport ( $user, $remember) | |
| Return the data to store in cookies. | |
| getCookie ( $request, $key, $prefix, $default=null) | |
| Get a cookie. | |
| getExtendedLoginCookies () | |
| Gets the list of cookies that must be set to the 'remember me' duration, if $wgExtendedLoginCookieExpiration is in use. | |
| getJwtClaimOverrides (int $expirationDuration) | |
| getJwtCookieOptions () | |
| Helper method to make it easy for subclasses to alter JWT cookie options (as multiple wikis are expected to share the same cookie for some providers). | |
| getLoginCookieExpiration ( $cookieName, $shouldRememberUser) | |
| Returns the lifespan of the login cookies, in seconds. | |
| getUserInfoFromCookies ( $request) | |
| Fetch the user identity from cookies. | |
| postInitSetup () | |
| A provider can override this to do any necessary setup after init() is called. | |
| sessionDataToExport ( $user) | |
| Return extra data to store in the session. | |
| setForceHTTPSCookie ( $set, ?SessionBackend $backend, WebRequest $request) | |
| Set the "forceHTTPS" cookie, unless $wgForceHTTPS prevents it. | |
Protected Member Functions inherited from MediaWiki\Session\SessionProvider | |
| describeMessage () | |
| Return a Message identifying this session type. | |
| getConfig () | |
| Get the config. | |
| getHookContainer () | |
| getHookRunner () | |
| Get the HookRunner. | |
| hashToSessionId ( $data, $key=null) | |
| Hash data as a session ID. | |
| makeException ( $key,... $params) | |
| Throw an exception, later. | |
Protected Attributes | |
| mixed[] | $cookieOptions = [] |
| JwtSessionCookieHelper | $jwtSessionCookieHelper |
| mixed[] | $params = [] |
Protected Attributes inherited from MediaWiki\Session\SessionProvider | |
| Config | $config |
| LoggerInterface | $logger |
| SessionManager | $manager |
| int | $priority |
| Session priority. | |
| UserNameUtils | $userNameUtils |
The default session provider for MediaWiki which persists sessions using cookies.
Definition at line 27 of file CookieSessionProvider.php.
| MediaWiki\Session\CookieSessionProvider::__construct | ( | private JwtCodec | $jwtCodec, |
| private UrlUtils | $urlUtils, | ||
| $params = [] ) |
| JwtCodec | $jwtCodec | |
| UrlUtils | $urlUtils | |
| array | $params | Keys include:
|
Definition at line 52 of file CookieSessionProvider.php.
References MediaWiki\Session\CookieSessionProvider\$params, MediaWiki\Session\SessionInfo\MAX_PRIORITY, and MediaWiki\Session\SessionInfo\MIN_PRIORITY.
| 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.
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 216 of file CookieSessionProvider.php.
|
protected |
Return the data to store in cookies.
| User | $user | |
| bool | $remember |
Definition at line 425 of file CookieSessionProvider.php.
Referenced by MediaWiki\Session\CookieSessionProvider\persistSession().
|
protected |
Get a cookie.
Contains an auth-specific hack.
| WebRequest | $request | |
| string | $key | |
| string | $prefix | |
| mixed | null | $default |
Definition at line 406 of file CookieSessionProvider.php.
References $request.
Referenced by MediaWiki\Session\CookieSessionProvider\provideSessionInfo().
|
protected |
Gets the list of cookies that must be set to the 'remember me' duration, if $wgExtendedLoginCookieExpiration is in use.
Definition at line 466 of file CookieSessionProvider.php.
|
protected |
| int | $expirationDuration | Session lifetime in seconds. |
Definition at line 497 of file CookieSessionProvider.php.
Referenced by MediaWiki\Session\CookieSessionProvider\provideSessionInfo().
|
protected |
Helper method to make it easy for subclasses to alter JWT cookie options (as multiple wikis are expected to share the same cookie for some providers).
Definition at line 507 of file CookieSessionProvider.php.
Referenced by MediaWiki\Session\CookieSessionProvider\getVaryCookies(), MediaWiki\Session\CookieSessionProvider\provideSessionInfo(), and MediaWiki\Session\CookieSessionProvider\unpersistSession().
|
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.
| string | $cookieName | |
| bool | $shouldRememberUser | Whether the user should be remembered long-term |
Definition at line 480 of file CookieSessionProvider.php.
References MediaWiki\MainConfigNames\CookieExpiration, and MediaWiki\MainConfigNames\ExtendedLoginCookieExpiration.
Referenced by MediaWiki\Session\CookieSessionProvider\persistSession(), and MediaWiki\Session\CookieSessionProvider\setForceHTTPSCookie().
| MediaWiki\Session\CookieSessionProvider::getOpenApiSecuritySchemes | ( | ) |
Return OpenAPI security scheme definitions provided by this session provider.Returns an array mapping a scheme suffix to an OpenAPI Security Scheme Object (as an associative array). In the aggregated output of SessionManager::getAllOpenApiSecuritySchemes(), each final key is the provider's name (its string representation, which defaults to the class name, with backslashes replaced by hyphens) followed by a hyphen and the suffix.For example, a provider whose class is MediaWiki\Session\CookieSessionProvider returning [ 'Session' => [...] ] will produce the key "MediaWiki-Session-CookieSessionProvider-Session" in the aggregated output of SessionManager::getAllOpenApiSecuritySchemes().
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 348 of file CookieSessionProvider.php.
| 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).
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 455 of file CookieSessionProvider.php.
|
protected |
Fetch the user identity from cookies.
| WebRequest | $request |
Definition at line 389 of file CookieSessionProvider.php.
References $request.
Referenced by MediaWiki\Session\CookieSessionProvider\provideSessionInfo().
| MediaWiki\Session\CookieSessionProvider::getVaryCookies | ( | ) |
Return the list of cookies that need varying on.
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 333 of file CookieSessionProvider.php.
References MediaWiki\Session\CookieSessionProvider\getJwtCookieOptions().
| 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 session ID or user info should implement this as a no-op.
| SessionBackend | $session | Session to persist |
| WebRequest | $request | Request into which to persist the session |
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 220 of file CookieSessionProvider.php.
References MediaWiki\Session\CookieSessionProvider\$cookieOptions, $request, MediaWiki\Session\SessionBackend\addData(), MediaWiki\Session\CookieSessionProvider\cookieDataToExport(), MediaWiki\MainConfigNames\CookieSecure, MediaWiki\MainConfigNames\ForceHTTPS, MediaWiki\Session\SessionProvider\getConfig(), MediaWiki\Session\SessionBackend\getId(), MediaWiki\Session\CookieSessionProvider\getLoginCookieExpiration(), MediaWiki\Session\SessionBackend\getUser(), MediaWiki\Session\CookieSessionProvider\sessionDataToExport(), MediaWiki\Session\CookieSessionProvider\setForceHTTPSCookie(), MediaWiki\Session\SessionBackend\shouldForceHTTPS(), and MediaWiki\Session\SessionBackend\shouldRememberUser().
| 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.
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 211 of file CookieSessionProvider.php.
|
protected |
A provider can override this to do any necessary setup after init() is called.
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 85 of file CookieSessionProvider.php.
References MediaWiki\MainConfigNames\CookieDomain, MediaWiki\MainConfigNames\CookieHttpOnly, MediaWiki\MainConfigNames\CookiePath, MediaWiki\MainConfigNames\CookiePrefix, MediaWiki\MainConfigNames\CookieSameSite, MediaWiki\MainConfigNames\CookieSecure, MediaWiki\MainConfigNames\ForceHTTPS, MediaWiki\Session\SessionProvider\getConfig(), MediaWiki\MediaWikiServices\getInstance(), and MediaWiki\MainConfigNames\SessionName.
| 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.
| WebRequest | $request |
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 119 of file CookieSessionProvider.php.
References $request, MediaWiki\Session\CookieSessionProvider\getCookie(), MediaWiki\Session\CookieSessionProvider\getJwtClaimOverrides(), MediaWiki\Session\CookieSessionProvider\getJwtCookieOptions(), MediaWiki\Session\CookieSessionProvider\getUserInfoFromCookies(), MediaWiki\Session\UserInfo\newAnonymous(), MediaWiki\Session\UserInfo\newFromId(), and MediaWiki\Session\SessionManager\validateSessionId().
|
protected |
Return extra data to store in the session.
| User | $user |
Definition at line 445 of file CookieSessionProvider.php.
Referenced by MediaWiki\Session\CookieSessionProvider\persistSession().
|
protected |
Set the "forceHTTPS" cookie, unless $wgForceHTTPS prevents it.
| bool | $set | Whether the cookie should be set or not |
| SessionBackend | null | $backend | |
| WebRequest | $request |
Definition at line 308 of file CookieSessionProvider.php.
References $request, MediaWiki\MainConfigNames\ForceHTTPS, MediaWiki\Session\SessionProvider\getConfig(), MediaWiki\Session\CookieSessionProvider\getLoginCookieExpiration(), and MediaWiki\Session\SessionBackend\shouldRememberUser().
Referenced by MediaWiki\Session\CookieSessionProvider\persistSession(), and MediaWiki\Session\CookieSessionProvider\unpersistSession().
| MediaWiki\Session\CookieSessionProvider::suggestLoginUsername | ( | WebRequest | $request | ) |
Get a suggested username for the login form.This is usually null, but may return the user name of a previous login session from the same device. This is meant to reduce login friction by reminding infrequent editors about their chosen username.The default CookieSessionProvider stores the last username in a dedicated cookie that, unlike the "Token" session ID cookie, is not removed during logout (via User::doLogout, SessionBackend::unpersist, SessionBackend::save, and finally CookieSessionProvider::unpersistSession).
| WebRequest | $request |
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 372 of file CookieSessionProvider.php.
References $request.
| 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 session ID or user info should implement this as a no-op.
| WebRequest | $request | Request from which to remove any session data |
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 270 of file CookieSessionProvider.php.
References $request, MediaWiki\Session\CookieSessionProvider\getJwtCookieOptions(), and MediaWiki\Session\CookieSessionProvider\setForceHTTPSCookie().
| MediaWiki\Session\CookieSessionProvider::whyNoSession | ( | ) |
Return a Message for why sessions might not be being persisted.For example, "check whether you're blocking our cookies".
Reimplemented from MediaWiki\Session\SessionProvider.
Definition at line 450 of file CookieSessionProvider.php.
References wfMessage().
|
protected |
Definition at line 33 of file CookieSessionProvider.php.
Referenced by MediaWiki\Session\CookieSessionProvider\persistSession().
|
protected |
Definition at line 35 of file CookieSessionProvider.php.
|
protected |
Definition at line 30 of file CookieSessionProvider.php.
Referenced by MediaWiki\Session\CookieSessionProvider\__construct().