WP User Sentry Docs
WP User Sentry is a very simple WordPress Plugin which I built to cover a small gap in most security plugins.
Last Reviewed 25th May 2020
Installation
Stable version
The latest stable release version of WP User Sentry is via WordPress.org Repository to install from within WordPress.
Open wp-admin/ and navigate to Plugins -> Add new plugin, searching WP User Sentry and click install and activate.
Development version
The latest version is available via Github, simply clone the master branch.
Note this is not recommended and, for any production site, you should use the Stable version from WordPress.org.
Basic Usage
Once installed and activated WP User Sentry is working out of the box, it will send an email to a user whenever they login.
Who is sent the email, the subject and contents of the email can be configured within the setting section.
In addition, it provides a table on each user’s profile showing the sessions currently active.
To access WP User Sentry settings visit wp-admin -> Settings -> WP User Sentry
Note: Settings will not save until you hit the Save button
GEO API Provider
By default WP User Sentry does not geo locate users, you can however select a GEO API Provider, at which point WP User Sentry will subsequently lookup IPs to that provider. This allows the use of the country and flag options within emails.
By default, WP User Sentry provides two providers:
- Ip-api.com
- WooCommerce MaxMind
Ip-api.com is a free service. When selected, each time a user logs in, the IP is sent (via a HTTP request) to ip-api.com and it returns Country and Country Code. ip-api.com is a third party service, governed by its own data privacy policy and service level agreement.
WooCommerce MaxMind is available if WooCommerce is active and a license key is present in its settings. Setting up this integration is free. For full details to see https://docs.woocommerce.com/document/maxmind-geolocation-integration/
Which option you choose will be dependent on your current setup and existing plugins:
| Pros | Cons | |
| None | Fast/No Privacy issues | No Geolocation data |
| ip-api.com | More Accurate and available in all circumstances | Slower/dependent on 3rd party service |
| WooCommerce GeoAPI | Local DB so faster, single integration | Requires WooCommerce and a MaxMind License (which are free) |
Additional providers may well be added in future, if you have a suggested provider please do open a Github issue with the suggestion.
Determining who should receive emails
By default, whenever any user logs in they are sent an email. This might not be the behaviour you wish, for example you might not want this to occur for customers logging in. So you can choose to filter which roles by unticking the checkboxes. If all checkboxes are unticked then no user will be sent a login email. This can be used as a way to temporary disable sending while you are setting up, for example. The test email will still send, regardless of which roles are selected.
To reduce the number of emails sent you can select the option to not send emails if a session already exists for that user with the same IP and user agent (for example, if you have logged in with incognito mode). Note, if you log in with a different browser, for example, Chrome and Firefox, then it will send a new email.
Customising the Email
By default WP User Sentry sends out a rather bland and boring message – you can configure this in the WP User Sentry settings.
Both the subject and email contents are editable. You can add dynamic content by using {user_login} note the curly braces are required. The dynamic options available are:
- {user_login} – The users login
- {display_name} – The option selected that is shown on public pages for the user
- {homeurl} – The home url of your site normally example.com
- {time} – Current date and time
- {ip} – IP address of the person logging in
- {browser} – The browser of the user logging in
- {os} – The operating system of the user logging in
- {profile_url} – Direct link to the users profile, with anchor to the sessions table
- {country} – If GeoAPI provider is selected, then the country, as determined by the IP
- {flag} – If GeoAPI provider is selected, the emoji flag for the country.
The browser, OS and country information should be treated as a best guess and are determined by the user agent and IP of the logging in user. Useragent, in particular, is very easy to change.
Testing the email
When you have edited your message you can click the “test email” button which will send an email to yourself (the email address in your profile) using your current details for IP and Browser.
Developer Options
The following filters are available to build integrations into WP User Sentry
wp_user_sentry_notify – Filters a boolean to determine if the email should be sent, the User ID is passed as an argument.
wp_user_sentry_email_message – Filters the email contents, filters prior to dynamic content is rendered so your filtered message can use dynamic elements if required. Note: It passes only the message as off v1.1. A future version will change this to include the user object.
wp_user_sentry_login_email – filters the email array, which includes who is being sent to, subject, message and headers.