Skip to content
MDView as Markdown

Single Sign-On (SAML)

What is SSO?

Single sign-on lets your team log in to Report URI with the same account they use everywhere else, through your own Identity Provider (IdP). We support SAML 2.0, which works with Okta, Microsoft Entra ID, Google Workspace, JumpCloud, Ping and anything else that speaks the standard.

Once configured, you control who can reach your Report URI data from your IdP. Deprovision someone there and they lose access here, without anyone having to remember to remove them.

SSO is available on the Ultimate and Enterprise plans. It is currently in open beta — the setup page is visible on every account so you can see what is involved, but configuring it requires a plan that includes it.

SSO configuration is per-owner, not per-team

SSO is configured on your own account and applies to every email address on your claimed domains. You do not need to switch into a team to set it up — the page lives at Account → Setup SSO.

Before you start

You will need two things:

  1. Access to DNS for each email domain you want to use, so you can publish a TXT record.
  2. An IdP administrator who can create a SAML application and give you its metadata XML.

You will also want somewhere safe to store a break-glass code — see Enforcing SSO below.

Step 1 — Give your IdP admin the SP details

The top of the Setup SSO page lists everything your IdP administrator needs:

Value What it is
SP Entity ID Our identifier for the SAML application.
ACS URL Where your IdP posts the assertion. This is unique to your account.
NameID format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress — the NameID must be the user's email address.
Required attributes email, firstName and lastName. All three are required for real logins.

The full SP metadata, including our signing certificate, is published as XML at /saml/sp-metadata.xml. Most IdPs can import that URL directly, which is quicker and less error-prone than copying fields by hand.

Step 2 — Claim and verify your email domains

Add each email domain your organisation uses under Claimed domains. Multiple domains are supported and expected — organisations that have acquired other companies almost always have several.

Claiming a domain gives you a verification token. Publish it as a DNS TXT record at the domain's apex, with the value:

report-uri-verification=<your token>

Then click Verify. Once the record resolves, the domain is marked verified.

Verifying a domain does not turn on SSO

Verification only makes SSO available for that domain. Your users can still log in with a password until you complete Step 4. This is deliberate — it lets you test properly before committing.

We re-check the TXT record daily. If it stops resolving, logins keep working for a 7-day grace period and then fail closed. Do not remove the record after verifying.

Step 3 — Upload your IdP metadata and test

Paste the metadata XML from your IdP into the Identity Provider configuration panel. We parse it, validate the signing certificate, and show you the entity ID, SSO endpoint and certificate expiry. We will email you when that certificate is approaching expiry, at 30, 7 and 1 days out.

Now click Test SAML login. This opens a real round-trip to your IdP in a new tab, without changing how anyone logs in.

If it fails, the transaction log records every assertion attempt with the precise reason. That is the fastest way to diagnose a mismatch, and it means you rarely need to contact us.

The test login is more forgiving than a real one

A test login succeeds with just the NameID and warns you about missing attributes. Real logins require email, firstName and lastName, so fix any warnings before enforcing.

Step 4 — Enforcing SSO

Until this step, SSO is an option — users on your claimed domains can log in with either a password or SSO.

Generate a break-glass code first. It is shown once, so save it somewhere safe. It is the only way back into your account if your IdP becomes unavailable.

Then click Disable local password login. From that point, any login attempt from an email on your verified claimed domains is routed to your IdP, and passwords are refused — including through the password-reset flow.

You can re-enable local password login at any time from the same panel.

Just-in-time (JIT) account creation

When someone from a verified claimed domain logs in through your IdP for the first time, we create their Report URI account automatically. There is no invitation step and no pre-provisioning.

What happens depends on whether they already have an account:

  • No existing account — one is created and bound to your IdP.
  • An existing account with that email — it is linked to your IdP rather than duplicated. They keep their existing data.
  • An account already bound to a different organisation's IdP — the login is rejected. An account can only belong to one IdP.

Team membership is not automatic

JIT creates the account, not the access. A newly provisioned user lands on an empty personal account and is shown a message asking them to contact an administrator. Someone with team admin rights still has to add them to the relevant team. Plan for this — it is the most common surprise when rolling SSO out to a large group.

Every login, including the first, re-checks that the asserted email's domain is one of your verified claimed domains. An IdP can assert any identity it likes, so this check is what binds "what your IdP says" to "what your organisation is allowed to speak for". If a domain claim lapses, logins fail closed.

Logging in with SSO

Both directions of the SAML flow are supported, and you do not have to choose — they work side by side.

SP-initiated login starts at Report URI. This is what most people will use:

  • Go to the login page and enter an email address as normal. If that domain has SSO enforced, the login is routed to your IdP instead of asking for a password.
  • Or use the Log in with SSO link on the login page and enter an email address directly.

Either way we sign an authentication request, hand off to your IdP, and your IdP posts the assertion back to your account's ACS URL.

IdP-initiated login starts at your IdP. If you publish Report URI as a tile or bookmark in your IdP's application dashboard, users can click it and land straight in their account without visiting our login page first. Nothing extra needs configuring here — it works as soon as your IdP metadata is uploaded and your domain is verified.

Which one should you use?

SP-initiated is the more robust of the two, because the request originates here and we can tie the response back to it. If you have a choice, prefer it — but IdP-initiated is there when your IdP's app portal is how your users expect to reach things.

Recovering access

If your IdP is unavailable and your users cannot log in, use the break-glass link on the SSO login page with the code you saved in Step 4. That gets you back into the account so you can re-enable local password login.

If you have lost the break-glass code and still have access to your account, generate a new one from the setup page — the old one stops working immediately.

Monitoring

Two places worth checking after a rollout:

  • The transaction log on the setup page records every assertion, successful or not, with a sanitised failure reason.
  • Your Audit Trail records SSO events alongside the rest of your account security events, and can be streamed to a SIEM via webhooks.