WordWarden Directory Connector

Authrim WordWarden verifies directory passwords against LDAP or Active Directory. Run the connector near the directory; Authrim handles the login interface, account mapping, sessions, and subsequent OIDC or SAML flows.

The directory continues to manage passwords. Authrim does not store directory passwords or password hashes for this login method. During login, Authrim and WordWarden receive the submitted password and pass it to LDAP/AD for verification.

Connection modes

Mode	Connection direction	Directory-side exposure
Direct HTTPS	Authrim sends an HTTPS request to WordWarden.	A reachable HTTPS connector endpoint, usually behind a reverse proxy. LDAP/AD stays private.
Cloudflare Tunnel	Authrim calls a public HTTPS hostname; cloudflared carries the request over its outbound tunnel to WordWarden.	No inbound port on the connector host, but the hostname still exposes a routed connector endpoint.
Authrim Relay	WordWarden opens an outbound WebSocket to Authrim and receives verification requests on that connection.	No public WordWarden endpoint is required. Outbound access to the Authrim host is required.

The connection setting in Authrim is direct for Tunnel and relay for Relay. All three modes require connector authentication; a tunnel does not replace HMAC or the directory’s TLS checks.

sequenceDiagram
    participant Browser
    box transparent Authrim side
        participant Authrim
    end
    box rgba(11,138,138,0.07) Internal / corporate network
        participant WW as WordWarden
        participant LDAP as LDAP / AD
    end
    WW->>Authrim: Open outbound WebSocket (Relay)
    Authrim->>WW: Short-lived authentication challenge
    WW->>Authrim: HMAC challenge response
    Browser->>Authrim: Username and password
    Authrim->>WW: Verification request over authenticated connection
    WW->>LDAP: Search and password bind over TLS
    LDAP-->>WW: Verification result and permitted attributes
    WW-->>Authrim: Result, directory subject, selected attributes
    Authrim-->>Browser: Continue login after account and policy checks

The vertical box edges separate the Authrim side from the internal network hosting WordWarden and LDAP/AD. Scroll horizontally when the diagram is wider than the screen.

A WebSocket starts as an outbound connection but carries messages in both directions after establishment. In Relay mode, Authrim sends work through that existing connection; it does not open a new inbound connection to the directory network. Proxies and firewalls must allow WebSocket upgrades and long-lived connections.

Verifying the connection and returned data

For direct connections, Authrim signs requests to POST /v1/auth/verify-password using AUTHRIM-HMAC-SHA256. WordWarden verifies the signed information, send time, and nonce, a value used to detect request reuse. It also checks that the tenant and connector match. The active setting holds the current key; previous holds the old key during rotation.

For Relay, Authrim sends a short-lived challenge and WordWarden responds using HMAC. Authentication also uses a nonce and send time. The connection checks protocol-version compatibility and the tenant/connector pair in the Relay URL. Request IDs match verification requests to responses. HMAC authenticates the connecting party; TLS protects the communication.

WordWarden returns only attributes present in both Authrim’s requested attribute_names and WordWarden’s permitted ldap.attributes. Group queries can also return membership information. Authrim decides application roles, account mapping, and the final attributes released to applications.

Use an attribute that continues to identify the same directory user over time. The active_directory profile defaults to objectGUID, and openldap defaults to entryUUID. Binary subjects are returned as base64url. A distinguished name (DN) identifies an entry’s location in the directory and can change when that entry moves. Choose subject_attribute explicitly for a generic directory if DN stability is insufficient.

Prepare before installation

Item	Values and checks
Host and network	A host that can reach LDAP/AD. Relay needs outbound WebSocket access to Authrim; direct/Tunnel needs an HTTPS URL reachable from Authrim.
Directory connection	LDAP URL, CA certificate, certificate server name, search account, search base DN, and user filter.
User identification	Stable identity attribute, permitted username formats and domains, and attributes returned to Authrim.
Connector authentication	Matching tenant ID, connector ID, key ID, and secret on Authrim and WordWarden.
Service and monitoring	Persistent state storage, startup method, log destination, and ownership of key and certificate renewal.

First verify LDAP searches and password authentication from the internal network, then verify the connection to Authrim. This separates directory-connectivity problems from Relay or HTTPS problems.

Configure Authrim

In the tenant’s Directory Authentication settings, register a connector and choose its transport. Configure the connector ID, HMAC key ID and secret reference, requested attributes, and timeouts. For direct/Tunnel mode, also configure the WordWarden HTTPS endpoint. For Relay, issue a managed secret and store the one-time value on the WordWarden host.

Authrim’s connector configuration has two identifiers. id is the Authrim settings key, such as campus; connector_id is the WordWarden identifier, such as wwcon_8K4M2Q9F7D3H6P1X. The Relay URL uses the latter. Its tenant and connector must match WordWarden’s configuration.

Enable the directory-password authentication method for the intended tenant. LDAP’s authentication operation is called a bind. After a successful bind, Authrim checks account mapping and login conditions before creating a session. With auto_provision enabled, unmapped users can be recorded for administrator approval. They cannot log in before approval.

Configure WordWarden

Start from the connector repository’s config.example.yaml. The following is an excerpt; the remaining configuration is required before running the connector. Add LDAP lookup settings, username rules, timeouts, and protection settings from that template.

deployment:
  mode: single_tenant
server:
  listen: "127.0.0.1:8080"
  state_dir: "/var/lib/authrim-wordwarden"
tenants:
  - tenant_id: "tenant-a"
    connector_id: "wwcon_8K4M2Q9F7D3H6P1X"
    authrim:
      hmac_keys:
        active:
          kid: "kid_from_authrim"
          secret_ref: "env:AUTHRIM_WORDWARDEN_SECRET_ACTIVE"
      audit_hash_secret_ref: "env:AUTHRIM_WORDWARDEN_AUDIT_HASH_SECRET"
      relay:
        enabled: true
        url: "wss://login.example.com/api/auth/directory-relay/connect/tenant-a/wwcon_8K4M2Q9F7D3H6P1X"
    ldap:
      url: "ldaps://ldap.example.com:636"
      tls:
        verify: true
        server_name: "ldap.example.com"
        ca_file_ref: "file:/etc/authrim-wordwarden/ca/ldap-ca.pem"

Secret references accept env:NAME or file:/absolute/path. Do not put the secret itself in YAML. config validate checks reference syntax without reading secret values. Keep server.state_dir persistent. It contains the ID used to identify the running connector in the monitoring screen. Configuration changes currently require a process restart.

For LDAP, use verified LDAPS or ldap:// with tls.start_tls: true. Runtime TLS verification is required. The service account used for searches needs only the permissions required by the selected lookup mode.

Lookup mode	Behavior
search_then_bind	Service-bind, search for exactly one entry under base_dn, then bind as that user’s DN with the submitted password.
dn_template	Build the DN from a template and bind as that user. Optional service-bind/search settings retrieve attributes.
direct_bind	Bind with the processed username, then service-bind and resolve exactly one entry within the configured search scope.

Username format and domain restrictions, NFKC normalization, case handling, and LDAP filter escaping apply before lookup. Choose these rules to match the directory rather than assuming every deployment uses email addresses.

Verify the connection

Run the following on the connector host with the complete configuration and secret references available.

wordwarden --config /etc/authrim-wordwarden/config.yaml config validate
wordwarden --config /etc/authrim-wordwarden/config.yaml ldap test --tenant tenant-a
wordwarden --config /etc/authrim-wordwarden/config.yaml ldap test --tenant tenant-a --username john --password-stdin
wordwarden --config /etc/authrim-wordwarden/config.yaml doctor

The third command reads the test password from standard input. Check the Relay connection or HTTPS endpoint next, then test the Authrim login flow with a normal account, wrong password, unknown user, and unmapped identity. A plain directory-password session records the authentication methods as amr=["pwd","directory"]. Migration flows can add their own authentication evidence.

After validation, start WordWarden. A managed service or container should use the same configuration and secret references.

wordwarden --config /etc/authrim-wordwarden/config.yaml serve

For Relay, confirm an authenticated connection in the monitoring screen. For direct/Tunnel, verify reachability of the HTTPS URL that Authrim uses before testing login.

Credential verdicts include success, failure, and policy_required. An expired password or a required password change is not a successful login. Directory outages, TLS errors, overload, and HMAC failures are separate from the verdict on whether the password is correct. The current connector does not provide a complete self-service procedure for resolving expired passwords.

Operations and current limits

GET /healthz checks that the process is running; it does not test LDAP connectivity. By default, /healthz/details and /metrics accept access only from the same host.

The connector monitoring screen, Connector Fleet, shows instance ID, version, connection status, and configuration differences. Direct/Tunnel connections send periodic status reports, called heartbeats, using a separate key. Relay registers monitoring information during connection authentication.

Bound concurrency and request timeouts to what LDAP/AD can sustain. WordWarden detects request reuse and repeated abnormal requests. Its request-reuse records are not shared across connector instances, so plan multiple-instance operation explicitly. Accept both old and new keys during rotation, keep clocks synchronized, and correlate Authrim and connector events by request ID without logging passwords.

The connector repository currently describes a public-beta preparation stage. Confirm the actual connector and Authrim release compatibility before rollout; implementation support does not imply that every deployment already has the required features enabled.

Related documentation

• Why this connection keeps passwords in the directory
• PII separation

Implementation references: Authrim packages/ar-auth/src/directory-password-login.ts, directory-password.ts, directory-connector-relay.ts, and packages/ar-management/src/routes/directory-connectors.ts; WordWarden internal/adapters/ldap/client.go, internal/adapters/hmac/verifier.go, internal/adapters/relay/client.go, and docs/configuration.md.