Dev Blog: Enabling Self-Registration in InformaCast Mobile

Tags: 
informaCast-mobile-self-registration-development

Each month, we have a member from the Singlewire Software development team present a deep-dive, behind-the-scenes look at a recent project. This month, one of our software engineers, Ben, walks us through the recent addition of self-registration to our InformaCast software.

The Problem

Customers want more flexibility and lighter restrictions when adding external users, i.e. users that aren’t part of their “core” organization, to InformaCast.

Of the two features currently available to them, user loaders and distribution lists with campaigns, customers often thought that user loaders required InformaCast administrators to know too many details about these external users, and distribution lists with campaigns were too short-lived.

Singlewire took these concerns to heart and created self-registration.

The Solution

Self-registration takes the burden of adding external users to the system from InformaCast administrators by allowing these users to signup themselves.

Self-registered users authenticate via the Singlewire built-in identity provider, and immediately upon signing up, they’re directed to their profiles where they can add the devices on which they want to receive notifications, sign up to distribution lists from which they want to receive notifications, and opt out of notifications that don’t interest them.

In addition, InformaCast administrators can customize the Self Service interface (and that of the Administration Console) with their own color scheme and logo, providing a branded experience during the entire process.

The Design and Implementation

While registering new users sounds simple, there are many important pieces to consider to make the solution above work, such as supporting multiple identity providers, the branding experience, the sign-up flow, and increasing users’ power.

Supporting Multiple Identity Providers

Until now, InformaCast only supported one identity provider per customer. In order to support self-registration, every customer will now get an additional Singlewire built-in identity provider if they currently use one of the supported third-party identity providers, e.g. Azure, Okta, Google, etc.

The key advantage to this additional identity provider is that an organization's users can now belong to different login systems, i.e. administrator-registered users belong to Okta while self-registered users belong in the built-in identity provider. For example, a school district can keep "internal" users like its students and teachers separate from external users like parents.            

In order to facilitate this change, a database migration handles decoupling and simplifying our data modal. This migration is important for two reasons:

  1. It creates a one-to-many relationship between customers and their identity providers. In the future, Singlewire intends to support a number of identity providers for each customer and let users move between them.
  2. It decreases the size of our data tables.        

Singlewire also added a new providerIdpId attribute to the /users resource to specify the identity provider to use for authentication. This also allows for future flexibility when we provide more control over identity provider settings to customers. For this release, only self-registered users will have a non-NULL value, which will be the ID of their provider's Singlewire built-in identity provider. Every other user will have NULL which indicates they will use the customer's default identity provider.                

For this release, both GET and PUT requests are valid request types on the new /idps endpoint. An example response for a GET to the /idps/:idpId endpoint looks like this:

Note: Since this Google IDP has its isDefault value set to true, users will use Google for their identity provider when no alternate IDP ID is specified.

A Branded Experience 

In order to visually assist users with navigating both Self Service and the Administration Console, administrators are able to configure custom branding, which can include a new primary color, secondary color, logo, and even custom help content for Self Service users.

This same logo and color scheme will be visible while logging in, registering, and using the web application to facilitate a clear and consistent experience.

To store this new data, we added a /brandings endpoint in our cloud REST API. Since each of our services has access to this resource, we can issue a GET request to /brandings/:brandingId for a response that looks like this:

We can easily extract the primaryColor and secondaryColor and apply them to a page.  For the logo data, we issue a separate request to the /brandings/:brandingId/logo endpoint.        

The Sign-Up Flow

From the end-users' perspective, the sign-up process feels pretty similar to the login process. They click the "Sign up here" link on the login page, submit their information, and receive a confirmation email before finally logging in. The data flow that makes this possible is a bit more interesting.    

When administrators enable self-registration in the Admin Console, a PUT request is issued to the /idps/:singlewireIdpId endpoint with a simple payload: 

After successfully setting this value, InformaCast knows to show the "Sign up here" link on the login page. Additionally, when new users click that link, we pass the providerId, which is specific to an organization, and register flag set to true as query parameters. This informs the built-in Singlewire identity provider's microservice about the branding information to query and whether the system is in "register" mode.

Once new users submit the registration form, InformaCast redirects back to our REST API, which handles these requests at the /oauth2callback route. It unwraps the request, checks for any errors, and determines if the user-specified email already belongs to users in the system. If no users are found and the register flags are true, new users are created. They can then finish logging in successfully and view their profiles.    

More Power to the User

For this project, Singlewire is also excited to introduce distribution list subscriptions. Traditionally, InformaCast administrators were responsible for adding and removing users to distribution lists. They now have the option to move this task to users themselves.

A new "Allow Users to Subscribe" checkbox in the Distribution List form controls this behavior. Each distribution list with its isSubscribable attribute set to true appears in a list titled "Available Subscriptions" in Self Service mode. When a user checks a box in the "Subscribed" column, it issues a PUT to the user/:userId/:subscribable-distribution-lists/:listId with a payload shaped like the following:

This tells Singlewire’s cloud REST API to insert a new record for User 4095f2ca-2852-11eb-8f82-cff6dd4ca1de and Distribution List 0dfd8675-2852-11eb- 8f82-e3fd246447c5. Unsubscribing is as simple as setting the isSubscribable attribute to false which deletes the record.

The Final Product

Self-registration is now available. We believe our customers will thoroughly enjoy the simple registration process, organization-specific branding, and enhancements to Self Service like distribution list subscriptions. With the help of customer feedback, we look forward to continually improving this feature.

 

 

InformaCast Online Demo