Notification Plugin

In order to set up notifications for your open source UE Auth instance, you will need to set up the notifications plugin interface and build a service to interact with UE Auth. Most of the security features of UE Auth that revolve around passwordless logins, password reset, and so on, require this plugin to be configured.

First, you must make the appropriate API requests to configure the notification service using a ROOT authgroup access-token. This only works with ROOT admins. To further ensure this does not change frequently, you must do a GET on /plugins/global to see the current version number and include it in your request. This will increment the version number as well.

POST /plugins/global/notification

{
  "enable": true,
  "url": "https://youremailortextservice.com/path",
  "currentVersion": 1
}

This will add a registered client specifically for notification requests. It will then return the client-id and client-secret of this new service in the request. Make note of these as your service will need them to request tokens or to validate incoming requests.

{
  "type": "PLUGINS",
  "data": {
    "notifications": {
      "enabled": true,
      "notificationServiceUri": "http://www.something.com",
      "notificationServiceClientId": "your-notification-client-id",
      "notificationServiceClientSecret": "your-notification-client-secret",
      "plugins": {
        "version": 2
      }
    }
  }
}

If you wish to disable notifications, you can simply send "enabled": false, to the same endpoint and this registered client will be erased.

Now Auth Group owners can enable their own notifications. If they do so, this will result in a POST http request to the notifications url specified in your enabling request for the following interactions (notification types):

• general - Will work without successful notification depending on config and store the notification for 30 days
• forgotPassword - Plugin Required and must succeed
• verify - Plugin Required and must succeed
• passwordless - Plugin Required and must succeed

To update an authGroup configuration, use the PATCH /group/id endpoint:

[
  {
    "op": "replace",
    "path": "/pluginOptions/notification/enabled",
    "value": true
  },
  {
    "op": "replace",
    "path": "/pluginOptions/notification/ackRequiredOnOptional",
    "value": true
  }
]

Regardless of the auth-group interacting with your service, all requests to the Notification Service will be via client-credential tokens against the ROOT authGroup and clientId. Your service should validate the following:

• The token in general - iss, exp, etc...
• That the audience is equal to the Notification Service ClientId issued
• That the notification iss is equal to the token iss
• That you have not received the ID before
• That the authGroup is Root (may change this later if we implement custom servers)

As a final precaution, your service can request its own token and query the Notifications API to validate incoming requests. It will do this using the client_id and client_secret issued, again for the root authGroup.

NOTE: Notifications only have a 30-day life in service for an audit or query via API.

The body of the POST will be as follows - shown in JSON schema:

{
    "type": "object",
    "description": "Request sent to your notification plugin url as a POST method",
    "properties": {
        "id": {
          "type": "string",
          "description": "unique id of the notification - save to prevent duplicate requests."
        },
        "iss": {
          "type": "string",
          "description": "IdP issuer - make sure it matches the token"
        },
        "type": {
          "type": "string",
          "description": "kind of request this is",
          "enum": ["general", "forgotPassword", "verify", "passwordless"]
        },
        "formats": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["email", "sms"]
          } 
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "email address of intended recipient"
        },
        "sms": {
          "type": "string",
          "description": "phone number of intended recipient"
        },
        "authGroup": {
          "type": "object",
          "description": "UE Auth Group to which the recipient is registered",
          "properties": {
            "id":{
              "type": "string"
            },
            "name":{
              "type": "string"
            },
          }   
        },
        "screenUrl": {
          "type": "string",
          "description": "Url of the screen required to process type of notification sent - includes encoded tokens and other query parameters associated to the request. For password related functionality, this is not sent to the API requester directly."
        },
        "meta": {
          "type": "object",
          "description": "Additional json structured data specific to the request that may be useful."
        } 
    }
}

In future iterations, there will be an option at an authGroup level to override the DEFAULT_NOTIFICATION_PLUGIN_URL with a customUrl to a different service per Group as desired by the owner.

Verified Users

If the notification plugin is not enabled in your open source instance, both globally and within the authGroup, accounts will still not be verified when created. If you've set requireVerified to true, you will need to manually verify these accounts and manually set the flag on the account to true.

If you do have notifications enabled, it is recommended that you use the autoVerify feature.

NOTE: The forgot password notification also sets the verify flag to true.

Designed Limitations of Self Registration

• You can not enable requireVerified on your authGroup if it is public (locked=false) and you do not have notifications enabled
• Users self-registering to a public (locked=false) authGroup which has set requireVerified true and autoVerify false, must perform a password reset immediately after account creation to verify the account. We highly recommend you set autoVerify to true in this case. Alternatively, you could forgo the user initially setting a password by using the generatePassword option, simplifying the workflow.
  • Note: you can assist by initiating the password-reset or verify-account operations on behalf of the user as well