Cosync JWT authentication for MongoDB Realm

Cosync JWT Authentication


Clearly, mobile and cloud computing technologies will play a pivotal role in building solutions to mitigate this crisis. It is up to the world’s entrepreneurs and engineers to dream up and implement the applications that will meet the challenges of this totalizing epidemic. It is our belief, that the real-time mobile database connected to the cloud will be one of the central building blocks in this effort. Mobile devices are now ubiquitous across the globe, span all social classes, and provide the connecting gateway for all human communication. The cloud provides the baseline infrastructure for ensuring that all this communication happens in a structured and secure manner. The enabling technology that connects mobile devices to the cloud in an efficient manner is the real-time mobile database. Today, MongoDB Realm is the leading real-time mobile database in the world.

CosyncJWT is an authentication provider for developers building applications on top of MongoDB Realm. It is a based on JSON Web Tokens which is an industry standard RFC 7519 method for representing claims between two parties. CosyncJWT provides secure user authentication and identity management through an RSA encrypted public/private key protocol, which it manages on behalf of the developer.

CosyncJWT Authentication

JWT authentication is based on public/private key encryption. The CosyncJWT provider generates and signs JWT authorization tokens using a private key that is only known to the developer. The MongoDB Realm database stores the public key to verify the integrity of the JWT authorization token. In addition to generating JWT authorization tokens, the CosyncJWT provider also performs other authentication services such as user registration, two-factor verification, user management, signup, and invitation functions.

The purpose of a CosyncJWT authentication system is to handle routine user authentication and onboarding functions on behalf of a MongoDB Realm application. It also provides a trusted hub for managing the application users and for analyzing signup and invitation flows. Since JWT tokens are based on RSA public/private key encryption, it would be extremely difficult to stand up a man-in-the-middle attack between the CosyncJWT authentication provider and the MongoDB Realm application that depended on it.

MongoDB recommends JWT authentication as the preferred method for authenticating users into a Realm Platform application. CosyncJWT is a simple service intended to save developers time in implementing this functionality.

For more information about CosyncJWT, please to the Cosync website

To download the open source code for our sample application, please go to the following GitHub repository

Terms and Definitions


  • CosyncJWT portal website for developers
  • CosyncJWT REST API for MongoDB Realm applications

In order to use the service, a developer must register an account through the CosyncJWT portal. The primary purpose of CosyncJWT portal website is to manage user authentication and authorization on behalf of MongoDB Realm applications. The CosyncJWT developer portal provides functionality for a developer to manage application users through a coherent web interface.

The CosyncJWT REST API provides a runtime service through which a MongoDB Realm desktop/mobile application can perform user authentication and connect to the application that was setup in the CosyncJWT portal.

Cosync JWT Portal & REST API


A CosyncJWT application maps onto a MongoDB Realm instance and performs the authentication function on its behalf. Both the CosyncJWT application and the MongoDB Realm instance are used by the end-user application that is installed on a mobile device. This three-way mapping is isomorphic.

The end-user application could be implemented in one of the five development languages being supported by MongoDB Realm, which include:

  • Swift
  • Objective C
  • Java
  • Node.JS with JavaScript
  • NET

The CosyncJWT system provides GitHub repositories with examples in Swift and JavaScript for the developer to get going with. Over the next few months, we will provide sample code in all five languages.

An application within the CosyncJWT portal has a number of core attributes that define it, and a number of application settings that regulate its authenticating behavior. The core attributes include:

  • App Name
  • App Id
  • App Token
  • App Public Key
  • App Private Key
  • App Status

The App Name is a descriptive name for the application; it must be unique within the list of applications owned by the developer. The App Token is used by a client application to access services from the CosyncJWT REST API. The App Public Key is by the MongoDB JWT Authentication mechanism to verify the validity of user JWT login tokens that are passed to by the CosyncJWT service. Since only the CosyncJWT service holds the private key for signing purposes, this would prevent a man in the middle attack from passing the application a counterfeit JWT token from any other source than Cosync JWT. The App Private Key is held by the CosyncJWT portal and is used to sign JWT authorization tokens after it has authenticated the user on behalf of the application. The App Status determines whether an application is active, inactive, suspended, or blocked.

An application also provides a number of settings that control the finer aspects of its behavior.

  • App Type
  • Two Factor Verification
  • App Invitation
  • App Signup
  • App Signup Flow
  • Password Filter
  • User Id Format

App Type

Two-factor verification

  • none
  • google — through the Google Authenticator app
  • phone — through SMS login codes sent through TWILIO

The Google Authenticator app has the advantage of being free and ultra-secure because the 2-factor codes are rotated every minute. For more information about the Google Authenticator application, please consult the following

The phone form of two-factor is through SMS login codes that are sent to a user through a developers TWILIO account. For more information about TWILIO see the following

To enable SMS login codes to perform two-factor authentication for an application, select `phone` and enter the following information associated with your TWILIO account

  • TWILIO account SID
  • TWILIO Auth Token
  • TWILIO Phone Number

This information is only available to developers with paid TWILIO subscriptions. The advantage of using SMS login codes is that it does not require setting up the Google Authentication application. The disadvantage is that each SMS login code cost the developer money. For applications with large user bases, this cost can add up.

App Invitation

App Signup

App Signup Flow

  • none
  • code
  • link

If none is selected, users can sign up to the application without verification. If code is selected, users are sent a code to their handle to verify their identity and have to enter the code in a secondary signup phase. If link is selected, the user handle is sent a link, which the user can click on to confirm their identity. The HTML of the link landing page can be configured by the developer.

Password Filter

  • minimum length
  • minimum upper-case letters
  • minimum lower-case letters
  • minimum number of digits (0…9)
  • minimum special characters

The special characters include @, %, +, \, /, ‘, !, #, $, ^, ?, :, (, ), [, ], ~, `, -, _, ., and ,

User Id Format

  • uid
  • handle

The uid format generates a 32-byte globally unique identifier for each user Id in the MongoDB Realm application e.g.


The handle format uses the primary handle as the user id. In the case of an email handle, the format is the email with the ‘@’ character replaced by an underscore, so the email would have a user id of

Admin Users

For security reasons, admin users must be created explicitly in the CosyncJWT portal website by the developer, who must take extra precautions to never share the admin user’s JWT authorization token.

CosyncJWT Portal Website

The user interface of the CosyncJWT Portal website is extremely easy to understand, and maps conceptually to the MongoDB Realm cloud portal. Where MongoDB Realm uses the term instance, the CosyncJWT Portal uses the term application. Cosync applications map in one to one manner onto MongoDB Realm instances.


The public key can either be in a standard format with a — — BEGIN PUBLIC KEY — — header, which should be copied into the Realm Public Key section described below to configure the Realm MongoDB instance, or it can be in a string format to be used by crypto functions within an app. The App Token should be copied to the application constants file of the client application source code to be used in the HTTP header for any REST calls to the CosyncJWT Rest service.

The Show Super User Token function is used to generate a JWT token and an access token for a superuser admin user. The superuser JWT token can be used by a backend Node.js server that responds to events on the MongoDB Realm instance, where it would need to do so with admin privileges. The superuser access token is needed for specific REST calls to the CosyncJWT Rest service pertaining to setting application data.

The App Token should also be copied and pasted into the constants file of the applications code. It is this JWT token that is used by the CosyncJWT REST API to authenticate the calling application.


  • Setting up a Realm instance for Cosync JWT
  • Logging in a user into a MongoDB Realm application using Cosync JWT
  • Onboarding a user into a MongoDB Realm application using Cosync JWT

The CosyncJWT system provides a REST API through which applications can perform the login and onboarding functions. For onboarding, the system provides both a signup and an invite mechanism.

A signup mechanism allows users to onboard into the application directly. The invite mechanism requires that a new user be invited into the application by a user that is already registered with it. The invite mechanism is typically used by application that want to maintain tighter control over those users that belong to it.

Realm Instance setup

In a first step, the developer must create an application in the applications section of the CosyncJWT portal website. In a second step, the developer should copy the Realm Public Key in the Keys section of the application to the clipboard.

In a third step, the developer should sign into the MongoDB Realm portal for the application instance that maps to the CosyncJWT application and go to the Settings section.

In a fourth step, the developer should click on JWT to enable it as a form of authentication for the MongoDB Realm instance. And then paste the Realm Public Key that was copied to the clipboard in the second step.

By setting the public key for a specific application from CosyncJWT, the developer is ensuring that only an authenticator with the matching private key would be able to produce signed JWT tokens that match the public key. Since RSA public/private key encryption is near impossible to break, this pretty much assures the developer that his account with CosyncJWT is the only signing authority out there.

Lastly, the Realm Instance portal does present some advanced settings, for the moment CosyncJWT is built around the default values for these advanced settings so there is no need to change them.

Click Save and complete the setup of the JWT authentication for the Realm instance.


Login Flow

If two-factor verification is enabled for the user, the application will first issue a login CosyncJWT REST function call, and then wait for a six-digit verification code to be sent to the user’s phone number for identity confirmation. The application will then issue a loginComplete CosyncJWT REST function call to complete login process.


Both the signup and invitation process allow the user to pass structured onboarding data, which is saved in the user record after its creation. CosyncJWT makes no claims as to the structure of this onboarding data, which could contain user roles for the new user or coupon codes.


Signup Flow


Pricing Model

The base CosyncJWT service is free — and offers a developer up to three development applications limited to 50 users each.

The standard CosyncJWT subscription is $2 per month and includes up to three commercial applications of up to 1000 users each.

For commercial applications that exceed 1000 registered users, the developer is charged $1 per 1000 users per month, on a pay-as-you-go plan.

A paid subscription can be suspended. When that happens, the developer will be charged for all accrued pay-as-you-go user charges and login services to the developer’s applications will be suspended.




I have been a software entrepreneur for the past 25 years and an iOS programmer for the last eight years. I am the founder of Cosync, Inc.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Richard Krueger

I have been a software entrepreneur for the past 25 years and an iOS programmer for the last eight years. I am the founder of Cosync, Inc.