- Stitch >
- Users & Authentication >
- User Management
Stitch Users¶
On this page
Overview¶
This page covers the technical aspects of how Stitch represents users
internally. It describes the structure and content of user objects, which model individual user accounts and are referenced by expressions like
context.user and %%user
. It also
covers the session-based authentication
mechanisms that Stitch uses internally, including details on storing,
refreshing, and invalidating access tokens.
To learn how to manage your application’s users, check out these guides:
User Objects¶
Stitch represents each application user internally with a User Object that includes a unique ID and additional metadata that describes the user. You can access user objects in the following ways:
- In a Function by accessing context.user.
- In rule expressions with the
%%user
expansion. - In client applications with the StitchAuth interface
User objects have the following form:
Field | Type | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
id |
string | A string representation of the ObjectId that uniquely identifies the user. | ||||||||
type |
string | The type of the user. The following types are possible:
|
||||||||
data |
document | A document that contains metadata that describes the
user. This field combines the data for all identities
associated with the user, so the exact field names and values
depend on which authentication providers
the user authenticated with. |
||||||||
custom_data |
document | A document from your application’s custom user data collection that specifies the user’s ID. You can use the customer user data collection to store arbitrary data about your application’s users. Stitch automatically fetches a new copy of the data whenever a user refreshes their access token, such as when they log in. The underlying data is a regular MongoDB document, so you can use standard CRUD operations through the MongoDB Atlas service to define and modify the user’s custom data. Avoid Storing Large Custom User Data Custom user data is limited to |
||||||||
identities |
array | A list of authentication provider identities associated with the user. When a user first logs in with a specific provider, Stitch associates the user with an identity object that contains a unique identifier and additional metadata about the user from the provider. For subsequent logins, Stitch refreshes the existing identity data but does not create a new identity. Identity objects have the following form:
|
Note
In general, Stitch creates a user object for a given user the first time that they authenticate. If you create a test Email/Password user through the Stitch UI, Stitch creates that user’s user object immediately.
User Metadata¶
Each authentication provider can associate a distinct set of metadata fields with an application user. Some providers (such as Email/Password) always add specific fields, whereas others allow you to configure the data to associate with each user. The following table describes the metadata fields that each authentication provider includes in a user object:
Authentication Provider | Details | ||||
---|---|---|---|---|---|
Anonymous | Anonymous users are not associated with any metadata. | ||||
Email/Password | Email/Password users are always associated with the following metadata fields:
|
||||
API Key (Server & User) | API Key users are always associated with the following metadata fields:
|
||||
OAuth 2.0 (Facebook & Google) | OAuth 2.0 users can be associated with data provided by the external authentication service according to the provider’s Metadata Fields configuration. Users must explicitly grant your application permission to access the data. | ||||
Custom Function | Custom Function authentication users are not automatically associated with any data. | ||||
Custom JWT | Custom JWT authentication users can be associated with any data
included in the JWT returned from the external authentication
system. The provider’s Metadata Fields configuration
maps fields in the JWT to fields that appear in the user object’s
data and identity fields. |
User Sessions¶
When a user is successfully authenticated, their sessions are managed with access tokens and a refresh token provided by MongoDB Stitch. The client SDKs implement the logic of managing these tokens and providing them to Stitch when making requests, but it can be useful to understand how sessions work when you’re building your client applications.
For web browsers, the JavaScript SDK stores these tokens in HTML5 local storage. In the Android SDK, they are stored in Shared Preferences. In the iOS SDK, they are stored in the Keychain.
The access token for a session expires after thirty minutes. However, a new session can be started by retrieving a new access token from Stitch using the refresh token. The SDKs automatically take care of refreshing access tokens, so you do not need to worry about this when implementing client applications.
You can invalidate a refresh token by calling the logout()
method
on the client, which does two things: it locally deletes current
session information by deleting both the access and refresh tokens,
and it invalidates the refresh token on the MongoDB Stitch server.
Note
The logout()
method provided by the SDKs does NOT invalidate
any active sessions on the server. This means that if an access
token is leaked out of storage before logout()
is called, that
access token can be theoretically used by an attacker to continue
making requests on behalf of the user who “logged out” for up to
thirty minutes (until that access token expires).
The user list under the Users tab, on the Users page of the MongoDB Stitch admin console, provides a way to revoke all sessions for a specific user. This will invalidate all access tokens and refresh tokens for that user. See the Revoking User Sessions page for the specific steps.