What is a CosyncJWT Application?

Within the Cosync Portal, a developer maintains a number of applications that each contain a collection 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.

An application within the Cosync Portal maps onto a MongoDB Realm Application that is being implemented by the developer, which uses JWT authentication. The mapping between a Cosync application and a MongoDB Realm Application is isomorphic. In the older Realm Cloud product, an application was called a Realm instance.

A MongoDB Realm Application is typically linked to a MongoDB Atlas Cluster that defines the data base for the application. A cluster contains a list of collections that contain objects that conform to cluster’s schema. A MongoDB Realm Application maps a particular Realm onto MongoDB Atlas Cluster through a concept called a partition key value. The partition key is a predetermined property key name, e.g. _partition, that contains a value. The partition key name is determined by the developer at the time MongoDB Realm Application is created. In order for an Atlas collection to be mapped into a Realm, it must contain a property with the same name as the partition key, e.g. _partition. It is the value of the partition key that defines which Realm the object in the Altas collection belongs to. The way to think about it is as follows, Altas maps objects into collections. Realms are a mapping upon the mapping and define objects within multiple collections as belonging to a specific Realm. In the old Realm Cloud product, individual Realms within a Realm Instance were more like collections within an Atlas database. However, in order to blend the two concepts together, the new MongoDB Realm created the concept of partitions. This concept is best explained here MongoDB Realm Partitioning

The CosyncJWT service can be used as a JWT authentication provider for a MongoDB Realm Application, which is managed through the MongoDB Realm Application portal at MongoDB. Setting up the CosyncJWT service is extremely easy. The first step involves creating an application with the Cosync Portal website that maps on the MongoDB Realm Application that is created in the MongoDB Realm Application portal.

An application within the Cosync JWT portal has the following attributes:

• Name
• Type (development or commercial)
• Status (active, inactive, suspended, or blocked)
• Two-factor authentication
• Onboarding
• JWT meta-data
• Realm public key
• JWT password filtering
• Application token (appToken)
• Users

The application name is a descriptive name for the application; it must be unique within the list of applications owned by the developer. It can also be changed at any time. The application id is a unique global identifier (GUID) that is assigned to the application at creation.

Application Type

The Cosync Portal 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 Cosync JWT system. The base subscription, which is six dollars $6 per month, includes up to 5000 (five thousand) commercial application users. For commercial applications that exceed the initial 5000 users, the cost of pay as you go is one dollar per thousand users per month, or $0.001 per user per month.

Application Status

The CosyncJWT application status determines whether an application is operational or not. There are four possible application status values

• active
• inactive
• suspended
• blocked

If the application status is active, it is up and running and can allow users to be authenticated into it. For a commercial application, subscription charges will only apply when the status is active. At any time, a developer can choose to set the status of an application to inactive. When this is done, all REST API calls to the application will no longer work - including login. If a developer fails to pay his subscription and commercial app charges, either because the credit card has expired, or he/she has requested reimbursement for those charges, the application status is set to suspended, which is functionally equivalent to inactive. Once a developer has submitted proper payment, a suspended application can be once again turned into active from the Cosync Portal. If an application violates the terms of service for Cosync, the application may be blocked by the systems administrator. If this were to happen, the developer would need to contact Cosync to reinstate a blocked application to an active status.

Onboarding & Meta-Data

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. Alternatively, the new user can be sent a link to verify his/her identity. Whether a code or a link is sent to the user is controlled through the application’s signup flow controls. 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 metadata data, which is saved in the user record after its creation. This metadata is also passed through as metadata fields in the JWT token. Cosync JWT makes no claims as to the structure of this meta data, which could contain user roles for the new user or coupon codes. This meta-data is specified in the JWT tab of the application section in the Cosync Portal website.

The Cosync Portal provides a developer with a mechanism to enable/disable signup and invitation for all their applications. This is also in the JWT tab of the application section.

Two-Factor Verification

CosyncJWT supports two-factor verification to better secure a user’s identity within an application. There are three two-factor verification settings:

• none
• google
• phone

The default is none, where an application does not require a user to authenticate beyond providing a matching password at the time of login.

The google two-factor authentication is both free and secure. This system works by having the user install the Google Authenticator app on their device link. The Google authenticator app works by sending a one-time password to the user’s app, which is update every minute with a new password. The user sets up the Google authenticator app on a device by providing an app secret key (which is provided by CosyncJWT) and encoded in a QR encoded image that can be scanned by the app. The advantage of using the Google authenticator is that the developer does not incur SMS phone charges for each code authentication message sent on login.

The phone two-factor authentication provides a traditional SMS based two-factor authentication code for login. In this scenario, the user is sent an SMS message to their verified phone number at the time of login. Login is a two step process in which the second step involves entering the code that was sent to the user’s device for further authentication. The phone two-factor authentication function is implemented in CosyncJWT using the developer’s TWILIO account. To enable this function, the developer must provide:

• TWILIO Account SID
• TWILIO Auth Token
• TWILIO phone number

All these are available with a commercial TWILIO account.

Two-factor authentication is a multi-tier process. First, it must be enabled at the application level by the developer within the Cosync Portal. In a second step, the user must enable individual two-factor authentication at the application level. For google authentication, this means setting up the application for two factor verification in the Google Authenticator app. For phone authentication, the user must provide a verified phone number that is first checked with a code. After that, CosyncJWT will send the user an SMS code for every login attempt.

Two-Factor verification settings are controlled in the JWT tab of the application section.

Realm Public Key

When a developer creates an application, the CosyncJWT system generates an RSA public/private key pair for JWT authentication. The private key is kept hidden in an encrypted form within the CosyncJWT database, the public key is available in the interface presented to control the application with the Cosync Portal. Typically, this public key is copied and pasted into the MongoDB Realm instance settings within the cloud.

The Realm Public Key is available in the KEYS tab of the application section within the Cosync Portal.

Application Token

The CosyncJWT appToken is itself a JWT token used by the MongoDB Realm application to log in to the REST API Service for Cosync. The appToken identifies which application and developer is using the REST services, and it provides a passport of sorts to those services. The appToken is generated at the time the application is created.

The appToken is available in the KEYS tab of the application section within the Cosync Portal.

JWT Password filtering

The CosyncJWT authentication service also includes password filtering functionality. This is used to impose minimum password requirements on the authenticating user as far as their password is concerned. Password filtering includes requirements like:

• minimum password length
• minimum number of upper case letters
• minimum number of lower case letters
• minimum number of digits
• minimum number of special characters

Password filtering is actually enforced by the client-side application code during signup, or change password. The special characters include @, %, +, , /, ‘, !, #, $, ^, ?, :, (, ), [, ], ~, `, -, _, ., and ,

The Password filtering settings are available in the JWT tab of the application section within the Cosync Portal.

Users

Lastly an application within CosyncJWT is populated by a collection of users who are authenticated to use it. CosyncJWT keeps around the handle and password for those users - it does not keep any additional private information about the users.