Skip to content
Security > Authentication

SAML

SAML authentication is a separate plugin, not bundled with 3forge Enterprise: request and install it, then point 3forge Enterprise's SSO extension point at it along with your identity provider's SAML details. This is a browser-redirect login, not a username-and-password check, so it works for the Web only; see Authentication -> Two plugin mechanisms, not one if you need REST or WebSocket clients authenticated too.

Configuring the connection

Set sso.plugin.class and the identity-provider details, then restart:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Load the SAML plugin as the SSO plugin
sso.plugin.class=com.f1.ami.plugins.amisaml.AmiWebSamlPluginImpl

# The identity provider's sign-in URL, and how 3forge Enterprise identifies itself to it
saml.identity.provider.url=https://your-idp.example.com/sso
saml.entityid=your-3forge-application

# Where the identity provider sends the response. The path is where 3forge Enterprise expects it
saml.service.provider.url=https://your-ami-host:33333/saml-suffix

# The SAML attribute (or NameID) that becomes the user name. Defaults to uid
saml.username.field=NameID

saml.service.provider.url must include a path (.../saml-suffix above, not a bare host): 3forge Enterprise expects the identity provider's response at that path, and the plugin cannot initialize without one. saml.username.field names the SAML attribute (or NameID) that becomes the username, and defaults to uid.

After restarting, open the Web's address in a browser, and the login redirects to the identity provider. A successful login redirects back into the Web already signed in; a rejected one is turned back by the identity provider before 3forge Enterprise sees anything to accept or reject.

Mapping SAML attributes to roles

Set a role property to the SAML attribute name that carries it, then a values property to say which values mean "yes":

1
2
3
4
saml.ami.isadmin.field=groups
saml.ami.isadmin.values=ami-admins
saml.ami.isdev.field=groups
saml.ami.isdev.values=ami-devs

Each values property is a comma-delimited list, so a value that itself contains a comma, such as a full distinguished name, cannot be matched. Use an attribute whose values are plain names.

To give users layouts by group, name the attribute that carries the groups, list the groups 3forge Enterprise recognizes, and define each group's layouts:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# The attribute holding the user's groups
saml.ami.group.field=groups

# The groups 3forge Enterprise recognizes
saml.ami.groups=analysts,traders

# The default layout and the layouts each group grants
saml.group.analysts.ami.default.layout=analyst.ami
saml.group.analysts.ami.layouts=analyst.ami,shared.ami
saml.group.traders.ami.default.layout=trader.ami
saml.group.traders.ami.layouts=trader.ami

A user's groups are the values of the group attribute that also appear in saml.ami.groups. A user in one of those groups gets that group's default layout, and the group's layouts are combined into the list the user can open, in no particular order. A user in several of those groups gets the combined layouts of all of them, but which group supplies the default layout is not defined, so define a default layout for one group only if a user can belong to several.

Clock skew, message lifetime, and diagnostics

  • saml.identity.provider.clock.skew.ms: how much difference to tolerate between 3forge Enterprise's clock and the identity provider's when checking a SAML response's timestamps. It defaults to 2000. Raise it if logins fail with a message-rejected error and the 2 clocks aren't tightly synchronized.
  • saml.identity.provider.lifetime.ms: how long a SAML response is accepted as fresh after it's issued. It defaults to 60000000, about 16.7 hours.
  • saml.debug: logs the encoded and decoded response from the identity provider and the attributes taken from it, for diagnosing a rejected login. It defaults to true, so set it to false once the connection works.

Other properties

  • saml.nameID.format: the NameID format requested from the identity provider: email, unspecified, persistent, or transient. It defaults to transient, and any other value also gives transient.
  • saml.identity.provider.cert.file: the path to the identity provider's X.509 certificate. It is read at startup, and the plugin cannot initialize if the file is missing or not a valid certificate.
  • saml.identity.provider.nocert.rsa.key.strength: the RSA key size, in bits, of the temporary key pair the plugin generates when saml.identity.provider.cert.file is not set. It defaults to 2048, and a smaller value logs a security warning.
  • saml.relay.state: an optional RelayState value. It has no default.

What this does not support

  • No REST or WebSocket login. SAML is a browser-redirect flow; a REST or WebSocket client has no way to be redirected the way a browser is, so this plugin authenticates the Web only.
  • No property drives single logout (SLO) back out to the identity provider: logging out of 3forge Enterprise does not end the SAML session at the identity provider.
  • No metadata auto-discovery: the identity provider's URL, entity ID, and certificate are each set as separate properties; there's no property that points at a metadata XML document to read them from.
  • No values containing commas: The admin, dev, and group value lists split on commas, so a value such as a full distinguished name cannot be matched.