Configuring Single Sign-On (SSO)

Backfire supports per-company OIDC SSO with Microsoft Entra ID, Okta, and Google Workspace. Users at your company sign in by typing their work email on the Backfire login page; if the domain is registered with us they’re redirected to your IdP. Passwords continue to work as a recovery path.

This guide is for company administrators. Two steps require Tsukaeru.net support: verifying your email domain (DNS TXT) and final go-live. Plan for a 1–2 business day turnaround on each.

Prerequisites

• A Backfire account with the admin role on your company.
• Administrative access to one of:
  • Microsoft Entra ID (formerly Azure AD)
  • Okta
  • Google Workspace
• The ability to publish a DNS TXT record on each email domain you want to federate.

Overview — the five-step handshake

1. Add your email domain to Backfire (AddVerifiedDomain).
2. Publish the DNS TXT record we give you.
3. Tsukaeru.net support verifies the domain (VerifyDomain).
4. Register Backfire as a relying party in your IdP and capture the client_id and client_secret.
5. Submit the IdP config to Backfire (ConfigureOidc). After this, users at the federated domain are redirected to your IdP on sign-in.

Step 1 — Add your email domain

In the Backfire admin console (or via AddVerifiedDomain), submit the FQDN of the email domain your users sign in with (e.g. example.co.jp). One company can register multiple domains; each is verified independently. Domains are case-insensitive — Example.co.jp and example.co.jp are treated as the same.

If the FQDN is already claimed by a different Backfire customer, the request is rejected. Email Tsukaeru.net support with proof of ownership if you believe a domain was claimed incorrectly.

Step 2 — Publish the DNS TXT record

Backfire returns a verification token. Publish it as a TXT record on the domain:

_backfire-verify.example.co.jp   TXT   "backfire-verify=<token-from-step-1>"

DNS changes take anywhere from minutes to several hours to propagate depending on your registrar’s TTL.

Step 3 — Tsukaeru.net verifies the domain

Email your Tsukaeru.net support contact once the TXT record is live, including the company name and the FQDN. An operator runs VerifyDomain, which queries the TXT and stamps the row as verified. You’ll receive confirmation once the domain is live in our system.

Until a domain is verified, it does not route SSO traffic. Users at a pending domain continue to sign in with their password.

Step 4 — Register Backfire as a relying party in your IdP

The exact UI varies by IdP. The redirect URI to register is the same in every case:

https://<your-backfire-host>/oauth/oidc/callback

Your Backfire host is the domain you (or your reseller) use to access Backfire — for example, files.example.co.jp or backfire.tsukaeru.net.

Required ID-token claims

Backfire requires the following claims on the IdP-issued ID token. All three IdPs send them by default, but if you’ve customised the token contents make sure they’re present:

Claim	Why Backfire needs it
email	Routes the user to the correct company via the verified_domains table
email_verified	We refuse to JIT-provision a user from an unverified email — the IdP must have proven the user owns the address
name	Used as the Backfire display name on first sign-in
sub	The IdP’s stable identifier for the user — Backfire maps (issuer, subject) → user

Microsoft Entra ID

1. Microsoft Entra admin centre → Identity → Applications → App registrations → New registration.
2. Name: Backfire (or whatever you prefer).
3. Supported account types: “Accounts in this organisational directory only” — single-tenant.
4. Redirect URI: Web → https://<your-backfire-host>/oauth/oidc/callback.
5. After creation, on the app’s overview page note the Application (client) ID — this is your client_id. The Directory (tenant) ID determines your issuer_url, which will be https://login.microsoftonline.com/<tenant-id>/v2.0.
6. Certificates & secrets → Client secrets → New client secret. Pick a 24-month expiry. Copy the Value — you can only see it once.
7. Token configuration → Add optional claim → ID and tick email if it isn’t already listed by default.
8. API permissions → Add a permission → Microsoft Graph → Delegated permissions: add openid, profile, email. Grant admin consent.

Okta

1. Okta admin → Applications → Applications → Create App Integration → OIDC – OpenID Connect → Web Application.
2. App integration name: Backfire.
3. Sign-in redirect URIs: https://<your-backfire-host>/oauth/oidc/callback.
4. Assignments: restrict to the groups of users who should be able to sign in to Backfire.
5. After creation, on the General tab copy the Client ID and Client secret.
6. Your issuer URL is https://<your-okta-domain> (e.g. https://example.okta.com) — the leading scheme + host with no trailing slash.

Google Workspace

1. Google Cloud Console → APIs & Services → OAuth consent screen. Configure for Internal if you only want users in your Google Workspace, or External for limited testing.
2. APIs & Services → Credentials → Create credentials → OAuth client ID → Web application.
3. Authorised redirect URIs: https://<your-backfire-host>/oauth/oidc/callback.
4. After creation copy the Client ID and Client secret.
5. Your issuer URL is https://accounts.google.com.

Step 5 — Submit the IdP config to Backfire

Provide the following to Tsukaeru.net support, or input them directly via ConfigureOidc (admin console UI coming):

• Provider: entra / okta / google
• Issuer URL (from the IdP-specific step above)
• Client ID (from the IdP-specific step above)
• Client secret — Tsukaeru.net stores this in our secret manager (OpenBao). The secret value never enters our database and never appears in logs. If you submit via support, prefer an encrypted channel; if you input via the admin console, the request is over TLS and the secret is sent directly to the secret store.
• Default role (optional) — the role JIT-provisioned users receive on first sign-in. Defaults to member. Change to viewer if you want new users to land as read-only and be promoted by an admin.

Once the config is saved, the next user typing a @your-domain email on the Backfire login page is redirected to your IdP. There is no caching delay — the first login attempt after Step 5 exercises the live flow.

What changes for your users

• The Backfire login page asks for an email first. After entering alice@example.co.jp, Alice is redirected to your IdP rather than seeing the password field.
• First-time SSO users are auto-provisioned with the default role you chose in Step 5. No admin pre-invite is required.
• Users keep their Backfire password and can still sign in with it as a fallback (e.g. on a device that can’t do browser SSO). To remove password as a fallback for a user, contact Tsukaeru.net support.
• Users who change their email at your IdP keep their Backfire account — the IdP’s stable subject is what we bind to, not the email address.

Removing SSO / unverifying a domain

If you offboard an IdP or stop using a domain, contact Tsukaeru.net support to unverify the domain. Unverifying:

• Stops new SSO redirects — users at that domain fall back to password.
• Immediately revokes all live SSO sessions for your company (active access tokens expire within 15 minutes; refresh tokens are revoked in the same operation).
• Leaves password sessions untouched.

To remove an IdP configuration entirely without unverifying the domain, use DeleteOidcConfig.

Troubleshooting

Symptom	Likely cause
User types email, sees password field anyway	The domain is not yet verified, or the user’s email is on a different (unverified) domain.
User redirected to IdP, login succeeds, but bounces back to Backfire with an error	client_secret is wrong or expired. Rotate the secret in the IdP and resubmit.
Configured for a different tenant error after IdP login	The issuer_url in Backfire’s config doesn’t match the iss claim in your IdP’s tokens. Re-check the issuer URL — Entra in particular has multiple forms; use https://login.microsoftonline.com/<tenant-id>/v2.0.
Sign-in works for some users, others see “email not verified”	The IdP is sending email_verified: false for those accounts. Fix this at the IdP (typically requires the user to confirm their primary email).

For anything not in this table, email Tsukaeru.net support with the time of the failed sign-in attempt — our gateway logs are correlated by minute.