Sign-in and accounts

Decide who can create an account and how people sign in. Every sign-in method of Antimatter works without a licence, single sign-on and directories included.

Who can create an account

Right after installing, check System Console › Authentication › Signup. With the defaults, anyone with an invitation link to a community can create an account, but nobody can sign up without one.

Community admins also control who joins their community, with invitation links and their own allowed domains: see the Running a community guide.

From the command line: amctl user create (add --system-admin or --guest), amctl user invite, amctl user deactivate, amctl roles system-admin <user> to make someone a system administrator, and amctl roles member <user> to undo it.

Email and password

In System Console › Authentication › Email:

In System Console › Authentication › Password:

A length of 12 or more does more for security than character rules. To reset a password for someone: System Console › User Management › Users, or amctl user change-password <user> --password <new>.

Multi-factor authentication

Multi-factor authentication (MFA) adds a code from an authenticator app to the password. It applies to accounts that sign in with email or AD/LDAP; with single sign-on, use your identity provider's MFA. In System Console › Authentication › MFA:

• Enable Multi-factor Authentication (ServiceSettings.EnableMultifactorAuthentication, off): people can turn MFA on in their security settings.
• Enforce Multi-factor Authentication (ServiceSettings.EnforceMultifactorAuthentication, off): everyone must set it up, at sign-up or at their next sign-in.

If someone loses their device: amctl user resetmfa <user>, or reset it from their page in System Console › User Management › Users.

Single sign-on

Antimatter can sign people in through your identity provider. On first sign-in it creates their account (if account creation is allowed) from the name, email and username the provider sends.

OpenID Connect, GitLab, Google and Entra ID

Go to System Console › Authentication › OpenID Connect, and choose under Select service provider: GitLab, Google Apps, Entra ID (Office 365) or OpenID Connect (Other) for any other provider (Keycloak, Authentik, Zitadel, Okta, Auth0…).

1. In your provider, create an application (a "client") of the web type, with this redirect URI, for your site URL:

   Provider	Redirect URI
   OpenID Connect (Other)	https://chat.example.com/signup/openid/complete
   GitLab	https://chat.example.com/signup/gitlab/complete
   Google	https://chat.example.com/signup/google/complete
   Entra ID	https://chat.example.com/signup/office365/complete

2. In Antimatter, fill in the Discovery Endpoint (the provider's /.well-known/openid-configuration URL; for GitLab, the GitLab Site URL instead), the Client ID and the Client Secret. For other providers, also the Button Name and Button Color of the sign-in button.
3. Use Preferred Username (GitLab and other providers) takes the Antimatter username from the provider's preferred_username claim.
4. Save, sign out, and try the new button on the sign-in page.

The settings are stored in OpenIdSettings, GitLabSettings, GoogleSettings or Office365Settings (for example AM_OPENIDSETTINGS_ENABLE, AM_OPENIDSETTINGS_DISCOVERYENDPOINT, AM_OPENIDSETTINGS_ID, AM_OPENIDSETTINGS_SECRET). Additional Scopes (AM_OPENIDSETTINGS_ADDITIONALSCOPES) asks the provider for more OAuth scopes, space-separated, on top of the default ones. The older OAuth 2.0 page only appears for servers that still have an OAuth 2.0 GitLab, Google or Entra ID configuration.

For plain OpenID Connect (not GitLab, Google or Entra ID), signing in also syncs user attributes you've linked to a claim: Antimatter reads the ID token and the userinfo response (userinfo wins when both carry a claim), tries the claim name as a single top-level key first, then as dot-separated nesting (for example address.country) if nothing matched. A claim the response doesn't include clears the attribute it's linked to, since the provider is treated as the source of truth for what it syncs. This is on by default; turn it off with AM_FEATUREFLAGS_OPENIDATTRIBUTESYNC=false.

SAML 2.0

In System Console › Authentication › SAML 2.0, turn on Enable Login With SAML 2.0 (SamlSettings.Enable) and fill in what your identity provider gives you: the Identity Provider Metadata URL, or the SAML SSO URL, the Identity Provider Issuer URL and the Identity Provider Public Certificate. On the identity provider's side:

• Service Provider Login URL (assertion consumer service): https://chat.example.com/login/sso/saml;
• Antimatter's metadata, for providers that import it: https://chat.example.com/api/v4/saml/metadata.

Map the attributes your provider sends: at least the Email Attribute and Username Attribute, and optionally the ID, first and last name, nickname, position, language, guest and admin attributes. Verify Signature and Enable Encryption are on by default (encryption needs a service provider key and certificate; only RSA keys are supported); Sign Request is off. The signature algorithm defaults to RSAwithSHA256.

AD/LDAP

In System Console › Authentication › AD/LDAP, a step-by-step page connects Antimatter to Active Directory or another LDAP server: the server and port (LdapSettings.LdapServer, LdapSettings.LdapPort, 389 by default), the connection security (none, TLS or STARTTLS), the base DN and a bind account (BaseDN, BindUsername, BindPassword), filters for users, guests, admins and groups, and the attributes for email, username, ID, names and picture. People then sign in with their directory login.

A synchronisation job runs every 60 minutes (LdapSettings.SyncIntervalMinutes) to update names and deactivate people removed from the directory; run it now with amctl ldap sync. LDAP groups can be linked to communities and channels in System Console › User Management › Groups. SAML accounts can also be kept in sync with AD/LDAP (Enable Synchronizing SAML Accounts With AD/LDAP).

Custom profile attributes mapped to an AD/LDAP or a SAML attribute, in System Console › System Attributes, sync the same way from both: a text attribute's value is copied as the directory or assertion sends it, up to 64 characters (a longer value clears the attribute rather than being cut short); a select or multiselect attribute's value is matched to an existing option whatever its case, keeping that option's own spelling, and a new option is created when none matches. Options nobody holds any more are pruned, and a synced attribute's option list can only be changed by the sync that owns it, not by hand in the System Console.

Moving existing accounts

To switch existing email accounts to single sign-on, amctl user migrate-auth email saml users.json (or ldap) moves them in bulk. A user can also change their own sign-in method in their security settings when Allow Authentication Transfer (ServiceSettings.ExperimentalEnableAuthenticationTransfer, in System Console › Experimental › Features) is on.

Guest accounts

Guests are people from outside your organisation who only see the channels they are invited to. Turn them on in System Console › Authentication › Guest Access:

Once on, community admins invite guests to specific channels. Administrators can turn a member into a guest with amctl user demote, and a guest into a member with amctl user promote.

Sessions

How long people stay signed in is set in System Console › Environment › Session Lengths:

To sign everyone out at once, use Revoke All Sessions in System Console › User Management › Users. To sign one person out, open their page there.