README
¶
password
Email and password sign-in, with a policy you can tighten without redeploying.
The core engine already knows how to hash and check a password. This plugin wraps that as a named, toggleable auth method and adds the rules around it: a minimum length, an optional special-character requirement, and a domain allowlist that stops anyone outside your company from registering.
Use it when
- You want the familiar credential flow as a primary sign-in method
- You're gating signup to company email domains for an internal tool
- You need password rules an admin can change from the dashboard, without a redeploy
Skip it when
- You're building passwordless.
magiclinkandpasskeycover that, and shipping both undercuts the security argument for either - Your only clients are machines. Use
apikey - Users arrive through an identity provider you don't control.
ssoorsocialown the credential in that case
Wiring
authsome.WithPlugin(password.New(password.Config{
MinLength: 10,
RequireSpecial: true,
}))
Restrict signup to your own domains:
authsome.WithPlugin(password.New(password.Config{
AllowedDomains: []string{"example.com", "example.org"},
}))
Config
| Field | Type | Default | What it does |
|---|---|---|---|
MinLength |
int |
engine default | Minimum characters. 0 defers to the engine policy |
RequireSpecial |
bool |
false |
Require at least one special character |
AllowedDomains |
[]string |
empty | Email domains permitted to sign up. Empty allows all |
Settings
| Key | Default |
|---|---|
password.min_length |
8 |
password.require_special |
false |
password.allowed_domains |
empty |
All three are enforceable and scoped global or per-app, so a stricter app can override the global floor.
Endpoints
This plugin does not add routes. Sign-up and sign-in stay on the core endpoints, /v1/signup
and /v1/signin.
Lifecycle hooks
| Hook | What happens |
|---|---|
BeforeSignUp |
Rejects the registration if the password or the email domain fails policy |
It also registers a StrategyProvider so password shows up as a selectable auth method, and
an AuthMethodContributor so the dashboard knows the user has one.
Related
Account lockout, rate limits, password history and expiry live in the engine config rather
than here. See authsome.PasswordConfig and authsome.LockoutConfig.
Documentation
¶
Overview ¶
contract.go: Wires the password plugin into the forge-dashboard contract surface. The actual manifest + handlers live in the subpackage at plugins/password/contract/; this file exposes the integration via plugin.ContractContributor so authsome's RegisterContractContributor loop picks the plugin up automatically.
Package password provides a built-in password authentication plugin for AuthSome.
The password plugin wraps the core email/password authentication flow as a named plugin with configurable validation rules. It hooks into BeforeSignUp to enforce password policy, and provides a StrategyProvider for password-based authentication.
Index ¶
- Variables
- type Config
- type Plugin
- func (p *Plugin) DeclareSettings(m *settings.Manager) error
- func (p *Plugin) ListUserAuthMethods(ctx context.Context, userID id.UserID) ([]*plugin.AuthMethod, error)
- func (p *Plugin) Name() string
- func (p *Plugin) OnBeforeSignUp(_ context.Context, req *account.SignUpRequest) 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
- func (p *Plugin) RegisterRoutes(_ forge.Router) error
- func (p *Plugin) Strategy() strategy.Strategy
Constants ¶
This section is empty.
Variables ¶
var ( // SettingMinLength controls the minimum password length. SettingMinLength = settings.Define("password.min_length", 12, settings.WithDisplayName("Minimum Password Length"), settings.WithDescription("Minimum number of characters required for passwords"), settings.WithCategory("Password Policy"), settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp), settings.WithEnforceable(), settings.WithInputType(formconfig.FieldNumber), settings.WithUIValidation(formconfig.Validation{Required: true, Min: intPtr(4), Max: intPtr(128)}), settings.WithHelpText("Minimum number of characters required. Default: 8"), settings.WithOrder(10), ) // SettingRequireSpecial controls whether special characters are required. SettingRequireSpecial = settings.Define("password.require_special", false, settings.WithDisplayName("Require Special Character"), settings.WithDescription("Require at least one special character in passwords"), settings.WithCategory("Password Policy"), settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp), settings.WithEnforceable(), settings.WithHelpText("When enabled, passwords must contain at least one special character"), settings.WithOrder(20), ) // SettingAllowedDomains restricts signup to specific email domains. SettingAllowedDomains = settings.Define("password.allowed_domains", "", settings.WithDisplayName("Allowed Email Domains"), settings.WithDescription("Comma-separated list of allowed email domains for signup (empty = all allowed)"), settings.WithCategory("Password Policy"), settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp), settings.WithInputType(formconfig.FieldTextarea), settings.WithPlaceholder("example.com, mycompany.org"), settings.WithHelpText("Leave empty to allow all domains. Separate multiple domains with commas."), settings.WithOrder(30), ) )
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// MinLength overrides the engine password policy minimum length.
// Set to 0 to use the engine default.
MinLength int
// RequireSpecial requires at least one special character.
RequireSpecial bool
// AllowedDomains restricts signup to specific email domains.
// Empty means all domains are allowed.
AllowedDomains []string
}
Config configures the password plugin.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the password authentication plugin.
func (*Plugin) DeclareSettings ¶
DeclareSettings implements plugin.SettingsProvider.
func (*Plugin) ListUserAuthMethods ¶
func (p *Plugin) ListUserAuthMethods(ctx context.Context, userID id.UserID) ([]*plugin.AuthMethod, error)
ListUserAuthMethods implements plugin.AuthMethodContributor. It reports a "password" method if the user has a non-empty password hash.
func (*Plugin) OnBeforeSignUp ¶
OnBeforeSignUp validates the signup request against the password plugin's rules.
func (*Plugin) RegisterContract ¶
func (p *Plugin) RegisterContract( d *dispatcher.Dispatcher, reg contract.Registry, wreg contract.WardenRegistry, engine plugin.Engine, ) error
RegisterContract implements plugin.ContractContributor. It type-asserts the engine handle to *authsome.Engine (the only concrete type that implements plugin.Engine in practice) and delegates to the subpackage's Register function. Failed assertion returns a descriptive error rather than panicking — keeps non-authsome embedders cleanly opted out.
func (*Plugin) RegisterRoutes ¶
RegisterRoutes is a no-op for the password plugin since the core signup/signin routes are already registered by the API handler.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package contract registers the password plugin's forge-dashboard contract surface: three intents (password.settings, password.policy, password.settingsUpdate) backed by the settings.Manager, plus a standalone /auth/password page that extends the auth contributor's /settings page with a password-policy panel.
|
Package contract registers the password plugin's forge-dashboard contract surface: three intents (password.settings, password.policy, password.settingsUpdate) backed by the settings.Manager, plus a standalone /auth/password page that extends the auth contributor's /settings page with a password-policy panel. |