Registration Design

The Use Case is here: Register Device

Overall process

Diagram Below

  • Authentication depends on availability of a "native" platform. 3rd-party Auth is performed via calls to external website which depends on Cordova functionality. If this isn't available, the Access Token needs to be set to an agreed-upon token specific for non-native platforms. The PlatformService knows if we're running native or not.
  • The Access Token (expired or not) plays a prominent role in steering the initial logic.
  • Clearing the Access Token had been a good way to force registration, but with iOS, it's not as easy to get to the storage. I've created a separate menu item that provides the ability to clear state.
  • One test of whether or not the Access Token is valid occurs on the back-end (Check Registration API). Using this Access Token to inquire "userinfo" from the 3rd-party site is also how the back-end picks up the profile information. (There is also potential to cross-check this with what came across in the JWT token.)
  • Expiration data is stored when a new access token is either created or renewed. This timestamp (with a grace period) is used to tell if the access token needs to be renewed or not. NOTE: there is no way to use the back-end or Auth0 to learn what the expiration time of the access token will be or has been.

Value provided

  • Verifying an Email Address to serve as Principal in both ClueRide system and the BadgeOS system.
  • User is offered choices of how to verify their chosen email address: social accounts (Facebook, Google, etc.) or by directly entering an email. (By doing this App Side, we can provide the guidance for selecting between the choices.)
  • Allowing the use of a short-lived and opaque "access" token to be established for identifying the session and sharing the identity information.
  • Sharing of sensitive information only occurs with trusted devices.

Captured Data

Since this entire set of data is cleared from web storage upon logout, there would be no record on this device of previous attempts to register.

Key Value Description Upon Logout/Deregister/Retry Upon Refresh
profile profile JSON representation of User Profile Cleared Updated
jwtToken id_token Raw JSON from 3rd-party auth provider Cleared Updated
accessToken access_token Provided within Auth Header Cleared Updated
refreshToken refresh_token Provided during renewal call Cleared (and invalidated server-side) No action
expiresAt expires_at Timestamp of the access token expiration Cleared Updated
registrationType registration_type Either SOCIAL | PASSWORDLESS Cleared No action


Design Page for Auth0: Auth0 Design

Auth0 provides the following desirable features:

  • Works with Ionic apps
  • Passes back and forth an opaque and short-lived access token, unique for each user and session.
  • Provides Social Logins. (There is a limit of two, but Google and Facebook are good entry points).
  • Infrastructure and support for
    • handling multiple apps
    • logging attempts and failures

Device Identification vs Installation Identification

FUTURE items for the most part, but good to keep in mind:

  • Registering other devices should be handled (FUTURE, but don't paint ourselves into a corner)
  • Hardware ID is useful to confirm that the device is indeed the device we think it is, but this can't be used to completely determine the Member — the device may be wiped and then handed to someone else for their use. Need link between device ID (to tell when device has changed or allow multiple devices) and the Member's Principal.
  • Identify a given installation since a particular device may be wiped and then handed to someone else; don't want to think that the new user should be afforded the same identification as the previous user. Discussion conducted here:
  • It does make sense to capture the information that is available in the Ionic Platform API: within the database as part of registration:
    • Platform type: ios, android, etc
    • Platform form factor: height/width of display

Functionality to be Provided

This lists the functionality and the service which will be responsible for handling the functionality. This also lists the events that provide separation and which help manage the dependencies.

Name Service Event?
Check Platform Ready RegStateService Asynch => Synch
Setup Custom Scheme Callback RegStateService Wiring the Callback
Native platform? PlatformService
Expiration Check TokenService
Renewal Prep RenewalService
Renewal Post RenewalService Asynch to Auth0
Renewal Digest cell-content Upon Auth0 response
Retrieve Tokens TokenService
Persist Provisional Tokens TokenService
Persist Confirmed Tokens TokenService
Persist Renewed Tokens TokenService
Clear Provisional Tokens TokenService
Clear All Tokens TokenService
Hide Splash Screen ?? After first Screen is shown
Handle Exceptions NotificationService
Present Registration Options RegistrationPage Via App responding to event
Register Auth0 Prepare RegStateService
Register Auth0 POST RegStateService Asynch to Auth0
Register Auth0 Callback RegStateService Inbound from Auth0
Prepare Profile from JWT ProfileService & TokenService
Present Profile for Confirmation ConfirmPage Via App responding to event
Confirm Registration ConfirmPage calling RegStateService Inbound from User
Retry Registration ConfirmPage calling RegStateService Inbound from User
Update Profile on Backend RegStateService (maybe (separate Update)ProfileService) Asynch with Backend

State Diagram



  1. Client requests Registration State for the application identified by its URL scheme. This triggers the initial state transition and returns an Observable which will return the RegState once it is settled. This could be nearly immediate if the access token is valid, quickly if the access token needs to be renewed, or after several seconds or even minutes if the user is walking through the choices required to choose a suitable email address.
  2. PlatformStateService tells us if we're running Native or not. If not native, we set the BDD token and issue ACTIVE A event.
  3. If Native, we ask the TokenService if the token is present. If No token at all, we need to show the registration page.
  4. If we do have a token, the Renewal Service can synchronously check if it is expired. The Token Service will have the information needed to determine expiration. If it is still active, we issue the ACTIVE B event.
  5. If the access token needs to be renewed, the Renewal Service is invoked asynchronously to obtain a new token and a new expiration timestamp. If successful, the Active C event is issued. If not, an Error is issued.
  6. If there is no token at all, and the registration page has been shown, the user will be given a choice of registration methods: Social and Email (Passwordless). The key is to assure the associated email account is the one which will accumulate the badges. The user initiates the next state transition by Selecting the Authentication Method.
  7. Whether Social or Email, execution control is passed to the Auth0 website to perform the authentication. Upon completion, we receive a Callback.

Usage of Reg State Service

NOTE: We will want the main app to control the presentation of the Registration Page. This needs to be coordinated against its navigation scheme at this time. (Perhaps the routing will help with this in Ionic 4).

  • Client subscribes to the RegState Observable and awaits events. Possible events are:
    • SessionActive (with detail about how it became active: A, B, C, H)
    • Error (E, F)
    • Awaiting Confirmation (G)
  • Considering a separate subscription which would allow a client to present their own page. This would be Event D and would require the client to invoke the change of state within the RegState Service.

Notes on the State Diagram

  • Many of the components are re-usable.
  • Some components will be created as a separate parallel path to break dependency on other apps (MobiLoc in particular).
  • At this point, I haven't included any calls to the backend to "verify" that the access token will retrieve the same results that are provided via the JWT token. Note that I do want to make this call so we can establish a cached session with a known WordPress user account — or give the opportunity to create one.

Potential tickets

  • Create the Reg-State.service which sequences this set of states.
  • New renewal.service

Issues under Consideration

  • Whether to bring back error information for diagnostics — How are these errors being displayed? Toast and a post to the server logging the event?
  • Capture of Platform information as mentioned just above the diagram here.
  • How to handle the display of the registration page (the note is a proposal).
  • Do we need to invoke Auth0's Logout? Seems like this just takes us off-site. On the other hand, I'm not sure what's going on when I try to switch to a different account. Maybe the renewal token?
  • If I wanted to mock out the native Auth0 chunk, what would that interface look like?
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License