Security > Authentication

LDAP¶

LDAP authentication is a separate plugin, not bundled with 3forge Enterprise: request it, then set ami.auth.plugin.class and 6 required LDAP properties to point it at your directory.

Configuring the connection¶

Set the plugin class and the 6 required properties in local.properties, then restart:

ami.auth.plugin.class=com.f1.ami.amildap.AmiAuthenticatorLDAP
ldap.host=ldap.example.com
ldap.port=389
ldap.bind.dn=cn=admin,dc=example,dc=com
ldap.bind.password=your-bind-password
ldap.base.dn=ou=people,dc=example,dc=com
ldap.user.attribute.name=sAMAccountName

All 6 are required; the plugin fails to initialize without them. ldap.user.attribute.name is the LDAP attribute that holds the username a person types to log in: sAMAccountName for Active Directory, uid for most other directory servers.

After restarting, attempt a login with a real directory account, for example over REST:

curl -sk -u <directory-username>:<directory-password> "https://<host>:<port>/3forge_rest/whoami"

Confirmed against a real (test) LDAP directory, 2026-09-18: a correct login returns the username and HTTP 200; a wrong password and an unrecognized username both come back identically, as the literal body BAD_CREDENTIALS with HTTP 401 (3forge Enterprise does not tell a caller which part was wrong). An unreachable directory (wrong host, wrong port, directory down) comes back as INTERNAL_ERROR with HTTP 500; see Authentication -> What a rejected login looks like.

If you were on this property set before 2026¶

Every LDAP property except ldap.port was renamed to match 3forge Enterprise's own naming convention. A deployment still running the old names will fail to start the plugin, because the old property keys are no longer read at all:

Old name	Current name
`ldap.address`	`ldap.host`
`ldap.bindDN`	`ldap.bind.dn`
`ldap.bindPW`	`ldap.bind.password`
`ldap.baseDN`	`ldap.base.dn`
`ldap.userAttributeName`	`ldap.user.attribute.name`
`ldap.maxConnections`	`ldap.max.connections`
`ldap.initialConnections`	`ldap.initial.connections`
`ldap.useSSL`	`ldap.use.ssl`

ldap.attributes is not renamed: it still works, but only as a fallback for ldap.amiscript.attributes (see below), and is deprecated in favor of it.

Connection pooling and SSL¶

These are optional; each has a default if you don't set it.

Property	Default	What it controls
`ldap.max.connections`	`10`	Maximum pooled connections to the directory.
`ldap.initial.connections`	`5`	Connections opened at startup.
`ldap.use.ssl`	`false`	Connect over LDAPS.
`ldap.use.start.tls`	`false`	Upgrade a plain connection to TLS with `StartTLS` instead of connecting over LDAPS directly.
`ldap.ssl.truststore.path`	(none)	Truststore file to validate the directory's certificate, when `ldap.use.ssl` or `ldap.use.start.tls` is on.
`ldap.truststore.pin`	(none)	Password for the truststore file.
`ldap.ssl.truststore.format`	(none)	Truststore format, e.g. `JKS` or `PKCS12`.
`ldap.ssl.validate.hostname`	`true`	Reject a certificate whose hostname doesn't match the directory server.

Mapping directory attributes to roles¶

Two properties map LDAP attributes onto 3forge Enterprise's own user properties (admin flag, dev flag, layout, session limit, and similar):

ldap.ami.attributes: maps onto the built-in keys (ISADMIN, ISDEV, LAYOUTS, MAXSESSIONS, DEFAULT_LAYOUT, and others). Comma-separated AMI_KEY=LDAP_ATTRIBUTE pairs; a bare name means the two are spelled identically. Use the = form whenever a key can't be spelled as a valid LDAP attribute name, e.g. DEFAULT_LAYOUT=DEFAULTLAYOUT.
ldap.amiscript.attributes: same AMI_KEY=LDAP_ATTRIBUTE form, for attributes you want to read from AmiScript as amiscript.variable.<AMI_KEY> rather than as one of the built-in keys.

If you set only the deprecated ldap.attributes, it is read as a fallback for ldap.amiscript.attributes only. It does not populate ISADMIN, ISDEV, or any other built-in key: set ldap.ami.attributes directly for those.

What this does not support¶

No property configures a search filter beyond the single user-attribute lookup (ldap.user.attribute.name). There's no property for a custom LDAP filter string.
No group-membership check independent of the attribute-mapping properties above: a user's roles come only from attributes on their own directory entry, not from walking group membership separately.