fxa-auth-server/docs/service_notifications.md

Firefox Accounts Attached Service Notifications.

Mozilla-hosted services that integrate with Firefox Accounts have certain additional data-handling requirements, such as a requirement to delete user data when a user deletes their Firefox Account.

To help services meet these requirements, FxA publishes a stream of notification events to SQS. If you would like to connect your service as a consumer of this stream, please email fxa-staff@mozilla.com for assistance.

Each notification event has a JSON body with an "event" key naming the type of event, and other keys that vary depending on the type of the event. The types of event, the additional data they contain, and the actions that attached services should take in response are described below.

Due to the details of how events are published to SQS, the event body is double-JSON-encoded inside a wrapper object with a "Message" key, so an example event would look something like this:

{"Message": "{\\"event\\": \\"delete\\", \\"uid\\": \\"d755addd247aa18e700486da98778fe3\\"}"}

For an example of how to process these events in practice, you can take a look at the event-handling code from the sync tokenserver (python). or the FxA profile server (nodejs).

Common Event Properties

All notifications will include the following properties in their JSON body object:

• event: A string identifier for the type of event that occurred.
• ts: Integer timestamp when the event occurred, in seconds.
• metricsContext: optional object containing metrics parameters such as utm_campaign and utm_source.

Since SQS does not guarantee order of delivery of events, reciving services should use the ts field to help handle events that may have been received out-of-order.

Account Verification Event

Message Properties:

• event: The string "verified".
• uid: The userid of the account being that was created.
• email: The primary email address that was verified for the account.
• locale: The accept-language header supplies by the user at account creation.
• marketingOptIn: Optional, boolean, whether the user opted-in to marketing emails.

Receiving services should use this message to initialize any state that needs to exist for all Firefox Accounts.

It's currently consumed by the email marketing team, and new services probably shouldn't use it, and instead prefer initializing state on demand when seeing a user for the first time.

Account Login Event

Message Properties:

• event: The string "login".
• service: The name of the service that was logged in to. Currently always "sync".
• uid: The userid of the account being that was used to log in.
• email: The primary email address of the account.
• deviceCount: The number of active sessions on the user's account.
• userAgent: The user-agent header sent by the user on their login request.

This event is currently consumed by the email marketing team in order to manage sync-setup-related email campaigns. New services probably shouldn't use it.

Account Deletion Event

Message Properties:

• event: The string "delete"
• uid: The userid of the account being deleted
• iss: The API server that issued the event ("api.accounts.firefox.com" in production environments)

Services receiving this event should delete any data held on behalf of the user, taking particular care to purge any PII such as email address.

Since the uid is an opaque identifier with no PII, esrvices may keep the account uid after deleting the user's data if that simplifies their internal implementation.

Password Reset Event

Message Properties:

• event: The string "reset".
• uid: The userid of the account that was reset.
• iss: The API server that issued the event ("api.accounts.firefox.com" in production environments)
• generation: A monotonically increasing integer for de-duping events (ok ok, it's a timestamp).

Services receiving this event should terminate user login sessions that were established prior to the event.

For Sync, the Sync authentication flow exposes the "generation" number directly to the service, so it can deny access to any requests with a generation number lower than the one received in this event.

For other services, there is no way to know the generation number associated with a previous login. It's probably best to ignore generation and instead terminate login sessions established prior to the timestamp in ts.

Password Change Event

Message Properties:

• event: The string "passwordChange".
• uid: The userid of the account that had its password changed.
• iss: The API server that issued the event ("api.accounts.firefox.com" in production environments)
• generation: A monotonically increasing integer for de-duping events (ok ok, it's a timestamp).

As with the "reset" event above, services receiving this event should terminate user login sessions that were established prior to the event.

Change of Primary Email Address Event

Message Properties:

• event: The string "primaryEmailChanged".
• uid: The userid of the account that was updated.
• email: The email address that is the new primary for the account.

Note that the message does not include the previous primary email address. Receiving services should use the uid to uniquely identify a user, and should update their records of that user's preferred email address.

Change of Profile Data

Message Properties:

• event: The string "profileDataChange".
• uid: The userid of the account that was updated.

Receiving services should update any cached profile information that they hold about the user, such as their display name or 2FA status.

Device Connection Event

Message Properties:

• event: The string "device:create".
• uid: The userid of the account to which a device was connected.
• id: The id of the device that was connected.
• timestamp: Integer millisecond timestamp at which the event occurred.
• type: The type of device, e.g. "desktop" or "mobile".
• isPlaceholder: Boolean indicating whether the device explicitly registered itself, or had a device record implicitly created by the server.

Services that know about connected devices should, upon receiving this event, make accommodations for any state that may need to be stored for that device

Sync is the only service that currently knows about connected devices, so other services probably shouldn't use this.

Device Disconnection Event

Message Properties:

• event: The string "device:delete".
• uid: The userid of the account from which a device was disconnected.
• id: The id of the device that was disconnected.
• timestamp: Integer millisecond timestamp at which the event occurred.

Services that know about connected devices should, upon receiving this event, discard any transient state stored for that device and deny any future access requests made on behalf of that device.

Sync is the only service that currently knows about connected devices, so other services probably shouldn't use this.