Realm Blog

BYO Authentication: Connect Your Users to the Realm Mobile Platform

We’re making it easier than ever to integrate your existing systems with a modern mobile app, by introducing Custom Authentication on the Realm Mobile Platform. With a few lines of JavaScript, you can bring your own authentication to Realm, allowing your users can log in with their existing credentials and begin using any app built on the Realm Mobile Platform. Using Custom Authentication, you’ll be able to build modern mobile apps with single-sign on (SSO) capabilities, and you can even mobilize your whole legacy backend by integrating our new data connector API, so that your users get access to the data and capabilities they expect.

Legacy systems put you in a double bind when you want to build a new, useful mobile app. If you use your existing backends, it’s likely to be incredibly hard to build the new features your users demand — features that require streaming lots of data from many sources, which tend to overwhelm APIs built for a calmer web. But migrating your API to a more developer-friendly platform is likely to be even harder, exposing you to new security risks in untested authentication APIs, and forcing you to solve problems that you thought you already put behind you, this time in a new language and framework.

Wouldn’t it be great to keep the hard work you put into your API, while also getting all the modern development tools that make it easier to build better apps? That’s what bring-your-own authentication does for the Realm Mobile Platform. You get to integrate Realm with your trusted legacy authentication APIs, so that your users simply bring their username and password (or any other tokens or credentials) to your mobile app, and the Realm Mobile Platform handles the work of authenticating them against your existing API. Your developers don’t just avoid rewriting all their auth code: they also get realtime data sync, offline-first capabilities, and enterprise-grade data connectors for your existing databases and backends — all benefits that you get from building your app on the Realm Mobile Platform.

Here’s what it looks like in practice: you just write one short JavaScript file, then add a line to your configuration.yml file:

module.exports = function(deps) {
  return class FooAuthProvider extends deps.BaseAuthProvider {
    // This is used by the ROS when it loads the available
    // authentication providers. This function is required.
    static get name() {
      return 'custom/fooauth';

    // This is used by ROS when it parses the configuration
    // file, to ensure that required default options are
    // available. This function is optional.
    static get defaultOptions() {
      return {
        auth_server: 'https://my.auth.server.example',

    constructor(name, options, requestPromise) {
      super(name, options, requestPromise);

      // Here you can set your instance variables as usual
      this.httpMethod = 'GET';

Now we get to the substance of the authentication provider, where we’ll make a request to your authentication API using the credentials that the user provided:

verifyIdentifier(req) {
  // The token submitted by the client
  const token =;
  // The client SDKs also support sending additional information
  // in the form of a map/dictionary. This is accessible through
  // the `req.body.user_info` key.

  // The information required to reach your API server that can
  // validate the token. Obviously, this assumes a REST-like API.
  // Please note that `this.options` comes from the configuration file or
  // `defaultOptions()` method defined above. Similarly, `this.httpMethod` is
  // an instance variable defined in the constructor above.
  const httpOptions = {
    uri: `${this.options.authServer}/api/auth?token=${token}`,
    method: this.httpMethod,
    json: true,

  return this.request(httpOptions)
    .catch((err) => {
      // Please see src/node/services/problem/http_problem.js
      // for other error cases
      throw new problem.HttpProblem.Unauthorized({
        detail: `Something bad happened: ${err.toString()}`,
    .then((result) => {
      // This userID has to be unique, and will be used to either
      // - create a user in the ROS
      // - login the user, if it already exists
      return result.userID;

By combining easy authentication with the data connector API, you’ll also be able to connect your apps to the data stored behind your legacy systems. Whether your API is as old as SOAP or just as request-driven as REST, the Realm Mobile Platform’s data connector API will give your users real-time, streaming access to their data they need, and your developers get to use the modern, reactive features of the Realm Mobile Database. You’ll be able to build great app experiences quickly, without trying to teach your older, legacy systems the new tricks they’d need to deal with the scale demands of mobile apps.

To start moving faster on your own mobile journey, just jump into the documentation for custom authentication. If you’d like to learn more about how to completely integrate the Realm Mobile Platform with your legacy databases as well, check out our new PostgreSQL data connector API.

Realm Team

At Realm, our mission is to help developers build better apps faster. We provide a unique set of tools and platform technologies designed to make it easy for developers to build apps with sophisticated, powerful features — things like realtime collaboration, augmented reality, live data synchronization, offline experiences, messaging, and more.

Everything we build is developed with an eye toward enabling developers for what we believe the mobile internet evolves into — an open network of billions of users and trillions of devices, and realtime interactivity across them all.

Get more development news like this