> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forecastable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up single sign-on

> Verify your company’s email domains, connect an OIDC or SAML identity provider, and manage sign-in policies.

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](https://docs.forecastable.com/administration/sso-trust-policies.md) 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**.

| DNS field | What to enter |
| - | - |
| Type | `TXT` |
| Name / host | The displayed `_forecastable-sso.example.com` name |
| Value | The complete displayed `forecastable-sso-verification=...` value |

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](https://docs.forecastable.com/administration/sso-trust-policies.md) 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.

| Forecastable field | Meaning |
| - | - |
| Redirect URI | Copy this exact address into the provider's allowed callback or redirect URLs. It ends in `/oauth2/idpresponse`. |
| OIDC issuer URL | The identifier of your identity provider, copied from its discovery document's `issuer` value. Preserve any trailing slash. |
| Provider client ID | The identifier of the application you created in the provider. |
| Provider client secret | That application's secret. Treat it as a password and never put it in screenshots, logs, or Git. |

**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.

| Field | Meaning |
| - | - |
| ACS / reply URL | Copy the displayed callback ending in `/saml2/idpresponse` into your provider. |
| Audience / entity ID | Copy the displayed `urn:amazon:cognito:sp:...` value exactly. |
| SAML metadata URL | A publicly accessible HTTPS URL for your application's provider metadata, including its signing certificate and sign-in endpoint. |
| NameID | Configure a stable identifier for the person, such as a persistent subject identifier. |

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.

| Field | Typical OIDC name | Purpose |
| - | - | - |
| Email address field | `email` | Contains the work email that matches the Forecastable account and verified domain. |
| Email verification field | `email_verified` | Required to be true under **Verified email**. Company-managed identities do not require a true value. |
| Display name field | `name` | Contains the person's display name. It does not grant permissions. |

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.

### Share a company sign-in link

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](https://docs.forecastable.com/administration/sso-trust-policies.md). 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](https://docs.forecastable.com/administration/sso-trust-policies.md).
* **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](https://docs.forecastable.com/administration/sign-in-methods.md). For errors, read [SSO troubleshooting](https://docs.forecastable.com/administration/sso-troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.