Notify to users about changes made to their authenticators

Introduction

This feature enables the system to send notification emails to users when changes are made to their authenticators. Additionally, it fires an event to a service bus when configured, allowing external services to be notified of the changes as well. This helps to keep users informed and ensures seamless communication between the system and external services.

To enable this feature, navigate to the Security section in the Settings and set Notify users about changes made to their authenticators to Yes.

notify-user-about-changes-authenticators-setting.png

In this version, the supported authenticators are password, TOTP, WebAuthn, and Device Authentication (Trusted Browser). For details on handling changes to other authenticators like OS2faktor, Email, and SMS, please refer to the section Notify users when authenticators (OS2faktor, Email, SMS) change using domain events

Notification via email

Configuration

To enable email notifications for your user accounts in Safewhere Identify, follow these steps:

  1. Configure the email server. You can find it in the following link.

  2. Set up the email claim type in the Settings > System.

    configure-email-server.png

  3. Modify email templates

    We have introduced two new email templates as described below:

    • Notify users when authenticators change: This new email template is designed to notify users when there are changes made to their authenticators, such as adding, removing and changing authenticators from their account.

    • Notify users when password change: This new email template is used to inform users when their passwords have been changed.

    You can modify these email templates in Messaging > Templates.

    notify-user-about-changes-authenticators-setting.png

    You can find explanations for both email templates in the following link.

  4. Indeed, users need email addresses to receive change notifications.

    configure-user-email-notifications.png

Use cases

  1. When a user changes their password or an administrator changes it for them, a notification email will be sent to their mailbox.

    email-notification-changes-password.png

  2. When a user registers a TOTP authenticator, a notification email will be sent to their mailbox.

    email-notification-register-authenticators.png

  3. When a user registers a WebAuthn authenticator, a notification email will be sent to their mailbox.

    email-notification-register-authenticators_webauthn.png

  4. When a user registers a Device Registration (Trusted Browser), a notification email will be sent to their mailbox.

    email-notification-register-authenticators_trusted_browser.png

  5. When a user deregisters a WebAuthn authenticator or an administrator resets it, a notification email will be sent to their mailbox.

    email-notification-deregister-authenticators.png

  6. When a user deregisters a TOTP authenticator or an administrator resets it, a notification email will be sent to their mailbox.

    email-notification-deregister-authenticators_totp.png

  7. When a user deregisters a Device Registration (Trusted Browser) or an administrator resets it, a notification email will be sent to their mailbox.

    email-notification-deregister-authenticators_trusted_browser.png

  8. When an administrator clicks the Reset MFA methods button on Identify Admin to reset all MFA methods for a user, including a TOTP authenticator, a WebAuthn authenticator, and a Device Authentication authenticator (Firefox), notification emails will be sent to their mailbox as follows:

    email-notification-deregister-authenticators_totp_webauthn.png

    email-notification-deregister-authenticators_trusted_browser_reset_mfa.png

  9. When a user logs in using a recovery code of a WebAuthn authenticator, a notification email will be sent to their mailbox.

    email-notification-update-authenticators.png

  10. When a user logs in using a recovery code of TOTP authenticator, a notification email will be sent to their mailbox.

    email-notification-update-authenticators_totp.png

Notification via message bus

Configuration

Configure your Azure message bus or RabbitMQ queue in the Integration.

configure-users-message-queues-notifications.png

You can refer section How to use the domain event feature in this link for more detail.

Supported events

  1. When a user changes their password or an administrator changes it for them, the event below is published.
MessageID: 559c7e7eb84747089b2a784339374dff
CorrelationId: 0f72ed8a-ddd1-41ad-874f-70ff743b8f5a
MessageType: PasswordUpdated
AppId: ADMIN
MessageJson: 
{
    "Id": "25f04788-22d5-4391-8554-de877942b7a9",
    "NewPassword": "********",
    "MessageType": "PasswordUpdated"
}
  1. When a user registers a TOTP authenticator, the event below is published.
MessageID: e482196680a44521b80d2e58b9987645
CorrelationId: 00b1765a-d07b-40f9-aabc-fb59220878d0
MessageType: Created
AppId: ADMIN
MessageJson: 
{
    "DetailMessageType": "AuthenticatorRegistered",
    "Current": {
        "OtpTypeName": "TOTP authenticator",
        "Id": 1003,
        "UserId": "da12ccec-3f21-4ee3-8e50-ccbeeca0e02c",
        "OtpConnectionId": "498e5e39-867a-43ab-af72-d89967cfc1b3",
        "OtpConnectionName": "New One Time Password connector",
        "OtpType": 3,
        "IsEncrypted": false,
        "SecretCode": "********",
        "RecoveryCode": "Kg=="
    },
    "MessageType": "Created"
}
  1. When a user registers a WebAuthn authenticator, the event below is published.
MessageID: e482196680a44521b80d2e58b9987645
CorrelationId: 00b1765a-d07b-40f9-aabc-fb59220878d0
MessageType: Created
AppId: ADMIN
MessageJson: 
{
    "DetailMessageType": "AuthenticatorRegistered",
    "Current": {
        "OtpTypeName": "WebAuthn",
        "Id": 1002,
        "UserId": "da12ccec-3f21-4ee3-8e50-ccbeeca0e02c",
        "OtpConnectionId": "5e998890-dd9f-4ce6-baec-814685876db8",
        "OtpConnectionName": "OTP WebAuthn",
        "OtpType": 5,
        "IsEncrypted": false,
        "SecretCode": "********",
        "RecoveryCode": "Kg=="
    },
    "MessageType": "Created"
}
  1. When a user registers a Device Authentication authenticator, the event below is published.
MessageID: e482196680a44521b80d2e58b9987645
CorrelationId: 00b1765a-d07b-40f9-aabc-fb59220878d0
MessageType: Created
AppId: ADMIN
MessageJson: 
{
    "DetailMessageType": "DeviceRegistered",
    "Current": {
        "TypeName": "SecondFactorMethod",
        "Id": 1,
        "UserSecondFactorCodeId": 1004,
        "UserId": "da12ccec-3f21-4ee3-8e50-ccbeeca0e02c",
        "OtpConnectionId": "85b4dd16-136d-4fbe-b12e-ee14d5907941",
        "OtpConnectionName": "OTP Device",
        "DeviceCookie": "********",
        "DeviceName": "Chrome-WinNT",
        "Type": 1,
        "CreatedDate": "2024-02-21T03:48:42.2377903Z",
        "LastAccessedDate": "2024-02-21T03:48:42.2377903Z"
    },
    "MessageType": "Created"
}
  1. When a user logs in using their recovery code, the event below is published.
**Message**
MessageID: 49c8763d26824e12aa634654400cf168
CorrelationId: b2a544e5-971b-4d92-af0e-e03682764ca3
MessageType: Updated
AppId: RUNTIME
MessageJson: 
{
    "DetailMessageType": "RecoveryCodeUpdated",
    "Current": {
        "OtpTypeName": "Device Authentication",
        "Id": 1004,
        "UserId": "da12ccec-3f21-4ee3-8e50-ccbeeca0e02c",
        "OtpConnectionId": "85b4dd16-136d-4fbe-b12e-ee14d5907941",
        "OtpConnectionName": "OTP Device",
        "OtpType": 6,
        "IsEncrypted": false,
        "SecretCode": "********",
        "RecoveryCode": "Kg=="
    },
    "Previous": {
        "OtpTypeName": "Device Authentication",
        "Id": 1004,
        "UserId": "da12ccec-3f21-4ee3-8e50-ccbeeca0e02c",
        "OtpConnectionId": "85b4dd16-136d-4fbe-b12e-ee14d5907941",
        "OtpConnectionName": "OTP Device",
        "OtpType": 6,
        "IsEncrypted": false,
        "SecretCode": "********",
        "RecoveryCode": "Kg=="
    },
    "MessageType": "Updated"
}
  1. When a user deregisters a TOTP authenticator from their account or an administrator resets a TOTP authenticator of the user, the event below is published.
MessageID: 351cd87cf68445bfaa10038f80cc0a22
CorrelationId: 7ff19097-5cd7-4214-b4b4-48b0fff44a17
MessageType: Deleted
AppId: ADMIN
MessageJson: 
{
    "DetailMessageType": "AuthenticatorDeregistered",
    "Previous": [
        {
            "OtpTypeName": "TOTP authenticator",
            "Id": 2,
            "UserId": "da12ccec-3f21-4ee3-8e50-ccbeeca0e02c",
            "OtpConnectionId": "498e5e39-867a-43ab-af72-d89967cfc1b3",
            "OtpConnectionName": "New One Time Password connector",
            "OtpType": 3,
            "IsEncrypted": false,
            "SecretCode": "********",
            "RecoveryCode": "Kg=="
        }
    ],
    "MessageType": "Deleted"
}
  1. When a user deregisters a WebAuthn authenticator from their account or an administrator resets a WebAuthn authenticator of the user, the event below is published.
MessageID: 351cd87cf68445bfaa10038f80cc0a22
CorrelationId: 7ff19097-5cd7-4214-b4b4-48b0fff44a17
MessageType: Deleted
AppId: ADMIN
MessageJson: 
{
    "DetailMessageType": "AuthenticatorDeregistered",
    "Previous": [
        {
            "OtpTypeName": "WebAuthn",
            "Id": 1002,
            "UserId": "da12ccec-3f21-4ee3-8e50-ccbeeca0e02c",
            "OtpConnectionId": "5e998890-dd9f-4ce6-baec-814685876db8",
            "OtpConnectionName": "OTP WebAuthn",
            "OtpType": 5,
            "IsEncrypted": false,
            "SecretCode": "********",
            "RecoveryCode": "Kg=="
        }
    ],
    "MessageType": "Deleted"
}
  1. When a user deregisters a Device Authentication authenticator from their account or an administrator resets a Device Authentication authenticator of the user, the event below is published.
MessageID: 351cd87cf68445bfaa10038f80cc0a22
CorrelationId: 7ff19097-5cd7-4214-b4b4-48b0fff44a17
MessageType: Deleted
AppId: ADMIN
MessageJson: 
{
    "DetailMessageType": "DeviceDeregistered",
    "Previous": [
        {
            "TypeName": "SecondFactorMethod",
            "Id": 1,
            "UserSecondFactorCodeId": 1004,
            "UserId": "da12ccec-3f21-4ee3-8e50-ccbeeca0e02c",
            "OtpConnectionId": "85b4dd16-136d-4fbe-b12e-ee14d5907941",
            "OtpConnectionName": "OTP Device",
            "DeviceCookie": "********",
            "DeviceName": "Chrome-WinNT",
            "Type": 1,
            "CreatedDate": "2024-02-21T03:48:42.237",
            "LastAccessedDate": "2024-02-21T03:48:42.237"
        }
    ],
    "MessageType": "Deleted"
}
  1. When an administrator clicks the Reset MFA methods button on Identify Admin to reset all MFA methods for a user, including a TOTP authenticator, a WebAuthn authenticator, and a Device Authentication authenticator (Chrome, Firefox), the following events are published:
**Message**
MessageID: e8053a62f3724f259b2855ad7ac4d4fa
CorrelationId: d682486c-bfc6-452b-a72f-8862ea83c252
MessageType: Deleted
AppId: ADMIN
MessageJson: 
{
    "DetailMessageType": "DeviceDeregistered",
    "Previous": [
        {
            "TypeName": "SecondFactorMethod",
            "Id": 13,
            "UserSecondFactorCodeId": 1013,
            "UserId": "af9b83e2-6c5c-408f-8126-fa0b7f7fc54f",
            "OtpConnectionId": "85b4dd16-136d-4fbe-b12e-ee14d5907941",
            "OtpConnectionName": "OTP Device",
            "DeviceCookie": "********",
            "DeviceName": "Chrome-WinNT",
            "Type": 1,
            "CreatedDate": "2024-02-21T06:33:19.973",
            "LastAccessedDate": "2024-02-21T06:33:19.973"
        },
        {
            "TypeName": "SecondFactorMethod",
            "Id": 14,
            "UserSecondFactorCodeId": 1013,
            "UserId": "af9b83e2-6c5c-408f-8126-fa0b7f7fc54f",
            "OtpConnectionId": "85b4dd16-136d-4fbe-b12e-ee14d5907941",
            "OtpConnectionName": "OTP Device",
            "DeviceCookie": "********",
            "DeviceName": "Firefox-WinNT",
            "Type": 1,
            "CreatedDate": "2024-02-21T06:33:54.563",
            "LastAccessedDate": "2024-02-21T06:33:54.563"
        }
    ],
    "MessageType": "Deleted"
}

**Message**
MessageID: 06b0547c079c41e08c343efbd57b8233
CorrelationId: d682486c-bfc6-452b-a72f-8862ea83c252
MessageType: Deleted
AppId: ADMIN
MessageJson: 
{
    "DetailMessageType": "AuthenticatorDeregistered",
    "Previous": [
        {
            "OtpTypeName": "TOTP authenticator",
            "Id": 1011,
            "UserId": "af9b83e2-6c5c-408f-8126-fa0b7f7fc54f",
            "OtpConnectionId": "498e5e39-867a-43ab-af72-d89967cfc1b3",
            "OtpConnectionName": "New One Time Password connector",
            "OtpType": 3,
            "IsEncrypted": false,
            "SecretCode": "********",
            "RecoveryCode": "Kg=="
        },
        {
            "OtpTypeName": "WebAuthn",
            "Id": 1012,
            "UserId": "af9b83e2-6c5c-408f-8126-fa0b7f7fc54f",
            "OtpConnectionId": "5e998890-dd9f-4ce6-baec-814685876db8",
            "OtpConnectionName": "OTP WebAuthn",
            "OtpType": 5,
            "IsEncrypted": false,
            "SecretCode": "********",
            "RecoveryCode": "Kg=="
        },
        {
            "OtpTypeName": "Device Authentication",
            "Id": 1013,
            "UserId": "af9b83e2-6c5c-408f-8126-fa0b7f7fc54f",
            "OtpConnectionId": "85b4dd16-136d-4fbe-b12e-ee14d5907941",
            "OtpConnectionName": "OTP Device",
            "OtpType": 6,
            "IsEncrypted": false,
            "SecretCode": "********",
            "RecoveryCode": "Kg=="
        }
    ],
    "MessageType": "Deleted"
}

Notify users when authenticators (OS2faktor, Email, SMS) change using domain events

In Safewhere Identify, user email addresses, phone numbers, and OS2faktor codes are not stored using fixed attributes or claim types. Instead, they are stored in claim types that can be customized by customers. This makes it challenging to implement notifications for changes to them right away.

The suggested approach involves leveraging domain events within your system to detect changes in user claims associated with authenticators such as OS2faktor, Email, and SMS. These domain events are triggered when a new user is created or an existing one is updated.

For demonstration purposes, the following user claims are utilized:

  • uri:os2faktor:deviceid for the OS2faktor authenticator
  • uri:telephonenumber for the SMS authenticator
  • urn:email for the Email authenticator

After a domain event is triggered upon creating a new user, the message JSON object appears as follows:

**Message**
MessageID: 68f63f8710a64d69b9b2508f33cc1f12
CorrelationId: 41217325-52ad-43e8-8faf-370712fe900b
MessageType: Created
AppId: ADMIN
MessageJson:
{
    "Current": {
        "schemas": [
            "urn:scim:schemas:core:1.0",
            "urn:scim:schemas:extension:enterprise:1.0",
            "urn:scim:schemas:extension:safewhere:identify:1.0"
        ],
        "userName": "NewUser",
        "displayName": "NewUser",
        "active": true,
        "password": "",
        "userContexts": [],
        "urn:scim:schemas:extension:enterprise:1.0": {
            "organization": "Root"
        },
        "urn:scim:schemas:extension:safewhere:identify:1.0": {
            "forceResetPasswordAfterFirstTimeLogin": false,
            "claims": [
                {
                    "type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
                    "value": "NewUser"
                },
                {
                    "type": "uri:os2faktor:deviceid",
                    "value": "459-322-313-220"
                },
                {
                    "type": "uri:telephonenumber",
                    "value": "0342123454"
                },
                {
                    "type": "urn:email",
                    "value": "newuser@globeteam.com"
                }
            ]
        },
        "actAsServiceUris": [],
        "passwordHash": "",
        "passwordSalt": "",
        "numberOfRegisteredMFADevices": 0,
        "id": "7b279a6a-c556-4a77-bbd2-b96a96fff2d6",
        "externalId": "NewUser",
        "meta": {
            "created": "0001-01-01T00:00:00Z",
            "lastModified": "0001-01-01T00:00:00Z",
            "location": "/admin/api/rest/v2/users/7b279a6a-c556-4a77-bbd2-b96a96fff2d6"
        },
        "schema": "urn:scim:schemas:core:2.0:User"
    },
    "MessageType": "Created"
}

In the provided message JSON object above, the Current section represents the user's JSON object after a successful creation.

After a domain event is triggered upon updating an existing user, the message JSON object appears as follows:

**Message**
MessageID: d5264def34984f21a7c78050dc8b294e
CorrelationId: 4f679200-16fa-49b8-a66f-65ad15f9b115
MessageType: Updated
AppId: ADMIN
MessageJson: {
    "Current": {
        "schemas": [
            "urn:scim:schemas:core:1.0",
            "urn:scim:schemas:extension:enterprise:1.0",
            "urn:scim:schemas:extension:safewhere:identify:1.0"
        ],
        "userName": "NewUser",
        "displayName": "NewUser",
        "active": true,
        "password": "",
        "userContexts": [],
        "urn:scim:schemas:extension:enterprise:1.0": {
            "organization": "Root"
        },
        "urn:scim:schemas:extension:safewhere:identify:1.0": {
            "forceResetPasswordAfterFirstTimeLogin": false,
            "claims": [
                {
                    "type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
                    "value": "NewUser"
                },
                {
                    "type": "uri:os2faktor:deviceid",
                    "value": "459-322-313-999"
                },
                {
                    "type": "uri:telephonenumber",
                    "value": "0342123999"
                },
                {
                    "type": "urn:email",
                    "value": "newuser999@globeteam.com"
                }
            ]
        },
        "actAsServiceUris": [],
        "passwordHash": "",
        "passwordSalt": "",
        "numberOfRegisteredMFADevices": 0,
        "id": "7b279a6a-c556-4a77-bbd2-b96a96fff2d6",
        "externalId": "NewUser",
        "meta": {
            "created": "0001-01-01T00:00:00Z",
            "lastModified": "0001-01-01T00:00:00Z",
            "location": "/admin/api/rest/v2/users/7b279a6a-c556-4a77-bbd2-b96a96fff2d6"
        },
        "schema": "urn:scim:schemas:core:2.0:User"
    },
    "Previous": {
        "schemas": [
            "urn:scim:schemas:core:1.0",
            "urn:scim:schemas:extension:enterprise:1.0",
            "urn:scim:schemas:extension:safewhere:identify:1.0"
        ],
        "userName": "NewUser",
        "displayName": "NewUser",
        "active": true,
        "password": "",
        "userContexts": [],
        "urn:scim:schemas:extension:enterprise:1.0": {
            "organization": "Root"
        },
        "urn:scim:schemas:extension:safewhere:identify:1.0": {
            "forceResetPasswordAfterFirstTimeLogin": false,
            "claims": [
                {
                    "type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
                    "value": "NewUser"
                },
                {
                    "type": "uri:os2faktor:deviceid",
                    "value": "459-322-313-220"
                },
                {
                    "type": "uri:telephonenumber",
                    "value": "0342123454"
                },
                {
                    "type": "urn:email",
                    "value": "newuser@globeteam.com"
                }
            ]
        },
        "actAsServiceUris": [],
        "passwordHash": "",
        "passwordSalt": "",
        "numberOfRegisteredMFADevices": 0,
        "id": "7b279a6a-c556-4a77-bbd2-b96a96fff2d6",
        "externalId": "NewUser",
        "meta": {
            "created": "0001-01-01T00:00:00Z",
            "lastModified": "0001-01-01T00:00:00Z",
            "location": "/admin/api/rest/v2/users/7b279a6a-c556-4a77-bbd2-b96a96fff2d6"
        },
        "schema": "urn:scim:schemas:core:2.0:User"
    },
    "MessageType": "Updated"
}

In the provided message JSON object above, the Current section represents the user's JSON object after a successful update, while the Previous section represents the user's JSON object before the update.

By subscribing to these events and handling relevant messages, you can set up a feature to send notification emails to inform affected users of the changes. For instance, if the "Updated" event indicates that the user's email has been changed, you can send an email to both addresses to notify the user about the update.