SAML And Two-Factor

Security Assertion Markup Language (SAML) authenticates internal users against your identity provider (IdP). Authenticator two-factor is a separate, password-side control for local and Lightweight Directory Access Protocol (LDAP) users. This page covers both, and the local administrator account you keep working through all of it.

SAML here means internal organization single sign-on (SSO). Customer Portal SSO is a different provider record with different sessions and its own administration.

Before you start

• You need SystemAdmin and a satisfied step-up. See Admin Settings and step-up.
• Sign in with an active local SystemAdmin account and confirm it works. Keep that session open while you configure federation.
• Get the IdP issuer, the SSO uniform resource locator (URL), the metadata URL if you use one, the public signing certificate, and the subject or claim contract from the identity owner. Never ask for, and never enter, an IdP private key.

Choose the default sign-in presentation

1. Open Directory and identity integrations.
2. Under Default source for internal users, choose Local password first, Active Directory / LDAP first, or Organization SSO first.
3. Select Save sign-in source.

This changes which sign-in option the login page leads with. It does not enable a provider, remove the local sign-in path, or grant anything. Choosing Organization SSO first takes effect only once SAML is enabled and readiness validation has passed — the product states "The login page shows organization SSO first only after SAML is enabled and readiness validation has passed." Until then the setting is saved but the login page does not lead with SSO.

Save the SAML configuration

Set the configuration up first and enable it for validation. Enforcement comes later.

1. Select Add integration and open the SAML workspace. It is a set of tabs — Setup, Service provider, Identity provider, Access mapping, and Validation — and each tab saves on its own. Work through them in turn and save each before moving on; there is no single save for the whole configuration.
2. In Setup, choose a provider preset: Generic SAML 2.0, Microsoft Entra ID, Okta, PingOne, or Google Workspace. A preset fills in provider conventions. It is not certification of that provider. This tab also carries the Enable SAML configuration for validation and Enforce SAML for ordinary internal sign-in toggles — enable the first now and leave enforcement off until you have validated (see Validate before enforcing).
3. In Service provider, set the SP entity ID / identifier and the Assertion consumer service path. The product displays the ACS / reply URL and SP metadata URL for you to give your identity owner. In the same tab, read Assertion signature policy, which states Signed assertions required. There is nothing to set: the product always rejects unsigned or invalidly signed assertions, and the workspace says so — "This policy cannot be disabled from the admin workspace." Save service-provider values.
4. In Identity provider, enter the IdP entity ID / issuer, the IdP SSO URL, the IdP metadata URL if used, and the IdP signing certificate (public certificate only — never a private key). Then choose the Stable subject mapping: Persistent NameID, Email claim, or Custom claim. Pick the one your IdP guarantees is stable per person, and review the Subject claim, Display-name claim, Email claim, and Groups claim names. Save.
5. Review the saved state on each tab.

Saving does not prove a sign-on works. The SP metadata the product publishes is setup information only.

Validate before enforcing

1. Open Validation.
2. Confirm an active local SystemAdmin path exists.
3. Select Validate readiness.
4. Read every result: saved metadata and certificate, required signed assertions, subject mapping, endpoint configuration, and local fallback.
5. Fix the saved configuration and validate again. Only validate again after you know what you changed.
6. Sign in with a test identity through the full flow.
7. Only after readiness passes, the test sign-in works, and local sign-in still works, enable Enforce SAML for ordinary internal sign-in.

At each sign-on BareBones Ticketing checks the signature, issuer, audience, destination, recipient, bearer confirmation, time bounds, subject stability, certificate, and replay. A wrong audience, a replayed assertion, a malformed assertion, a username collision, or an inactive user is refused. Do not weaken a check to make a test pass.

Map incoming groups to local groups

An assertion never grants product authority by itself. A mapping turns one incoming group value into membership of one local group, and the local group carries whatever access you gave it.

1. Open Access mapping.
2. Choose the normalized incoming group value and one active local group.
3. Check what that local group already carries — department access, project access, and any SystemAdmin grant. Everyone the mapping matches gets all of it.
4. Enable Apply this mapping on SAML sign-in.
5. Save once.

Mapping into a group that holds SystemAdmin

Two guardrails apply when the target local group carries a SystemAdmin grant.

1. Confirm the incoming group is the IdP's administrator group and that the identity owner controls its membership.
2. Enable Allow this SAML group mapping to provide SystemAdmin access through the selected BareBones group.
3. Save once.

Saving is refused if that control is off. The message tells you the group carries SystemAdmin and asks you to confirm this is a privileged admin mapping.

Saving is also refused if no usable local break-glass SystemAdmin path exists. A SAML-sourced administrator does not satisfy that requirement.

The second guardrail is re-checked at every sign-on. If no local break-glass path is available at that moment, the privileged mapping is not applied and the person does not receive SystemAdmin from it. Ordinary, non-privileged mappings are unaffected.

How mapped membership is removed

Removal happens at the next successful SAML sign-on. If the incoming value is gone, BareBones Ticketing removes the membership it previously derived from that mapping — and only that one. A membership you added by hand is left alone.

The product does not poll your IdP and does not end a session already in progress. Membership derived from a mapping persists until that person next signs on.

Urgent revocation does not wait for a sign-on — do it in the product. Removing someone's group in your IdP does not immediately remove the access they derived from it here. If they hold a session, they keep it; if they do not sign on again, the mapped membership is never removed. When you need access gone now — a departure, a compromised account, a mistaken grant — do both of these in the product, in order, and do not rely on the IdP change alone:

1. Remove the SystemAdmin grant (or the specific access) directly, in System Admin Access or the group that carries it, so the authority is gone at the source.
2. Disable the user account in Users and groups. A disabled account fails the active-user check on the next request, which closes off whatever the first step did not.

Doing both, in that order, revokes at the product boundary regardless of IdP state or an in-progress session. The IdP change is still worth making — it stops the mapping being re-applied at a future sign-on — but it is the slow half, not the urgent one.

Applying mapped membership can be refused on the licensed worker limit, and that refusal fails the sign-on. See Limits and scope.

Enable authenticator two-factor

Time-based one-time password (TOTP) enrollment applies to active local and LDAP users. It does not apply to SAML users, and it is not step-up — completing a two-factor challenge at sign-in does not unlock gated admin surfaces.

1. At the integration landing page, open Non-SAML sign-in security.
2. Enable Make authenticator-app enrollment available for local and Active Directory / LDAP sign-in.
3. Select Save sign-in security.

Each user then enrols themselves:

1. Open Sign-In Security in preferences.
2. Select Start authenticator setup.
3. Scan or type the setup material into an authenticator app, privately.
4. Enter a current code and select Confirm authenticator.

At later sign-ins the user enters their password first, then a six-digit code.

A code cannot be used twice. Once the product accepts a code it will not accept that one again, even while it is still on screen in the app and still inside its 30-second step. This catches people out at enrollment: the code used for Confirm authenticator is consumed by the enrollment itself, so signing in immediately afterwards needs the next code. Wait for the app to roll over rather than retyping the one you just used.

A reused code is refused in exactly the same words as a wrong code, so the screen will not tell you which happened. If a code that looks right is rejected, wait for the next one before assuming the enrollment is broken. Clearing and re-enrolling an authenticator also clears this history, so a replacement enrollment starts clean.

Enrollment is optional. There are no backup codes, no SMS or email one-time passwords, no push, no hardware tokens, and no WebAuthn. A lost authenticator is cleared by an administrator — see Users and groups.

Keep the local fallback working

When SAML is enforced and the IdP is unavailable, the local SystemAdmin account signs in through the displayed Local break-glass password sign-in option.

That account signs in normally and still completes step-up. It bypasses nothing. See Admin Settings and step-up for the last-local-admin rule.

Before each of these, confirm a local SystemAdmin path will remain:

• enabling enforcement;
• saving a privileged group mapping;
• disabling a user or group that supplies the local path;
• removing a SystemAdmin grant.

Fix the federation problem and revalidate before going back to ordinary SSO sign-in.

If it does not work

• Readiness validation fails. Fix the saved cause and validate again. Leave enforcement off. Signature checking is not yours to switch off — do not go looking for a way — and do not disable audience checks.
• The test sign-in fails but readiness passed. Use local sign-in, keep enforcement off, and reconcile the configuration with the identity owner.
• The sign-on is refused on a username collision. The incoming subject matches an existing local or LDAP identity. Nothing is merged. Decide which record is authoritative before changing either.
• A person signed in but has no access. The mapping did not match, or the local group it targets carries no access. Check the normalized incoming value and the local group.
• A privileged mapping would become the only administrator path. Stop. SAML administrator reach does not replace the local requirement.
• A user cannot complete the two-factor challenge. Clear the enrollment and have them enrol again. See Users and groups.

Related pages

• Admin Settings and step-up
• Users and groups
• Directory and LDAP
• Limits and scope