One-Time Token Event Documentation

[sjpadgett (Jerry P)]

I’ve implemented in production releases some use cases for one-time(misnomer).

• From Patient Assigned Templates send a notification to patient to request, via included token, addressing an assigned document/questionnaire. Token will open form in portal.
• A billing notification to patient that redirects to Online Payment in portal.
• @adunsulag implements in the telehealth module.
• By next patch users will be able to assign a timed token for portal log in. e.g. log in portal by clicking token.

Another new feature in rel-7.0.3 is expanding the portal whereto redirect to menu item as landing page after portal log in e.g.

https://localhost/openemr/portal/home.php?site=default&landOn=MakePayment
landOn query is used to redirect to a specific section of the portal.
$landOnHref = [
    'ClinicalDocuments' => '#onsitedocuments',
    'Appointments' => '#appointmentcard',
    'MakePayment' => '#paymentcard',
    'SecureMessaging' => '#secure-msgs-card',
    'HealthSnapshot' => '#lists',
    'Profile' => '#profilecard',
    'BillingSummary' => '#ledgercard',
    'MedicalReports' => '#reports-list-card',
    'PROAssessment' => '#procard',
    'Settings' => '#settings-card',
    'Help' => '#help-card',
    'Logout' => '#logout.php'
];

Below explains by example how to integrate and trigger a one-time token event for OpenEMR. The example process uses four main files of a current implementation:

• interface/modules/custom_modules/oe-module-faxsms/library/api_onetime.php
• src/Common/Auth/OneTimeAuth.php
• src/Events/Messaging/SendNotificationEvent.php
• interface/modules/custom_modules/oe-module-faxsms/src/Events/NotificationEventListener.php

These files work together to generate a one-time token, dispatch a notification event, and then process that event to notify users. This system is ideal for secure, one-time authentication scenarios.

---

1. Overview of the Components

api_onetime.php

• Purpose:
  Serves as the API endpoint that clients can call to request a one-time token.
• Functionality:
  • Accepts input parameters (such as a user identifier).
  • Uses the OneTimeAuth class to generate a secure token.
  • Dispatches a new event via SendNotificationEvent to notify the user about their token.
• Developer Notes:
  Customize this file to suit your routing and security needs. Ensure that proper validations and error handling are in place.

OneTimeAuth.php

• Purpose:
  Encapsulates the logic for creating and validating one-time tokens.
• Key Functions:
  • Token Generation: Creates a unique token for a given user.
  • Token Validation: Checks if a token is valid, has not expired, and matches the user’s request.
• Developer Notes:
  • Review the internal methods to understand token expiry and regeneration logic.
  • Modify the token algorithm if additional security measures are required.
  • Use the action flags to implement token actions such as require login to validate token PIN or limit portal access to assigned page.

SendNotificationEvent.php

• Purpose:
  Represents the event that is fired when a one-time token is created.
• Functionality:
  • Carries essential data such as the generated token, associated user ID, and any metadata required for the notification.
• Developer Notes:
  Use this class as the payload for any notification system integrated into your application.

NotificationEventListener.php

• Purpose:
  Listens for the SendNotificationEvent and processes it.
• Functionality:
  • When the event is triggered, this listener performs actions like sending an email or SMS with the token details.
  • You can extend or modify this class to integrate with your own notification services.
• Developer Notes:
  • Ensure that your notification system is secure and properly handles any failures (e.g., retry logic, logging).

---

2. Workflow: How the Event is Created and Processed

The following steps outline the typical flow from receiving a token request to notifying the user:

1. API Request:

• A client calls api_onetime.php (for example, via an HTTP POST request) and passes in required parameters (such as a user ID or email).

2. Token Generation:

• api_onetime.php instantiates the OneTimeAuth class.
• The generateToken method is called to create a secure, one-time token.

3. Event Dispatch:

• Once the token is generated, a new instance of SendNotificationEvent is created with the token and any related user data.
• This event is then dispatched using your project’s event dispatcher (or a custom mechanism if one is built into the framework).

4. Event Listening and Notification:

• The NotificationEventListener is registered to listen for SendNotificationEvent.
• When the event is fired, the listener processes it by, for example, sending an email or SMS to the user containing the one-time token.

5. Token Usage:

• The user receives the token and uses it (typically via a login form or API endpoint).
• OneTimeAuth validates the token (checking for authenticity and expiry), and then allows access if valid.

This is examples of one-time tokens from app

I hope this makes sense and is useful. Ask if you need help and I’ll try to get to you ASAP.