Skip to content

Single sign-on (SAML)

SSO lets your members sign in through your own identity provider, so access follows your directory instead of a separate password.

Available on Business. On other plans the page explains the requirement rather than offering the form, and the underlying operations refuse the request too — you can't get around it by crafting one.

What you get

  • Members sign in through your identity provider.
  • Deprovisioning in your directory stops them signing in via SSO.
  • Optionally, members on a verified email domain must use SSO.

Deprovisioning is not offboarding

Removing someone in your IdP prevents future SSO sign-in. It does not remove their AppGantry membership, end their existing sessions, or revoke their personal access tokens, project access tokens, or any other credential they hold. Offboarding is a separate checklist — see Offboarding a member.

Setting it up

1. Give your IdP AppGantry's details

The organization's Single sign-on page shows the service-provider details your identity provider needs, and offers the SP metadata document as a download. Import that into your IdP if it supports metadata import; otherwise copy the values across.

2. Configure the connection

Back in AppGantry, provide:

Field Notes
IdP entity ID Your provider's issuer identifier
IdP sign-on URL Where AppGantry sends authentication requests
IdP signing certificate PEM, used to verify assertions
NameID format Optional
Email attribute Optional; set it if your IdP doesn't use the default
Name attribute Optional

Then choose whether to enable SSO on save. Save it disabled first if you want to verify domains before anyone is affected.

3. Claim and verify your email domains

Verification proves you control a domain, and it is required before you can enforce SSO. Enforcing on an unverified domain would let anyone claim gmail.com and hijack sign-in for its users.

  1. Claim the domain, e.g. example.com.
  2. AppGantry shows a DNS TXT record with a name and a value.
  3. Add that record in your DNS.
  4. Click Verify.

DNS propagation takes anywhere from minutes to a day. If verification fails, confirm the record is visible from outside your network, then try again.

Claim every domain your members actually use — including the acquisition you haven't finished migrating.

4. Test before you enforce

With SSO enabled but not required, members can sign in either way. Have a real member complete an SSO sign-in end to end before you turn on enforcement.

How members actually start an SSO sign-in

This is the part that surprises people: there is no generic "Sign in with SSO" button on the AppGantry sign-in page, and there is nothing for a member to type there that starts SSO. An SSO sign-in begins at a URL that already names your organization.

The member sign-in link on the Single sign-on page is that URL. Get it in front of people in whichever of these fits your company:

  • Send it round when you announce the rollout, and again when you enforce.
  • Tell people to bookmark it. It is the one they should use every time, not the generic sign-in page.
  • Put it on the intranet, next to your other internal tools.
  • Add an AppGantry tile in your IdP. Identity-provider-initiated sign-in works, and a tile in the same launcher as everything else is what most people will actually click.

Somebody who lands on the ordinary sign-in page instead will simply be asked for a password. On a require-SSO organization that will not get them in, and the message will not tell them to go and find the SSO link, so publish the link somewhere durable rather than relying on one email.

5. Require SSO

Require SSO makes members on a verified domain sign in through your identity provider. It's a toggle, so you can turn it off again.

Check your emergency access first

Before enforcing, make sure at least one Admin can still get in if your IdP is unavailable — and know how you'd reach support if not. An org that has locked itself out of its own identity provider is an awkward place to be.

Removing SSO

Remove connection deletes the SSO configuration; members go back to password sign-in. Domains can be removed individually.

If an organization drops off a qualifying plan, any leftover connection and domains become removal-only: you can delete them, but not reconfigure them, until the plan qualifies again.

Operational notes

  • SSO doesn't replace roles. Signing in through your IdP says who someone is; their AppGantry role still says what they can do. See Organizations & members.
  • SSO and MFA are complementary. Enforce MFA at your IdP, or use AppGantry's own MFA policy, or both.
  • Tokens are unaffected. Personal and project access tokens keep working; SSO governs interactive sign-in. Revoke tokens explicitly when someone leaves.
  • Deprovisioning in your IdP is not offboarding. It closes the SSO sign-in route and nothing else — membership, live sessions, and every token the person holds survive it. Work through Offboarding a member.
  • SSO sign-ins are audited. See Audit events.

Troubleshooting

The failure message is deliberately generic

When an SSO sign-in fails, AppGantry shows the same short, non-specific message whatever went wrong — a bad assertion, an unknown organization, an expired request, a signature that didn't verify. That is by design: a detailed error on an unauthenticated page is a probe an attacker can use to learn which organizations and domains exist, and what your IdP is doing.

So don't diagnose from the browser. Diagnose from the two places that can tell you something:

  • Your identity provider's own sign-in logs, which record the request AppGantry sent and what the IdP made of it. This is where an entity-ID or certificate mismatch shows up by name.
  • Your organization's audit feed, which records SSO sign-ins.

If both look clean and members still can't get in, take a reproducible time and the member's email address to support rather than retrying with different settings.

Symptom Likely cause
Domain won't verify TXT record missing, wrong value, or not yet propagated
Sign-in fails at the IdP Entity ID or sign-on URL mismatch
Assertion rejected Wrong or expired signing certificate
Member signs in but has no access They have no membership yet — SSO authenticates, it doesn't grant roles
Wrong email on the account Set the email attribute to match what your IdP sends
Can't enable "Require SSO" No verified domain yet
Members can't find where to start an SSO sign-in There is no SSO button on the generic sign-in page. Give them the member sign-in link or an IdP tile
Every failure looks the same It is meant to. See the note above

See also