Stitch Users¶

MongoDB Logo
ServerDriversCloudToolsGuides
Get MongoDB
Close ×
MongoDB Stitch

Introduction
Tutorials
Users & Authentication
    Overview
    User Management
        Stitch Users
        Configure Custom User Data
        Finding a User
        Viewing User Data
        Managing User Accounts
        Linking User Accounts
        Working with Multiple User Accounts
    Authentication Providers
        Overview
        Anonymous
        Email/Password
        API Key
        Apple ID
        Facebook OAuth 2.0
        Google OAuth 2.0
        Custom Function
        Custom JWT
MongoDB Atlas
GraphQL
MongoDB Mobile
Functions
Triggers
External Services
Values & Secrets
Application Deployment
Hosting
Troubleshooting
Stitch Administration
Application Logs
Client SDKs
Release Notes

Stitch > Users & Authentication > User Management 

Stitch Users

On this page

Overview
User Objects
User Metadata
User Sessions

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:

Store Custom User Data
Find a User
View User Activity
View a User’s Devices
View a User’s Provider Data
Create an Email/Password User Account
Revoke User Sessions
Delete or Disable a User

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:

{
“id”: “”,
“type”: “”,
“data”: {
“”: ,
…
},
“custom_data”: {
“”: ,
…
},
“identities”: [
{
“id”: ,
“provider_type”: “”,
“data”: {
“”: ,
…
}
}
]
}

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:
Type Description
“normal” The user is an application user logged in through an authentication provider other than the API Key provider.
“server” The user is a server process logged in with any type of Stitch API Key.
“system” The user is a system user that bypasses all rules.
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 16MB, the maximum size of a MongoDB document. To avoid hitting this limit, consider storing small and relatively static user data in each custom user data document, such as the user’s preferred language or the URL of their avatar image. For data that is large, unbounded, or frequently updated, consider only storing a reference to the data in the custom user document or storing the data with a reference to the user’s ID rather than in the custom user document.
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:

{
“id”: “”,
“provider_type”: “”,
“data”: {
“ ”: ,
…
}
}

Field Name Description
id A provider-generated string that uniquely identifies this identity
provider_type The type of authentication provider associated with this identity.
data Additional metadata from the authentication provider that describes the user. The exact field names and values will vary depending on which authentication providers the user has logged in with. For a provider-specific breakdown of user identity data, see User Metadata.

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:
Field Description
email The user’s email address.
API Key (Server & User)

API Key users are always associated with the following metadata fields:
Field Description
name The name associated with the API key that the user authenticated with.
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.
← User Authentication Overview Configure Custom User Data →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.
Was this page helpful?
Yes
No