Choose an authentication setup

Tale supports local email-and-password accounts, organization-specific enterprise sign-in and identity supplied by a trusted reverse proxy. Choose based on where your team’s identities are managed and who owns account provisioning. Sign-in and provisioning are separate decisions: SSO authenticates a person, while invitations, sign-in provisioning or SCIM control membership.

Choose the right integration

Enterprise SSO and trusted headers are both configured per organization. Plan and test changes to identity mapping before moving existing accounts to another mechanism.

Establish the public URL first

Set SITE_URL and any supported base-path configuration to the URL people will actually open. Complete TLS and domain setup before registering redirect URLs with an identity provider.

Keep BETTER_AUTH_SECRET stable across the backend processes that serve the instance. Use the generated secret from your deployment tooling or inject it from your secret manager. A mismatch can interrupt authentication even when the identity provider accepts the user.

Use local accounts

Local sign-in stores password hashes in the application database. The first-admin setup creates the initial Owner; later members join by invitation. Configure mail delivery if your onboarding and password-recovery process relies on email.

Verify the complete flow with a test account: invitation, sign-in, sign-out and recovery. A working owner session does not prove that a new member can join.

Tale sends no verification mail, so an address is confirmed by whoever provisioned it: the setup wizard’s first Owner, an admin adding a person under Settings > Members, and the operator’s deployment all count as that assertion, and the account is usable straight away. Connected applications read this as the email_verified claim on the identity Tale issues, so a colleague an admin just added can sign in to them immediately. An account that comes from enterprise SSO, SCIM or trusted headers keeps whatever its directory reports instead.

Connect enterprise sign-in

Configure the organization under Settings > Enterprise SSO. Microsoft Entra ID and generic OIDC use issuer discovery; OAuth2 takes explicit authorization, token and userinfo endpoints; SAML uses metadata, an assertion-consumer URL and signing certificates.

Use the callback and metadata URLs shown there rather than reconstructing them. Current native OIDC callbacks use /api/sso/callback; the compatibility route /http_api/api/sso/callback is also supported for existing registrations. The IdP registration must match the URL used by the flow.

Follow Enterprise SSO and provisioning for protocol-specific setup, claim mapping, default roles, team synchronization and SCIM. Test sign-in in a separate browser session before ending the administrator session used to configure it. Discovery passing does not prove claims, group permissions or a complete sign-in.

Trust an authentication proxy

An application that already signs its users in can hand them into one organization through its reverse proxy. An Admin turns the feature on under Settings > Enterprise SSO, in the Trusted headers card: choose the highest role the proxy may assert, then create a key and copy it, because it is shown once. Point the proxy's sign-in at /api/trusted-headers/authenticate with that key in the Remote-Internal-Secret header and the identity headers Remote-Email, Remote-Name, Remote-Role and Remote-Teams. The environment reference lists the TRUSTED_*_HEADER variables for renaming those headers.

The key decides the organization. A member of that organization signs in; an address the deployment has never seen becomes a new member with the asserted role; an existing account from another organization is refused. Owner is never assertable, and a role above the organization's ceiling is lowered to it. On every sign-in the member's seat follows the asserted role, so Settings > Members shows what the proxy asserted; an Owner seat never changes. Turning the card off refuses every key without revoking one; revoking a key does not end the sessions it started.

Remote-Teams lists team names separated by commas, for example Finance,Operations; an id:name entry such as t-fin:Finance is accepted too, and teams are matched and created by name. An omitted header leaves team management alone; a present empty header removes memberships previously granted by this synchronization. Invalid entries can therefore remove synchronized memberships. Manually granted memberships are preserved.

A proxied visitor is signed in on the app's first own request: when that request carries the key and the identity header but no session cookie, the backend mints the session right there and the app opens signed in — no sign-in page, no redirect. Should the app still land on its sign-in page (a stale cookie, for example), the page hands the browser to the hand-off address by itself, and a refusal comes back to that page with its reason. Routing the proxy's /log-in straight to the hand-off address remains supported; the address answers a success with a redirect to the app and a refusal as a page with its status. Because the proxy owns the session, the app offers no sign-out to a proxied member; after an inactivity sign-out the automatic sign-in pauses until the member continues from the notice.

To show Tale inside the application's own page rather than in a tab, an Admin lists that page's origin under Embedding on the same settings page. Tale's pages then answer with a frame-ancestors policy naming 'self' and the listed origins instead of refusing every frame, and the X-Frame-Options header is left off. The list belongs to one organization, but the sign-in shell is one document for the whole deployment, so an origin any organization admits may load it. The browser sends the session cookie into a frame only when the surrounding page is on the same site as Tale, for example a subdomain of the host or Tale served under the host's own domain; a cross-site frame shows the sign-in page instead.

Diagnose sign-in failures

Use a staging organization for mapping changes and keep a tested administrative recovery path. Authentication changes can affect every member whose identity depends on the connection.