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

# Single Sign-On (SSO)

> Let your users sign in to your app with your company's identity provider, like Okta, Microsoft Entra ID, or Google Workspace, or make SSO the only way in.

Let your users sign in to your app with your company's identity provider (the service your company uses to manage work accounts, such as Okta, Microsoft Entra ID, or Google Workspace). Offer SSO next to your other sign-in methods, or make it the only way in for an internal app.

* One login: your users sign in with the work account they already have.
* One place to manage access: your identity provider decides who gets in.
* No new passwords for your users, and none for you to reset.

### How do I set up SSO for my app?

Single sign-on is available on Business plans and above, on apps using Hercules Auth 2.0. If your app was created before Hercules Auth 2.0, [upgrade it first](/docs/apps/users-auth/upgrade-to-hercules-auth-2).

<Steps>
  <Step title="Connect your identity provider">
    Go to **Organization → SSO** and choose **Connect identity provider**. Follow the steps in [SSO
    / SAML](/docs/platform/sso-saml), including verifying your email domains. You do this once, and every
    app in your organization can use it.
  </Step>

  <Step title="Turn on SSO in your app">
    In your app, go to **Users & Access → Auth Portal**. Under **Sign-in Methods**, turn on **Single
    sign-on (SSO)**. If your organization has more than one identity provider, pick the one this app
    uses.
  </Step>

  <Step title="Save">
    Click **Save**. Your sign-in page shows the new button within about a minute.
  </Step>
</Steps>

If your organization has no verified identity provider yet, the **Single sign-on (SSO)** row shows **Set up SSO**, which opens **Organization → SSO**.

### What do my users see?

A **Continue with SSO** button on your app's sign-in page. Clicking it sends them to your identity provider. After they sign in there, they come back to your app signed in. The first time someone signs in, Hercules creates their account in your app.

The button follows your [Auth Portal language](/docs/apps/users-auth/customize-auth-portal#how-do-i-change-the-auth-portal-language).

### How do I make SSO the only way to sign in?

1. Turn on SSO in **Users & Access → Auth Portal** first.
2. Go to **Users & Access → Sign-in Rules**.
3. Under **Who can sign up?**, choose **Only SSO users** and confirm.

This takes effect right away. Your app's other sign-in methods are hidden, and only people your identity provider signs in can sign up or sign in. People already signed in stay signed in until their session ends.

While **Only SSO users** is selected, you cannot turn SSO off in the Auth Portal. Change **Who can sign up?** first.

### How do I change which identity provider my app uses?

Go to **Users & Access → Auth Portal**, click **Configure** on the **Single sign-on (SSO)** row, pick another provider, and click **Save**. To add or remove providers, click **Manage identity providers**.

### What happens if SSO stops working?

If your identity provider can no longer be used, for example because a domain's verification lapsed, the **Continue with SSO** button disappears from your sign-in page. Your other sign-in methods keep working.

If your app is set to **Only SSO users**, nobody can sign in until you fix it. Your sign-in page tells users: "Single sign-on is not set up for this app yet. Contact the app owner." Your other sign-in methods stay hidden, so the app does not open up to everyone. Fix the provider under **Organization → SSO**. See [Why do I need to verify my domain?](/docs/platform/sso-saml#why-do-i-need-to-verify-my-domain) for the 7 days Hercules gives you to restore a missing DNS record.

### Additional FAQ

<AccordionGroup>
  <Accordion title="Which identity providers work?">
    Any provider you can connect under **Organization → SSO**: Okta, Microsoft Entra ID, Google
    Workspace, OneLogin, JumpCloud, any other SAML 2.0 provider, or an OpenID Connect provider.
  </Accordion>

  <Accordion title="Who can sign in with SSO?">
    Anyone your identity provider signs in, as long as your sign-in rules let them in. Block rules
    under **Users & Access → Sign-in Rules** apply to SSO users, and with **Only people I approve**,
    SSO users must match your approved emails or domains too. Manage who your identity provider
    signs in from your identity provider.
  </Accordion>

  <Accordion title="How do I check that SSO works before my users try it?">
    Open the provider under **Organization → SSO** and choose **Test sign-in**. You go through your
    identity provider's real sign-in, and Hercules shows who it signed in or what went wrong.
  </Accordion>

  <Accordion title="What happens if my plan changes?">
    Your app keeps SSO, and **Only SSO users** stays enforced, so your app does not open up to
    everyone. On any plan you can turn SSO off or change **Who can sign up?**. Turning SSO on,
    changing the identity provider, or choosing **Only SSO users** needs a Business plan or higher.
  </Accordion>

  <Accordion title="What happens to SSO when I transfer my app?">
    Your identity provider belongs to your organization, so it stays behind. The transferred app has
    no SSO, and if it was set to **Only SSO users**, **Who can sign up?** goes back to **Allow
    everyone**. Set up SSO again in the new organization.
  </Accordion>

  <Accordion title="Do cloned apps keep SSO?">
    Yes, when your organization's plan includes SSO. The clone signs in through the same identity
    provider and keeps **Only SSO users** if the original had it.
  </Accordion>

  <Accordion title="Is this the same as SSO for Hercules?">
    They share the same identity provider. [SSO / SAML](/docs/platform/sso-saml) lets your teammates sign
    in to Hercules itself. This page covers your app's users signing in to your app.
  </Accordion>
</AccordionGroup>

### What's next?

<Card title="Sign-in Rules" icon="shield-check" horizontal href="/docs/apps/users-auth/sign-in-rules" arrow>
  Control who can sign up for your app
</Card>

<Card title="Customize Auth Portal" icon="lock" horizontal href="/docs/apps/users-auth/customize-auth-portal" arrow>
  Customize login methods, branding, and domains
</Card>


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