Cosync JWT authentication for MongoDB Realm
Summary
For the past few months, The COVID 19 pandemic has wreaked havoc on all forms of social and business interactions. Travel has grounded to a halt, all major conventions have been cancelled, and most directly facing service businesses have been shut down. This has led to unprecedented social disruptions on a global scale. Social distancing is now the rule for everyone everywhere, as the most basic mitigation strategy. As this crisis continues to develop, there has been a frantic move to substitute in person communication with software applications that provide an equivalent virtual collaborative experience.
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.
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 www.cosync.io.
To download the open source code for our sample application, please go to the following GitHub repository
https://github.com/Cosync/CosyncJWTSample
Terms and Definitions
Developers
CosyncJWT provider is primarily oriented to serving developers. The service has two components:
- 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.
Applications
Within the CosyncJWT portal, a developer maintains a number of applications — each of which contain a number of users. The portal provides a developer with functionality to create, edit, and delete applications. It also provides a developer with the capability to manage users within each application.
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
The CosyncJWT system supports two types of applications: development and commercial. A development type of application is limited to fifty users. A free trial account only supports three development applications. In order to create commercial applications, a developer must register as a paid subscriber to the CosyncJWT system. The base subscription, which is two dollars $2 per month, includes up to three commercial applications up to one thousand users each. For commercial applications that exceed a thousand users, the cost of pay as you go is one dollar per thousand users per month.
Two-factor verification
CosyncJWT supports two-factor authentication that provides an extra level of security for users logging into applications. It provides three methods for doing this:
- 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 https://en.wikipedia.org/wiki/Google_Authenticator.
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 https://www.twilio.com.
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 Invitation is one of the primary onboarding features of CosyncJWT. With app invitation, onboarding is controlled through existing users. In order to onboard through this mechanism, a user must be sent an email or text to their handle with an invitation code. The invitation can also include structured JSON data that further controls the parameters of the invitation. The developer has control over whether an application supports app invitation or not.
App Signup
App Signup is the other primary onboarding mechanism of CosyncJWT. With app signup, a user can directly signup to an application by providing a handle and a password. Verification of this handle is controlled through the App Signup Flow discussed below. App Signup is enabled by default but can be turned off at the discretion of the developer.
App Signup Flow
The App Signup Flow determines if and how a user signing up to an app verifies his/her identity. There are three possible choices here:
- 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
Password filtering is used to impose password requirements on application users when they onboard or change their password. Password filtering is implemented on the client side because the server only ever receives the MD5 hash of the password for security reasons. However, the developer specifies the password filtering parameters on the server side, which are saved as part of the application settings. The client side will query these filtering parameters and implement the password filtering requirements on behalf of the application. Password filtering can either be turned on or off. If turned on, there are a number of filtering parameters that regulate how a password should be formed, these include:
- 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
The user id format determines the format of the user identifier within the MongoDB Realm instance that uses the CosyncJWT service for its JWT authentication method. The User Id format specifies how users are recorded by MongoDB Realm. There are currently two user id formats supported by CosyncJWT
- uid
- handle
The uid format generates a 32-byte globally unique identifier for each user Id in the MongoDB Realm application e.g.
001ea5db6a214caca2a27534c3a91be1.
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 joe@smith.com would have a user id of joe_smith.com.
Admin Users
MongoDB Realm makes a distinction between regular users and administrator users from a security perspective. From Realm’s standpoint, administrators — or admin users — have super user privileges over all data in a Realm instance for an application. Typically, no end user within an application is an admin user, rather this role is reserved for server functions that perform back end processing on the Realm instance running inside a NodeJS process.
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 CosyncJWT service is accessed through the CosyncJWT Portal website that is located at https://cloud.cosync.net . This is the primary destination that developer goes to in order to manage JWT authentication for their MongoDB Realm applications.
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.
Keys
The keys section provides the public key used to enable JWT authentication within the MongoDB Realm instance associated with the application.
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.
Flows
In this section we document the flows for integrating JWT authentication/authorization within a MongoDB Realm application. The topics that are covered include
- 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
Setting up a MongoDB Realm instance for JWT authentication/authorization using CosyncJWT is very easy.
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
The login process into an application using CosyncJWT can either take place with one function call if two factor verification is not enabled, and with two function calls if it is enabled. In the first scenario, the application will issue a login CosyncJWT REST function call as illustrated in the following sequence diagram:
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.
Onboarding
The CosyncJWT provider supports two mechanisms for onboarding users into a MongoDB Realm application: signup and invitation. The first mechanism — signup — provides a public facing onboarding strategy for an application. Typically, a simple signup process requires that a new user provide an email and a password. The email is then sent a six-digit code to verify identity, which the new user must enter in order to complete the signup process. The invitation process is an onboarding mechanism that provides tighter control over who is allowed to join the application. In an invitation scenario, a registered user must explicitly invite a new user into the application. Typically, a simple invitation process involves sending an invitation email to a new user, who then registers with the application by providing the email and the invitation code.
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
The signup process can be used by a perspective user to onboard into an application. From a programming standpoint this is a two-step process. First, the application calls the CosyncJWT REST signup function with the email handle and some signup data. Second, the CosyncJWT provider sends a six-digit code to the email handle to verify the user’s identity. Third, the application calls the CosyncJWT REST CompleteSignup function with the new user’s handle, password, and code to complete the signup process.
Invite
The invitation process can be used to restrict onboarding to specific emails (or phone numbers) that are explicitly authorized by existing users in the application. Invitation is a restrictive process used to control access to an application. First, the application on a sender device calls the CosyncJWT REST invite function with the email handle and some invite data. Second, the CosyncJWT provider sends a six-digit code to the email handle to verify the invited user’s identity. Third, the application on the invited user device calls the CosyncJWT REST register function with the new user’s handle, password, and code to complete the invitation process.
Pricing Model
The CosyncJWT prices are both affordable and straightforward. The pricing is based on the number of users that are authenticated within a MongoDB Realm application.
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.
Company
The Cosync, Inc company was founded on June 1st, 2018. Its goal is to develop an extensible communication and collaboration engine platform that can be adapted to a wide variety of networking solutions. At its founding, the Cosync, Inc company merged with Afinos and acquired its intellectual property — a patent in the area of Collaborative User Interfaces and a system for doing real time collaboration in a shared windowing environment.
