radiusmfa

README

go-radius-mfa

A small RADIUS authentication client for Go services, supporting PAP and MS-CHAP-V2 (RFC 2759 / RFC 2548). Typical use: verifying user credentials against NPS, FreeRADIUS, or an MFA gateway as one factor in a login flow.

Built on layeh.com/radius.

Install

go get github.com/rupivbluegreen/go-radius-mfa

Usage

client, err := radiusmfa.New(radiusmfa.Config{
    Addr:          "10.0.0.5:1812",
    Secret:        os.Getenv("RADIUS_SECRET"),
    Protocol:      radiusmfa.MSCHAPv2, // or radiusmfa.PAP
    NASIdentifier: "my-service",
    Timeout:       5 * time.Second, // per attempt
    Retries:       2,               // retransmissions after the first attempt
})
if err != nil {
    log.Fatal(err)
}

err = client.Authenticate(ctx, "jdoe", password,
    radiusmfa.WithCallingStationID("203.0.113.9"))

var reject *radiusmfa.RejectError
switch {
case err == nil:
    // Access-Accept — credentials valid
case errors.As(err, &reject):
    // Access-Reject — bad credentials; reject.ReplyMessage may say why
default:
    // transport error, timeout, or failed MS-CHAP-V2 mutual authentication
}

For MS-CHAP-V2, pass the bare account name (e.g. sAMAccountName) as the username — the domain prefix must not be included, as RFC 2759 excludes it from the challenge hash.

MS-CHAP-V2 details

• The client generates fresh random authenticator and peer challenges per request and sends MS-CHAP-Challenge + the 50-byte MS-CHAP2-Response (Microsoft vendor attributes, vendor ID 311). The password itself never crosses the wire.
• On Access-Accept the server's MS-CHAP2-Success authenticator response is verified (mutual authentication). An accept without a valid proof returns ErrProofFailed.
• The mschapv2 subpackage exposes the RFC 2759 primitives directly (NTPasswordHash, ChallengeHash, GenerateNTResponse, GenerateAuthenticatorResponse), validated against the RFC 2759 §9.2 test vectors.

Security notes

• MS-CHAP-V2 relies on MD4, DES, and SHA-1, which are cryptographically weak by modern standards; a captured challenge/response exchange can be cracked offline. PAP obfuscates the password only with the shared secret (RFC 2865).
• With either protocol, treat the RADIUS link as sensitive: run it over a trusted network segment, an IPsec tunnel, or RadSec, and use a long random shared secret.

License

MIT

Documentation

Overview

Package radiusmfa is a RADIUS authentication client supporting PAP and MS-CHAP-V2, intended for verifying user credentials against a RADIUS server (e.g. NPS, FreeRADIUS, or an MFA gateway) from Go services.

Index

• Variables
• type Client
  • func New(cfg Config) (*Client, error)
  • func (c *Client) Authenticate(ctx context.Context, username, password string, opts ...Option) error
• type Config
• type Option
  • func WithCallingStationID(id string) Option
• type Protocol
• type RejectError
  • func (e *RejectError) Error() string

Variables

var ErrProofFailed = errors.New("radiusmfa: server failed MS-CHAP-V2 mutual authentication")

ErrProofFailed is returned when an Access-Accept carries an MS-CHAP2-Success authenticator response that does not match the locally computed value, meaning the server did not prove knowledge of the user's password.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client authenticates users against a RADIUS server. It is safe for concurrent use.

func New

func New(cfg Config) (*Client, error)

New validates cfg, applies defaults, and returns a Client.

func (*Client) Authenticate

func (c *Client) Authenticate(ctx context.Context, username, password string, opts ...Option) error

Authenticate sends an Access-Request for username and password using the configured protocol. It returns nil on Access-Accept, a *RejectError on Access-Reject, ErrProofFailed if MS-CHAP-V2 mutual authentication fails, and a transport error if no valid response arrives within the configured timeout and retries.

username should be the bare account name (e.g. sAMAccountName) — for MS-CHAP-V2 the domain prefix must not be included, as it is excluded from the challenge hash.

type Config

type Config struct {
	// Addr is the RADIUS server address as host:port, e.g. "10.0.0.5:1812".
	Addr string
	// Secret is the RADIUS shared secret.
	Secret string
	// Protocol selects PAP or MSCHAPv2. Defaults to MSCHAPv2.
	Protocol Protocol
	// NASIdentifier, if non-empty, is sent as the NAS-Identifier attribute.
	NASIdentifier string
	// Timeout is the per-attempt wait for a server response. Defaults to 5s.
	Timeout time.Duration
	// Retries is the number of retransmissions after the first attempt, so
	// the server is tried Retries+1 times in total. Defaults to 2.
	Retries int
}

Config configures a Client. Addr and Secret are required.

type Option

type Option func(*reqOptions)

Option adjusts a single Authenticate call.

func WithCallingStationID

func WithCallingStationID(id string) Option

WithCallingStationID sets the Calling-Station-Id attribute for this request, typically the end user's source IP or phone number.

type Protocol

type Protocol string

Protocol selects the authentication method used for Access-Requests.

const (
	// MSCHAPv2 authenticates with MS-CHAP-Challenge and MS-CHAP2-Response
	// Microsoft vendor attributes (RFC 2548). The password never crosses the
	// wire; on Access-Accept the server's MS-CHAP2-Success proof is verified.
	MSCHAPv2 Protocol = "mschapv2"
	// PAP authenticates with the User-Password attribute, obfuscated with the
	// shared secret as defined by RFC 2865. Only use PAP over a trusted or
	// encrypted transport.
	PAP Protocol = "pap"
)

type RejectError

type RejectError struct {
	// ReplyMessage holds the server's Reply-Message attribute, if any.
	ReplyMessage string
}

RejectError is returned by Authenticate when the server answers with Access-Reject.

func (*RejectError) Error

func (e *RejectError) Error() string