Skip to main content
Single sign-on (SSO) lets your team sign in to Forecastable through your company’s identity provider. Forecastable supports OpenID Connect (OIDC) and SAML 2.0, including compatible Authentik, Okta, Auth0, and other providers. Each organization has one active provider and can verify multiple email domains. Open Settings > Single sign-on (/settings/sso) in the environment you want to configure. You need organization settings management permission. Configuration belongs to your active organization; switch organizations before configuring another team.

Before you start

Have these items ready:
  • Access to your email domain’s DNS records.
  • Administrator access to your identity provider.
  • An existing Forecastable account in your organization for testing.
  • A working native password account for emergency access if you plan to require SSO.
The default trust policy is Company-managed identities. It accepts existing accounts in your organization when your provider controls their work email addresses. It does not require users to confirm their email through an additional email message. Read Identity trust policies before connecting a provider that allows self-registration or user-edited email addresses.

Step 1: Verify your domain

  1. Enter the part after @ in your team’s work emails, such as example.com. Enter a domain, not an email address, website URL, or wildcard.
  2. Click Get DNS record.
  3. Add the displayed TXT record in your DNS provider. Use the copy buttons beside the record type, name, and value.
  4. Click Verify example.com after the record is publicly visible.
  5. Click Continue to identity provider.
Some DNS providers automatically append your domain. If yours does, enter _forecastable-sso as the host rather than adding the domain twice. Copy the actual challenge value from Forecastable; sample values do not verify ownership. DNS changes can take time to appear. A challenge expires after seven days; use Generate new record and replace the TXT value if it expires. A domain assigned to another Forecastable organization cannot be claimed. Verify each email domain separately: verifying example.com does not verify sales.example.com. Domain verification proves that your organization controls the domain. It does not prove that a particular person owns an email address. Your identity trust policy determines how Forecastable trusts each person’s address.

Step 2: Connect your identity provider

Create an application for Forecastable in your provider. Restrict it to the intended users or groups. Configure password requirements, MFA, and other identity checks in the provider.

OpenID Connect

Select OpenID Connect (OIDC) and use a confidential web application with authorization-code flow. Enable openid, email, and profile scopes. The issuer URL is not the redirect URI. For example, an Authentik issuer may be https://auth.example.com/application/o/forecastable/. Its discovery document is usually beneath that issuer at .well-known/openid-configuration; enter the document’s issuer value rather than the discovery document URL. The redirect URI points to Forecastable’s Cognito federation endpoint. Its hostname depends on the environment and may use an AWS Cognito domain or a configured Forecastable custom domain. Always copy the address shown in the environment’s SSO settings. Do not substitute the Forecastable login page or /login/cognito/return.

SAML 2.0

Select SAML 2.0 and create a SAML application in your provider. Start sign-in from Forecastable. Unsolicited provider-initiated callbacks do not have the browser-bound sign-in transaction and are rejected.

User details

Your provider sends named fields describing each person. OIDC calls them claims; SAML usually calls them attributes. Enter the field names, not a person’s actual email or name. OIDC defaults are filled in under User details. Change them only when your provider uses different names. For SAML, use the complete attribute name, including a URL prefix if the provider uses one. Keep the email verification field mapping configured even when using company-managed identities; this allows you to select Verified email later without forgetting the mapping.

Check and connect

  1. Click Check settings to inspect the provider and shared Cognito client configuration.
  2. Review any reported changes. A check is a configuration preview, not a successful user sign-in test.
  3. Click Connect identity provider and confirm.
  4. Forecastable switches to the management area after the connection succeeds.
Secrets are write-only. Loading an existing connection does not display its saved secret. Checks do not submit a new secret; connecting applies it. If setup partially fails, check again before retrying. The provider protocol cannot be changed in place after creation.

Manage your connection

The management area contains Sign-in policy, Identity provider, and Domains tabs. After connecting your provider, use Company sign-in link above the management tabs:
  1. Review the Sign-in address suggested from your organization name, or enter your own.
  2. Click Create link. Addresses must be unique in this environment and contain 3–63 letters, numbers, or hyphens, starting and ending with a letter or number. Reserved names such as google, sso, and logout are unavailable. Letters are saved in lowercase.
  3. Copy the saved Sign-in link, for example https://app.forecastable.com/login/acme. Use the exact hostname shown in your environment.
  4. Click Test sign-in link to open it in a new tab. It goes directly to your identity provider without asking for an email in Forecastable. An existing provider session may sign you in immediately.
  5. Share the link in your company portal, onboarding instructions, or bookmarks.
The link selects your organization; it does not grant access. Your provider supplies the authenticated email, and Forecastable still checks the active provider, exact verified domain, account, and identity trust policy. No account-association confirmation is added. To rename the address, edit it and click Save address. The previous link stops working for new sign-ins; update shared bookmarks. Retired addresses remain reserved to your organization, and you can restore one by saving it again. Changing your organization’s display name does not change its saved link. Disconnecting SSO or removing all verified domains makes the link unavailable. Its address remains reserved and works again after the connection and verified domains are restored. Backup users can still use the ordinary /login page for password recovery. The ordinary email-first SSO flow also remains available. Development and production have separate links and address settings. This feature needs no additional DNS records, certificates, or identity-provider callback URLs. An identity-provider application tile can open this link as its launch URL; it must start a Forecastable sign-in rather than send an unsolicited SAML assertion.

Sign-in policy

  • Identity trust policy: Choose Company-managed identities (the default) or Verified email. See the full comparison.
  • Require single sign-on: Off by default. When off, eligible existing accounts can use password, Google, or SSO. When on, ordinary members must use your provider; Google does not bypass this rule.
  • SSO session length: Choose 1–24 hours. The default is 12 hours.
  • Backup sign-in accounts: Choose up to five existing active users with native password sign-in in this organization. At least one is required before requiring SSO. SSO-only accounts cannot be backup accounts.
Click Save sign-in policy after changing these settings. Switching identity trust policy invalidates earlier SSO sessions so the next SSO sign-in uses the new policy. Password identities and organization roles remain intact.

Test before requiring SSO

  1. Click Test sign-in and enter the work email of an existing account on a verified domain.
  2. Open the test in its new tab and finish your provider’s authentication flow.
  3. Confirm that the correct Forecastable account opens with its existing access.
  4. Test a backup account using password sign-in in a separate browser session.
  5. Enable Require single sign-on, save, and confirm the change.
Previously issued password sessions are rejected on their next protected request when required SSO applies. Explicit backup accounts retain password sign-in and password reset. Provider assignment changes by themselves do not immediately terminate a Forecastable session; disable the Forecastable account when immediate access removal is needed.

Domains and disconnection

Use Domains to add, verify, or remove a domain. Removing a domain prevents new SSO sign-ins for that exact domain. Forecastable will not let you remove the last domain while SSO is required. Turn off Require single sign-on and save before clicking Disconnect SSO. Disconnection removes the active connection; it does not delete users, their password identities, or their saved SSO identity links. SSO does not synchronize your directory or assign Forecastable roles. Manage invitations, memberships, roles, and disabled accounts in Forecastable. For login behavior and Google sign-in, read Sign-in methods. For errors, read SSO troubleshooting.