Frederic G. MARAND eb760a3d1d Documented service-configuration. | 8 years ago | |
---|---|---|
.. | ||
README.md | 8 years ago |
Not documented: localstorage_token.js
is supposed to be an opaque implementation detail.
The accounts system is founded on the users
collection and the notion of login tokens, which allow reconnecting.
Connections have observers based on the Mongo implementation.
users
. Indexes (other indexes are added by other packages, like account-password
:
('username', {unique: 1, sparse: 1});
('emails.address', {unique: 1, sparse: 1});
('services.resume.loginTokens.hashedToken', {unique: 1, sparse: 1});
('services.resume.loginTokens.token', {unique: 1, sparse: 1});
('services.resume.haveLoginTokensToDelete', { sparse: 1 });
: For taking care of logoutOtherClients calls that crashed before the tokens were deleted."services.resume.loginTokens.when", { sparse: 1 });
: For expiring login tokensDEFAULT_LOGIN_EXPIRATION_DAYS
= 90. Default login token lifetime. Used by AccountsCommon_getTokenLifetimeMs()
.MIN_TOKEN_LIFETIME_CAP_SECS
= 3600. Maximum value of "soon". Used by AccountsCommon._tokenExpiresSoon(when)
.EXPIRE_TOKENS_INTERVAL_MS
= 100000. Frequency of token expiration checks. Used by setExpireTokensInterval(accounts)
in accounts_server.js
.CONNECTION_CLOSE_DELAY_MS
= 10000. Logout delay for other clients. Used by Meteor.logoutOtherClients()
, added from accounts_server.js
.AccountsClient extends AccountsCommon
(accounts_client.js
)constructor(options)
options
`:
connection
: optional DDP connection to reuseddpUrl
: optional DDP URL to create a new connection_loggingIn
: "private", use loggingIn()
/setLoggingIn()
for reactivity_loggingInDeps
: Tracker dependency_loginServicesHandle
: subscription to meteor.loginServiceConfiguration
_pageLoadLoginCallbacks
: an array of page loading callbacks_pageLoadLoginAttemptInfo
: holds the information passed to login callbacks during a page-load login attempt_initUrlMatching()
(from url_client.js
)_initLocalStorage()
(from localstorage_token.js
)callLoginMethod(options)
: call login method on the server
this.setUserId(id)
and Accounts._setLoginToken
on the server and returns an object with fields 'id' (actually userId
(containing the user id), 'token' (containing a resume token), and optionally tokenExpires
.Meteor.loggingIn()
reactive data sourcewait
modeAccounts.connection.setUserId()
onReconnect
handler which logs in with the resume tokenonLoginHook
or onLoginFailureHook
then the userCallback
optionmethodName
: The method to call (default login
)methodArguments
: The arguments for the methodvalidateResult
: If provided, will be called with the result of the method. If it throws, the client will not be logged in (and its error will be passed to the callback).userCallback
: Will be called with no arguments once the user is fully logged in, or with a single-element array containing the error on error.loggingIn()
: reactive getter for _loggingIn
loginServicesConfigured()
: A reactive function returning whether the loginServiceConfiguration
subscription is ready. Used by accounts-ui
to hide the login button until we have all the configuration loadedlogout(callback)
: logs the user out:
connection.logout()
logoutOtherClients(callback)
: Log out other clients logged in as the current user, but does not log out the client that calls this function. Interesting logic to execute two method calls without having the event loop run between them.makeClientLoggedIn()
: helper for callLoginMethod()
makeClientLoggedOut()
: helper for logout()
and reconnect errorsonPageLoadLogin(f)
: Register a callback to be called if we have information about a login attempt at page load time. Call the callback immediately if we already have the page load login attempt info, otherwise stash the callback to be called if and when we do get the attempt info.userId()
overrides pseudo-abstract parent method to use the per-connection user id._pageLoadLogin(attemptInfo)
:_setLoggingIn()
: setter for _loggingIn
(triggers reactive update)url_client.js
additions:
_attemptToMatchHash()
: Try to match the saved value of window.location.hash to one of the reserved hashes, to trigger an Accounts operation. On success, invokes passed handler which, when called from _initUrlMatching()
, will always be defaultSuccessHandler()
._initUrlMatching()
: called by constructor. Inits extra data on instance and invokes _attemptToMatchHash()
onResetPasswordLink()
Register a function to call when a reset password link is clicked in an email sent by on of the hash handlers. See Accounts-onResetPasswordLinkonEmailVerificationLink()
Register a function to call when an email verification link is clicked in an email sent by a hash handler. See Accounts-onEmailVerificationLinkonEnrollmentLink()
Register a function to call when an account enrollment link is clicked in an email sent by a hash handler. See Accounts-onEnrollmentLinkwindow.location.hash
. Reserved hashes:
reset-password
verify-email
enroll-account
defaultSuccessHandler()
attemptToMatchHash()
AccountsCommon
(accounts_common.js
)Base class for AccountsClient
/ AccountsServer
.
constructor(options)
.
connection
, then users
.connection
, ddpUrl
see initConnection()
sendVerificationEmail
, forbidClientAccountCreation
, restrictCreationByEmailDomain
, loginExpirationInDays
, and oauthSecretKey
(side-effect, not saved). see config(options)
addDefaultRateLimit()
: enable per-connection, per-method rate limiter for login
, createUser
, resetPassword
forgotPassword
to 5 calls every 10 seconds. Added from accounts_rate_limits.js
.config(options)
. Set up config for the accounts system. Call this on both the client the server. Overridden in server.
_options
.sendVerificationEmail
{Boolean}: Send email address verification emails to new users created from client signups.forbidClientAccountCreation
{Boolean} Do not allow clients to create accounts directly. Security issue #828 exists if this is not called on both client and serverrestrictCreationByEmailDomain
{Function or String} Require created users to have an email accepted by the function (by returning trueish) or having the string match the domain as a case-insensitive fully-anchored regex. See defaultValidateNewUserHook()
.loginExpirationInDays
{Number} Number of days since login until a user is logged out (login token expires).oauthSecretKey
When using the oauth-encryption
package, the 16 byte key using to encrypt sensitive account credentials in the database, encoded in base64.
oauth-encryption
package is not presentoauth-encryption
packageConfigError
: legacy, initialized from service-configuration
package during Meteor.startup()
.connection
: the MongoDB connection. If set to null, the users
collection will be local (avoid !)LoginCancelledError
: specific error class to use when a login sequence is cancelledloginServiceConfiguration
: legacy, initialized from service-configuration
package during Meteor.startup()
.removeDefaultRateLimit()
: disable the rate limiter for the methods below (from accounts_rate_limits.js
).user()
: returns the currently logged-in user by finding it from Mongo based on the userId()
value. Defaults to null
.userId()
: Error("userId method not implemented")
Basically an abstract method to be refined in child classesusers
: the users collectiononLogin(func)
: Register a callback to be called after a login attempt succeeds.onLoginFailure(func)
: Register a callback to be called after a login attempt fails._getTokenLifetimeMs()
: get the remaining login token lifetime in msec. Taken from loginExpirationInDays
if it exists. Defaults to DEFAULT_LOGIN_EXPIRATION_DAYS
(= 90) days in msec._initConnection(options)
- Options can contain
connection
: the connection on which to load the users
collectionddpUrl
: if connection is not set, connect to this URLMeteor.connection
will be used as a default_onLoginHook()
. As per hook.js, Hook system is under development. Use onLogin(func)
to make use of it._onLoginFailureHook()
. As per hook.js, Hook system is under development. Use onLoginFailure(func)
to make use of it._options = {}
- used directly by packages like accounts-password
and `accounts-ui-unstyled._tokenExpiration(when)
: when
is a token (timestamp, used to be any number in earlier versions). It is converted to Date, and added with _getTokenLifetimeMs()
to return the expiration date for the when
._tokenExpiresSoon(when)
: when
is a token (timestamp). True if it expires in less the smaller of 0.1 * _getTokenLifetimeMs()
and 1 hour.accounts_rate_limits.js
: loading this file initializes the rate-limiter for addDefaultRateLimit()
and removeDefaultRateLimit()
. This is why the package has a dependency on ddp-rate-limiter
.AccountsServer extends AccountsCommon
(accounts_server.js
)constructor(server)
AccountsCommon
constructor_server
from the server argument if not empty, defaulting to Meteor.server
otherwise_initServerMethods()
_accountData
using _initAccountDataHooks()
autopublish
is present, mark user fields as published:
profile
and username
emails
_initServerPublications()
users
collection using setupUsersCollection(users)
.setupDefaultLoginHandlers()
.setExpireTokensInterval(accounts)
._validateLoginHook
_validateNewUserHooks
to the single defaultValidateNewUserHook()
._deleteSavedTokensForAllUsersOnStartup()
_skipCaseInsensitiveChecksForTest
: used by tests only.addAutopublishFields(opts)
: allow packages to declare extra fields when autopublish is active.config(options)
: overrides parent method, but starts by invoking it. Option:
loginExpirationInDays
: removes the background token expiration observerdestroyToken(userId, loginToken)
: Deletes the given loginToken from the database. For new-style hashed token, this will cause all connections associated with the token to be closed.defaultResumeLoginHandler(accounts, options)
: Login handler for resume tokens. The token is found in options.resume
.defaultValidateNewUserHook(user)
: Validate new user's email or Google/Facebook/GitHub account's email, if the restrictCreationByEmailDomain
config option is active.insertUserDoc(options, user)
: main user account creation function, used by accounts-password
:
onCreateUser(func)
: registers func
as the single user creation hook allowed.registerLoginHandler(name, handler)
: The main entry point for auth packages to hook in to login. A login handler is a login method which can return undefined
to indicate that the login request is not handled by this handler.
name
{String} Optional. The service name, used by default if a specific service name isn't returned in the result.handler
{Function} A function that receives an options object (as passed as an argument to the login
method) and returns one of: undefined
, meaning don't handle; or a login method result object as described on _loginUser
.setExpireTokensInterval(accounts)
: starts a low-frequency (EXPIRE_TOKENS_INTERVAL_MS
= 10 sec) task expiring tokens. Can be deactivated using config({ loginExpirationInDays: null })
.setupDefaultLoginHandlers()
: registers defaultResumeLoginHandler()
as a login handler called resume
using registerLoginHandler()
.setupUsersCollection(users)
: configures the users
collection obtained from the parent constructor, by applying users.allow
to limite update rights to the document for the current user, and ensuring multiple MongoDB indexes:
username
: {unique: 1, sparse: 1})
emails.address
: { unique: 1, sparse: 1})
services.resume.loginTokens.hashedToken
: {unique: 1, sparse: 1})
services.resume.loginTokens.token
: { unique: 1, sparse: 1})
services.resume.haveLoginTokensToDelete
: { sparse: 1 })
services.resume.loginTokens.when
: { sparse: 1 })
updateOrCreateUserFromExternalService(serviceName, serviceData, options)
: Updates or creates a user after we authenticate with a 3rd party.
@param serviceName
{String} Service name (eg, twitter).@param serviceData
{Object} Data to store in the user's record under services[serviceName]. Must include an "id" field which is a unique identifier for the user in the service. (Side note: there is a specific kludge for old Twitter ids).@param options
{Object, optional} Other options to pass to insertUserDoc (eg, profile)@returns
{Object} Object with token
and id
(actually userId
) keys, like the result of the login
method.resume
and password
may not use thisprofile
but updates serviceData
userId()
: overrides the unimplemented version in AccountsCommon
. This function only works if called inside a method, throws otherwise.
usingOAuthEncryption()
: is OAuth encryption present AND is a key loaded ?
validateLoginAttempt(func)
: registers func
as a login attempt validation hook, returning an object with a stop()
method to unregister it.
validateNewUser(func)
: register func
as a user account creation validation hook, not returning anything.
_accountData
: see setAccountData()
.
_attemptLogin(methodInvocation, methodName, methodArgs, result)
: After a login method has completed, call the login hooks: validation (which can turn allowed into disallowed), and login or loginFailure hooks. Note that attemptLogin
is called for all login attempts, even ones which aren't successful (such as an invalid password, etc). If the login is allowed and isn't aborted by a validate login hook callback, log in the user. Use _loginMethod()
instead.
_clearAllLoginTokens(userId)
: removes all login tokens on a user identified by userId
`.
_deleteSavedTokensForAllUsersOnStartup()
: on Meteor.startup()
, immediately clean discovered saved tokens which applied to the previous instance of the application.
_deleteSavedTokensForUser(userId, tokensToDelete)
: used by the delayed logout (CONNECTION_CLOSE_DELAY_MS) in obsolete method logoutOtherClients()
and helper for _deleteSavedTokensForAllUsersOnStartup()
to logout other clients.
_expireTokens(oldestValidDate, userId)
: Deletes expired tokens from the database and closes all open connections associated with these tokens. Exported for tests. Also, the arguments are only used by tests. oldestValidDate is simulate expiring tokens without waiting for them to actually expire. userId is used by tests to only expire tokens for the test user. Side-effect The observe on Meteor.users will take care of closing connections for expired tokens.
_failedLogin()
: invokes the AccountsCommon.onLoginFailureHook
implementations.
_generateStampedLoginToken()
: generates a pseudo-random login token. As per docs: "Used by Meteor Accounts server and tests".
_getAccountData(connectionId, field)
: get the login token for a connection. Documented as a "HACK: This is used by 'meteor-accounts' to get the loginToken for a connection. Maybe there should be a public way to do that.". Also used by _getLoginToken()
.
_getLoginToken(connectionId)
: gets the login token for a connection, using the _getAccountData()
hack.
_getUserObserve(connectionId)
: test helper - returns the user observed on a connection
_hashLoginToken(loginToken)
: hashes a token with sha256, returning the hash in base64 encoding.
_hashStampedToken(stampedToken)
: modifies a stamped token from { token: ..., ... }
to { hashedtoken: ..., ... }
_initAccountDataHooks()
: add a DDP onConnect
callback which
_accountData[connection.id]
onClose
callback removing the current user token from the connection using _removeTokenFromConnection(connection.id);
and removing the connection stored in _accountData[connection.id]
on connection._initServerMethods()
: adds the account-related methods defined by the class. See _server._methodHandlers
.
_initServerPublications()
: starts account-related publications:
meteor.loginServiceConfiguration
from the (OAuth) service configuration. The secret
field is removed from the publication, hence it is only available when querying server-side.users
cursor publish:
profile
, username
, and emails
for the current user if applicable,null
addAutopublishFields(forLoggedInUser)
_id
and username
(if available) for all users, and fields added by other packages using addAutopublishFields(forOtherUsers)
users
anonymous with more fields,_insertHashedLoginToken(userId, hashedToken, query)
: add a hashed token to the services.resume.loginTokens
array on a user account. Do (incorrectly ?) says an index error can be thrown if the token is already present (as per MongoDB docs, it just does nothing)
_insertLoginToken(userId, stampedToken, query)
: test helper combining _insertHashedLoginToken()
and _hashStampedToken()
_loginHandlers
: list of all registered handlers. Starts as []
.
_loginMethod(methodInvocation, methodName, methodArgs, type, fn)
the safe version of _attemptLogin()
is the one to use to login a user.
_loginUser(methodInvocation, userId, stampedLoginToken)
: Log in a user on a connection after success. Returns { id: userId, token: stampedLoginToken.token, tokenExpires: self._tokenExpiration(stampedLoginToken.when) };
. Invoked from _attemptLogin()
.
_nextUserObserveNumber
: the next observer number for _userObservesForConnections
.
_removeTokenFromConnection(connectionId)
: remove an observer token from a connection.
_reportLoginFailure(methodInvocation, methodName, methodArgs, result)
: Report a login attempt failed outside the context of a normal login method. This is for use in the case where there is a multi-step login procedure (eg SRP based password login). If a method early in the chain fails, it should call this function to report a failure.
_runLoginHandlers(methodInvocation, options)
: Checks a user's credentials against all the registered login handlers, and returns a login token if the credentials are valid. It is like the login method, except that it doesn't set the logged-in user on the connection. Works by invoking tryLoginMethod()
on each handler until one returns something not undefined. Throws Error 400 on incorrect options for a handler, or a handler returning neither undefined nor a result object as described on _loginUser
.
_server
: a Server
(from ddp-server/livedata_server.js
) instance. Notable properties in this context:
_methodHandlers
: the Meteor methods table
login(options)
: runs result = _runLoginHandlers(self, options); _attemptLogin(self, "login", arguments, result);
. The method ensures options
is an object, but it is up to login handlers to check whatever field they look at in options: Meteor doesn't check them.logout()
: deletes the login token for the connection with destroyToken
and clears the current user id using method setUserId(null)
.logoutOtherClients()
: obsolete for compatibility with 0.7.2, use getNewToken()
and removeOtherTokens()
insteadgetNewToken()
: Generates a new login token with the same expiration as the connection's current token and saves it to the database. Associates the connection with this new token and returns it. Throws an error if called on a connection that isn't logged in.removeOtherTokens()
: Removes all tokens except the token associated with the current connection. Throws an error if the connection is not logged in. Returns nothing on success.configureLoginService(options)
: Allow a one-time configuration for a login service. Modifications to this collection are also allowed in insecure mode. Option keys:
service
: String, required. The name of the service to configure. Bug : this method can only be used to configure OAuth login providers. There is a XXX in the code about this problem having to be fixed, either by moving use of service
to the accounts-oauth
package, or to move the list of services from accounts-oauth
to accounts-base
_setAccountData(connectionId, field, value)
: modifies or deletes data from a connection kept on _accountData
.
_setLoginToken(userId, connection, newToken)
: replaces any token for a user on a connection with a new token. If the latter is not empty, sets up an observer for the token.
_successfulLogin()
: invokes the AccountsCommon.onLoginHook
implementations.
_testEmailDomain(email)
: checks user email matches the domain configured in the restrictCreationByEmailDomain
config option. Used by defaultValidateNewUserHook()
.
_userObservesForConnections
: observe handle for the login token that this connection is currently associated with, or a number. The number indicates that we are in the process of setting up the observe (using a number instead of a single sentinel allows multiple attempts to set up the observe to identify which one was theirs). Numbers obtained from _nextUserObserveNumber
.
_validateLogin(connection, attempt)
: perform login validation using available implementations in _validateLoginHook
. Note that all validators run even if one or more of them denies access or throws an error. The first reported error is the one the user receives by default, but later validators may override this behavior. Invoked from _attemptLogin()
.
_validateLoginHook
: holds a login validation hook. Doc in hook.js
warns "This pattern is under development. Do not add more callsites using this package for now"
_validateNewUserHooks
: holds an array of new user hooks.
note about methods. These 3 methods are public but marked (in 1.2.1) as likely not to remain so:
resetPassword()
: generates a password reset link (from token)verifyEmail()
: generates an email verification link (from token)enrollAccount()
: generates an account enrollment link (from token)AccountsTest
attemptToMatchHash()
facade for attemptToMatchHash()
functionAccounts
(see globals_server.js
)userId
: a copy of the Accounts.usedId()
methoduser()
: a copy of the Accounts.user()
methodaccounts_server.js
defaultCreateUserHook(options, user)
: __XXX see comment on Accounts.createUser in passwordsserver about adding a second "server options" argument.defaultValidateNewUserHook()
a weak email validation method based on the domain name. See AccountsServer._validateNewUserHooks
.cloneAttemptWithConnection(connection, attempt)
clone the attempt object, preserving the connection inside it instead of cloning it toopinEncryptedFieldsToUser(serviceData, userId)
: OAuth service data is temporarily stored in the pending credentials collection during the oauth authentication process. Sensitive data such as access tokens are encrypted without the user id because we don't know the user id yet. We re-encrypt these fields with the user id included when storing the service data permanently in the users collection.tryLoginMethod(type, fn)
: Try a login method, converting thrown exceptions into an {error} result. The type
argument is a default, inserted into the result object if not explicitly returned.url_client.js
defaultSuccessHandler()
: suspends autologin, invokes other handles for the same hash, passing them a closure capable of enabling autologin.package.js
et al.)Symbol | Client | Server | Test |
---|---|---|---|
Accounts | O | O | O |
AccountsClient | O | ||
AccountsServer | O | ||
AccountsTest | O |
Accounts
new AccountsClient()
(extends AccountsCommon
)new AccountsServer(Meteor.server)
(extends AccountsCommon
)Meteor
users
for the users
collection. Name is expected to become configurable in future versions.Meteor.loggingIn()
is an alias for Accounts.loggingIn()
.Meteor.logout()
is an alias for AccountsClient.logout()
.Meteor.logoutOtherClients()
is an alias for AccountsClient.logoutOtherClients()
.currentUser
-> Meteor.user()
.loggingIn
-> Meteor.loggingIn()
.Package | Client | Server | Specifics |
---|---|---|---|
underscore | O | O | |
ecmascript | O | O | |
ddp-rate-limiter | O | O | |
localstorage | O | ||
tracker | O | ||
check | O | ||
random | O | O | |
ejson | O | ||
callback-hook | O | O | |
service-configuration | O | O | unordered (needs Accounts.connection) |
ddp | O | O | |
mongo | O | O | expected abstraction in the future |
blaze | O | weak: define {{currentUser}} | |
autopublish | O | weak: publish extra users fields | |
oauth-encryption | O | weak | |
NPM crypto | O | in accounts_server.js |
accounts-server.js
OAuthEncryption
: if package oauth-encryption
is present, contains its encryption
export. Used by OAuth-related functions in this package.If OAuth encryption is present and a key is loaded, the startup code in accounts_server.js
seals the secret
field in ServiceConfiguration
exported by the service-configuration
package. This appears to be unstable, as per docs: XXX For the oauthSecretKey to be available here at startup, the developer must call Accounts.config({oauthSecretKey: ...}) at load time, instead of in a Meteor.startup block, because the startup block in the app code will run after this accounts-base startup block. Perhaps we need a post-startup callback?