SAML single sign-on

Connect your organization to a SAML 2.0 identity provider so members sign in with your company credentials instead of Google or GitHub. Once a domain is attached, anyone with an email address at that domain is routed to your IdP, and you can optionally require it.

Setting this up takes four steps, in this order. They all live on your organization's Settings page, under Configure SSO — expand that section to see them:

1. Create a SAML app in your IdP using the two service-provider values Ampbase shows you.
2. Prove you own the email domain with a DNS record.
3. Paste your IdP's details back into Ampbase and attach the domain.
4. Run the connection test.

You need the Owner role to see or change any of this.

What you'll need

• A SAML 2.0 identity provider you administer. This page walks through Okta, Microsoft Entra ID and Google Workspace click-by-click; any other SAML 2.0 IdP works the same way and is covered in Other identity providers.
• The ability to publish a DNS TXT record on the email domain you want to attach.
• An email domain your organization actually owns. Shared consumer providers (gmail.com, outlook.com, disposable-mail services, and similar) are refused — a claim on one of those would bind unrelated people to your organization, so passing the DNS challenge is necessary but not sufficient.

Step 1 — Your service-provider details

Go to Settings for your organization and select Configure SSO to expand the section. The first card shows two values, both specific to your organization:

Copy them straight from the page rather than assembling them by hand — the org id in the middle is yours alone, and an IdP configured against the wrong one will fail with a mismatched-audience error that is hard to read.

Ampbase only accepts logins it started. An assertion your IdP sends unprompted — the "app tile" or IdP-initiated flow — is rejected. Leave that mode off, and see App tiles and portals for what to do with the tile your IdP creates anyway.

Step 2 — Verify your email domain

A domain has to be proven yours before it can route logins. In the second card, enter the domain (for example acme-corp.com) and select Get DNS record. Ampbase returns a challenge:

Publish it with your DNS provider, then select Check DNS record. If it reports the record was not found, give propagation a few more minutes and try again — nothing is consumed by a failed check.

A verified domain belongs to one organization. The first organization to verify a domain claims it, and a second organization attempting the same domain is told it is already claimed rather than silently sharing it. Verifying a domain does not attach it to SSO yet; that happens in step 3.

Step 3 — Connect your identity provider

Create the SAML application in your IdP first, then come back and paste four things into the third card: the IdP entity ID, the IdP SSO URL, the IdP signing certificate, and the attribute names carrying email and display name.

If your IdP gives you a metadata XML file, expand Paste IdP metadata XML to fill these fields and paste it — the entity ID, SSO URL and certificate are extracted in your browser and the XML itself is never sent to Ampbase. Check the filled values before saving.

Okta

In the Okta admin console, go to Applications → Applications → Create App Integration, choose SAML 2.0, and give the app a name.

On the Configure SAML screen:

Still on that screen, add two Attribute Statements:

These two names are what the Okta preset in Ampbase's attribute-mapping control expects, so adding them here means you can pick the preset and change nothing. Okta signs both the response and the assertion with RSA-SHA256 by default; leave those defaults alone.

Finish the wizard, then open the app's Sign On tab and select View SAML setup instructions (or the metadata link). That page gives you the three values Ampbase needs:

• Identity Provider Issuer → paste into IdP Entity ID (Issuer)
• Identity Provider Single Sign-On URL → paste into IdP SSO URL
• X.509 Certificate → paste into IdP signing certificate (PEM)

Finally, on the Assignments tab, assign the app to the people or groups who should be able to sign in. A user who is not assigned cannot authenticate, no matter what Ampbase is configured with.

Microsoft Entra ID

In the Entra admin center, go to Enterprise applications → New application → Create your own application, choose Integrate any other application you don't find in the gallery, and create it. Then open Single sign-on and pick SAML.

Under Basic SAML Configuration:

The Entra step people get wrong is the email. Entra's default Name ID is an opaque, per-application identifier — a string like ttPsKJ3i…=, not an address — so Ampbase reads the email from a claim instead. Under Attributes & Claims, confirm these two claims exist (they are in Entra's default claim set):

Those are exactly the values in Ampbase's Microsoft Entra ID attribute preset, so selecting that preset fills them for you. Do not map the email to Name ID — an Entra configuration with no email claim mapped will authenticate the user and then fail to place them in your organization.

Under SAML Certificates, download Certificate (Base64) and open it in a text editor; that is the PEM block to paste into Ampbase. The same panel lists:

• Microsoft Entra Identifier → paste into IdP Entity ID (Issuer)
• Login URL → paste into IdP SSO URL

Then assign users under Users and groups. On the Entra free tier, assignment is per-user; group assignment needs a paid tier. Encrypted assertions also need a paid tier — Ampbase does not support encrypted assertions today, so signed-only is the correct configuration either way.

Google Workspace

In the Google Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app and give the app a name.

The next screen, Google Identity Provider details, is the one carrying everything Ampbase needs — capture it before moving on:

• SSO URL → paste into IdP SSO URL
• Entity ID → paste into IdP Entity ID (Issuer)
• Certificate → download it; the downloaded file is the PEM block to paste into IdP signing certificate (PEM)

Continue to Service provider details:

Continue to Attribute mapping. Unlike Okta and Entra, Google does not fix the attribute names — you choose them here, which means you choose whether they match Ampbase's preset. Map:

Name it email exactly and the Google Workspace preset in Ampbase's attribute-mapping control is correct with no edits. Name it something else and you must type that name into Ampbase instead — the mapping is what Ampbase reads the identity from, so a mismatch here authenticates the user and then fails to place them.

A display-name mapping is optional and a missing one never blocks a login. Google's basic directory attributes are First name and Last name separately rather than one full name, so unless your directory carries a full-name attribute you can map, leave Ampbase's name field empty — selecting the Google Workspace preset already leaves it empty for you. If you do add an app attribute called name, Ampbase picks it up without being told; otherwise members show by email address.

Finally, set User access to ON for everyone, or for the organizational units that should be able to sign in — a custom SAML app is off for everyone until you do, which is the most common reason a freshly-created Google app appears to do nothing.

One Google-specific limit worth knowing: a Google Workspace SAML app supports a single callback mode, and Ampbase needs the SP-initiated one. That is what the Start URL above sets up, and it is the only mode Ampbase accepts anyway.

Other identity providers

Any SAML 2.0 identity provider works. It needs to:

• accept an SP-initiated authentication request and post the response to your ACS URL,
• sign the assertion (signed responses are also fine; unsigned is refused),
• send the user's email address as an attribute, not only as the Name ID, and
• use your SP Entity ID as the audience.

Configure it with the SP Entity ID and ACS URL from step 1, then paste its entity ID, SSO URL and signing certificate back into Ampbase and set the attribute mapping to whatever attribute names it emits. Pick Custom in the vendor control and type them in.

The rest of the form

Below the IdP fields:

• Attribute mapping — pick your vendor from the dropdown, or Custom and type the names. The email mapping is required; the display-name mapping is optional and a missing display name never blocks a login.
• Member provisioning — turn on Create a member automatically the first time someone from a verified domain signs in if you want new joiners admitted without an invitation, and choose the role they get (Viewer or Admin). With it off, a user who authenticates but has never been invited is refused. Auto-provisioning only ever admits addresses inside a domain you verified.
• Domains that use this IdP — tick the verified domains that should route to this IdP. Attaching an unverified domain is refused by the server, not merely hidden in the form.

Select Enable SAML SSO. Members can sign in through your IdP as soon as this is saved.

Step 4 — Test the connection

Select Test connection in the fourth card. It checks everything that can be verified without a person standing at your IdP:

Each row reports pass or fail with the specific reason, and a failure never stops the other checks running — you see every problem at once rather than one per attempt. The test reads your saved configuration, so save step 3 before running it.

What it does not do is drive a browser through your IdP; no server-side test can. The real confirmation is signing in yourself, which is worth doing before you tell anyone else the change is live.

Signing in

Members go to the sign-in page and choose Sign in with SSO, then enter their work email. Ampbase looks up the domain, and if it belongs to an organization with SSO configured, sends the browser straight to that IdP.

The lookup answers on the domain, never on the address — so it tells a stranger only what your public DNS already tells them, and never whether a particular person has an account.

Requiring SSO

By default SSO is an additional way in: members can still use Google or GitHub. Ticking Require SSO closes those for everyone whose email is at an attached domain.

Turning it on needs a passing connection test. That gate is on the transition, not the state, so an organization that already requires SSO can keep saving other changes without re-testing first — but it cannot be switched on against a configuration nothing has checked.

Two things are worth knowing before you enable it:

Owners keep a way in. An Owner of the organization can still sign in with Google or GitHub even while SSO is required. This is deliberate and it is disclosed rather than hidden: if your IdP breaks or its certificate expires, somebody has to be able to reach the billing page and the SSO settings to fix it. Those sign-ins are recorded in your audit log. Everyone who is not an Owner is held to the IdP.

Rotating your certificate does not switch it off. Changing the IdP entity ID, SSO URL or certificate clears the recorded test pass, because the pass was earned against the old identity provider. Ampbase leaves the requirement on and shows a banner saying no test has passed against the current configuration — silently reopening password login because someone rotated a certificate would be the worse failure. Run the connection test again and the banner clears.

Rotating the signing certificate

Signing certificates expire, and every SAML login fails the day they do. Ampbase warns you on the SSO settings page starting 30 days out, and states the date; there is no other warning surface, so it is worth a calendar entry as well.

To rotate: generate or download the new certificate in your IdP, activate it there, paste the new PEM into Ampbase, save, and run the connection test again. The settings page shows the stored certificate's subject and validity dates under the field, so you can confirm the new one landed.

If the stored certificate cannot be read at all, the page says so rather than guessing at an expiry date — paste it again from your IdP.

Turning SSO off

Disable SAML SSO, at the foot of the SSO section, removes the configuration. (That is not the same as the Danger zone further down the Settings page, which deletes the whole organization.) Members keep their accounts and go back to signing in with Google or GitHub. Verified domains are kept, so re-enabling later does not mean re-proving them.

Disabling is never refused, even when the connection test is failing — the escape hatch cannot depend on the thing that broke.

App tiles and portals

Ampbase rejects any assertion it did not request. That is a deliberate protection, and it means the tile your IdP puts in its user portal will not work if it posts straight to Ampbase:

• Okta — the dashboard tile sends an unsolicited assertion, which is refused. Under the app's General tab, set application visibility to hide the icon from end users, and point people at the Ampbase sign-in page instead.
• Entra ID — set Sign on URL to https://ampbase.io/login/sso as above. The My Apps tile then starts the login at Ampbase, which is the flow that works.
• Google Workspace — set Start URL to https://ampbase.io/login/sso as above, so the app in the Google apps launcher starts the login at Ampbase.

Troubleshooting

Not supported yet

• Encrypted assertions. Assertions must be signed; encryption is not supported. Signed-only is the default on both Okta and Entra.
• IdP-initiated login. Logins must start at Ampbase.
• More than one IdP per organization. One SAML configuration per organization, covering all its attached domains.
• SCIM provisioning. Members are created on first login when auto-provisioning is on; there is no directory sync, and removing a user from your IdP stops them signing in but does not remove the member record.

Related

• How Ampbase works — organizations, channels and where SSO scopes.
• Webhooks — push organization and channel events to your own systems.