Safewhere Identify domain events

Introduction

Identify has support for publishing events to message buses about changes made to its domain objects. Third-party applications can subscribe to receive notifications about these events.

Supported events

Currently, Identify only publishes user-related events.

Created event

This event is published when a new user account is created or when users register their authenticators (TOTP Authenticator, WebAuthn and Device Authentication). Actions that trigger this event include:

  • Identify Admin: create a user from the User list or users register their Authenticator on My Profile page.
  • REST API: /admin/api/rest/v2/users (POST), /admin/api/rest/v2/users/.batch (POST), admin/api/rest/v2/users/onboardauthenticator (POST).
  • Identify Runtime: users register their TOTP Authenticator, WebAuthn or Device Authentication.
  • IdentifyMe: users register their TOTP Authenticator or WebAuthn.

Updated event

This event is published when a user is updated or users login using Recovery codes. Actions that trigger this event are:

  • Identify Admin: edit a user in the Edit user page, the My profile page, and the Mass update functionality.
  • Identify Runtime: users logins using the Recovery Codes.
  • REST API: /admin/api/rest/v2/users (PUT), /admin/api/rest/v2/users/.batch (PUT), /admin/api/rest/v2/users/{userId} (PATCH).

Deleted event

This event is published when a user is deleted or when users de-register their authenticators (TOTP Authenticator, WebAuthn and Device Authentication). Actions that trigger this event are:

  • Identify Admin: delete a user from the User list and the Mass delete functionality, users de-register their Authenticator on My Profile page, administrator resets all authenticators of a user.
  • REST API: /admin/api/rest/v2/users/.batch (DELETE), /admin/api/rest/v2/users/{userId} (DELETE), admin/api/rest/v2/users/authenticators (DELETE), admin/api/rest/v2/users/resetauthenticator (DELETE), admin/api/rest/v2/users/resetwebauthn (DELETE), admin/api/rest/v2/users/resetdeviceauthentication (DELETE).
  • IdentifyMe: users remove their TOTP Authenticator or WebAuthn from their account.

Batch StatusUpdated event

This event is published when you change status of multiple users. Actions that trigger this event are:

  • Safewhere Admin: change status using the Mass update status functionality.
  • REST API: admin/api/rest/v2/users/.batchStatus (PUT).

PasswordUpdated event

This event is published when the password of a user is changed. Actions that trigger this event are:

  • Identify Admin: Set passwords in the User list and the My password tab.
  • Identify Runtime: Force change password at the next login.
  • IdentifyMe: Change password or reset password

Updating passwords in the following places causes two events to be published: a PasswordUpdated event and an Updated event:

  • Safewhere Admin: change passwords from the User list, the Edit user page, and the My profile page.
  • Identify Admin: change passwords from Edit user page.
  • REST API: admin/api/rest/v2/users (PUT), /api/rest/v2/users/.batch (PUT), /api/rest/v2/users/{userId} (PATCH).

Anatomy of an event

An event has the following properties:

  • MessageId: a unique id of each message.
  • CorrelationId: All events that are published from the same web request on Identify side have the same correlation id. This is also the requestId that you can find in all log entries on the Identify side during that request. As a result, you can use this id to correlate all relevant events as well as to look up the Identify requests that caused the events.
  • MessageType: type of supported event. This may be handy when you want to write dedicated handlers for each type of events.
  • AppId: This AppId tells you from which part of Identify that published an event. Valid values are “Runtime”, “Admin”, and “Service”.
  • MessageJson: content of the message.

How to use the domain event feature

To enable the publishing of domain events, follow these steps:

  1. Go to Integrations in Identify and click the + button to create a new message queue. After that enable the Publish domain events option.

message queue

In which:

  • Display name: a friendly name of your queue. This is used by REST API as the primary key for identifying a message queue object.
  • Queue name: name of a queue or a topic in either Azure Service Bus or RabbitMQ. Upon saving a message queue object, Identify will try to access that queue. If it does not exist, Identify will also attempt to create that queue automatically. Note that attempting to create the queue may fail if Identify does not have write access. A good convention is to use your Identify tenant name for this field.
  • URI: connection string to message queue.
  • Active: specifies whether a queue is active. If a queue is active, Identify will publish events to it.
  • Number of times to retry sending a message: This setting is preserved for future development.
  • Audit messages: This setting is preserved for future development.
  • Publish domain events: specifies whether domain events are allowed to be published to the queue.
  • Publish logs: specifies whether log messages are allowed to be published to the queue.
  1. Enable the Message bus log target from the Logging settings

Message bus log target

Note: Hot reloading settings are not applied for Runtime. Restarting IIS is required.

How to use domain events with Azure Service Bus

This section will show the necessary steps to publish events to the Azure Service Bus:

  1. Create a new service bus in Azure if you have not done that: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dotnet-get-started-with-queues. Note that you need to use the standard plan or higher, as Identify needs to use Topics.

  2. Copy the connection string of your newly created service bus and paste it to the Uri setting of Identify’s message queue.

  3. Create a new topic and enter its name to the Queue name setting found in the previous section. Alternatively, if the connection string you entered to Identify gives write access for Identify, Identify can create a topic for you. Azure topic

Note: Azure Service bus does not have support for transaction. In other words, MSDTC must be disabled on tenant when using Azure Service Bus Queue. For more info, please refer to https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-amqp-dotnet#unsupported-features-restrictions-and-behavioral-differences.

How to use domain events with RabbitMQ

Note that for RabbitMQ, when you want to access it remotely, the built-in guest/guest account will not work. You need to create a new user account.

  • Open command prompt, navigate to C:\Program Files\RabbitMQ Server\rabbitmq_server-3.6.6\sbin (assuming that you are using RabbitMQ version 3.6.6).

  • Run the following commands to create a user. In the example below, a user named "testuser" was created and password was set to "testpassword" (Note: please use a stronger password for your production environment).

rabbitmqctl add_user testuser testpassword
rabbitmqctl set_user_tags testuser administrator
rabbitmqctl set_permissions -p / testuser ".*" ".*" ".*"
  • Open your Identify instance and create a message queue in Integration, fill in a URI connection string in amqp://testuser:testpassword@servername/ format:
    • "testuser" and "testpassword" are credentials of the user that you created previously.
    • servername is the name of server where you installed Rabbit queue. You can also use IP address for this.

Sample client code for consuming published events

Sample client code can be found at https://github.com/Safewhere/Safewhere-Identify-samples/tree/master/EventFramework.

Q&A

  • Question: What happens when I configure more than one active message queues?
  • Answer: Identify will publish events to all active message queues. However, we do not recommend having multiple active queues since publishing events is time-consuming.