README
¶
deviceverify
Spots a sign-in from a device this account has never used, and challenges it.
The pattern is familiar from every bank: sign in from a new laptop and you get a code by email or SMS before you are let through. This plugin implements that as a challenge with a short expiry, and can notify the user either way so an unexpected "new device" email tells them something is wrong.
It runs after sign-in, so credentials have already been checked. The device check is the second gate.
Use it when
- Stolen passwords are the threat and you want something beyond the password without full MFA enrolment
- You want the user notified about new devices even when you are not blocking
- Your users work from a small, stable set of machines, which makes a new one genuinely notable
Skip it when
- Your users are on many devices or clear cookies constantly. The challenge fires so often it becomes noise people click through
- You already require
mfaon every sign-in. Adding this is a second challenge for the same risk - You have no email or SMS delivery to send a challenge over
Wiring
authsome.WithPlugin(deviceverify.New(deviceverify.Config{
NotifyOnNewDevice: true,
ChallengeTTL: 10 * time.Minute,
})),
Config
| Field | Type | Default | What it does |
|---|---|---|---|
NotifyOnNewDevice |
bool |
true |
Send a notification when a new device appears |
ChallengeTTL |
time.Duration |
10m |
How long a verification challenge stays valid |
Settings
| Key | Default |
|---|---|
deviceverify.notify_on_new_device |
true |
deviceverify.challenge_ttl_minutes |
10 |
Lifecycle hooks
| Hook | What happens |
|---|---|
AfterSignIn |
Checks the device against the account's known devices and challenges an unknown one |
Related
Device registration and trust live in the core engine, on /v1/devices. anomaly treats a new
device type as one score among several. notification and email carry the challenge.
Documentation
¶
Overview ¶
contract.go: Wires the deviceverify plugin into the forge-dashboard contract surface via plugin.ContractContributor.
Package deviceverify provides new device detection and challenge-response verification. When a user signs in from an unrecognized device, the plugin can flag it or require verification via email/SMS.
Index ¶
- Variables
- func GenerateToken() (string, error)
- type Config
- type Plugin
- func (p *Plugin) DeclareSettings(m *settings.Manager) error
- func (p *Plugin) Name() string
- func (p *Plugin) OnAfterSignIn(ctx context.Context, u *user.User, s *session.Session) error
- func (p *Plugin) OnInit(_ context.Context, engine plugin.Engine) error
- func (p *Plugin) RegisterContract(d *dispatcher.Dispatcher, reg contract.Registry, wreg contract.WardenRegistry, ...) error
Constants ¶
This section is empty.
Variables ¶
var ( // SettingNotifyOnNewDevice controls whether a notification is sent when // a new device is detected. SettingNotifyOnNewDevice = settings.Define("deviceverify.notify_on_new_device", true, settings.WithDisplayName("Notify on New Device"), settings.WithDescription("Send a notification when a new device is detected"), settings.WithCategory("Device Verification"), settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp), settings.WithHelpText("Send a notification when a new device is detected"), settings.WithOrder(10), ) // SettingChallengeTTLMinutes controls how long a device verification // challenge is valid, in minutes. SettingChallengeTTLMinutes = settings.Define("deviceverify.challenge_ttl_minutes", 10, settings.WithDisplayName("Challenge TTL (minutes)"), settings.WithDescription("How long a device verification challenge is valid, in minutes"), settings.WithCategory("Device Verification"), settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp), settings.WithHelpText("How long a device verification challenge is valid, in minutes"), settings.WithOrder(20), ) )
Functions ¶
func GenerateToken ¶
GenerateToken creates a random hex token for device challenges.
Types ¶
type Config ¶
type Config struct {
// NotifyOnNewDevice sends a notification when a new device is detected
// (default: true).
NotifyOnNewDevice bool
// ChallengeTTL is how long a device verification challenge is valid
// (default: 10m).
ChallengeTTL time.Duration
}
Config configures the device verification plugin.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin detects new devices on sign-in and optionally sends notifications.
func (*Plugin) DeclareSettings ¶
DeclareSettings implements plugin.SettingsProvider. It registers all device-verification-related configurable settings.
func (*Plugin) OnAfterSignIn ¶
OnAfterSignIn checks if the device used for sign-in is new/unrecognized.
func (*Plugin) RegisterContract ¶
func (p *Plugin) RegisterContract( d *dispatcher.Dispatcher, reg contract.Registry, wreg contract.WardenRegistry, engine plugin.Engine, ) error
Source Files
Directories