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

# Single Sign-On (SSO)

> Configuring and using SSO to authenticate users in Fentu FSM

## Overview

Fentu FSM supports Single Sign-On (SSO), allowing your users to log in with the same identity they use across your organization — no separate Fentu password required. SSO is configured at the administration level and applies to all users in your organization.

<Note>
  SSO requires an active subscription tier that includes identity provider integration. Contact your Fentu account manager to confirm your plan supports SSO.
</Note>

## Supported Identity Providers

Fentu FSM uses the **SAML 2.0** and **OpenID Connect (OIDC)** protocols, compatible with major identity providers:

| Provider                          | Protocol        | Notes                                       |
| --------------------------------- | --------------- | ------------------------------------------- |
| **Microsoft Entra ID (Azure AD)** | SAML 2.0 / OIDC | Recommended for Microsoft 365 organizations |
| **Okta**                          | SAML 2.0 / OIDC |                                             |
| **Google Workspace**              | OIDC            |                                             |
| **OneLogin**                      | SAML 2.0        |                                             |
| **Ping Identity**                 | SAML 2.0        |                                             |
| **Custom IdP**                    | SAML 2.0        | Any SAML 2.0-compliant provider             |

***

## How SSO Works

When SSO is enabled, Fentu FSM acts as the **Service Provider (SP)**. Your identity provider (IdP) handles authentication. The flow is:

1. User navigates to your Fentu FSM login URL
2. Fentu FSM redirects the user to your IdP
3. User authenticates with their existing organizational credentials
4. IdP returns a signed assertion to Fentu FSM
5. Fentu FSM validates the assertion and logs the user in

<Info>
  User accounts are still managed in Fentu FSM (roles, permissions, branch assignments). SSO only handles the authentication step — it does not provision or deprovision users automatically unless SCIM is also configured.
</Info>

***

## Configuring SSO

### Step 1 — Gather Fentu FSM SP Metadata

<Steps>
  <Step title="Go to SSO Settings">
    Navigate to **Administration > Settings > Integrations > Single Sign-On**
  </Step>

  <Step title="Download SP Metadata">
    Click **Download SP Metadata** to get the XML file, or copy the individual values:

    * **Entity ID (Audience URI)**: `https://app.fentu.io/saml/metadata`
    * **ACS URL (Reply URL)**: `https://app.fentu.io/saml/acs`
    * **Single Logout URL**: `https://app.fentu.io/saml/slo`
  </Step>
</Steps>

### Step 2 — Configure Your Identity Provider

Register Fentu FSM as an application in your IdP using the SP metadata from Step 1. The exact steps depend on your provider:

<AccordionGroup>
  <Accordion title="Microsoft Entra ID (Azure AD)" icon="microsoft">
    1. Open the **Azure Portal** and go to **Entra ID > Enterprise Applications > New Application > Create your own application**
    2. Select **Integrate any other application you don't find in the gallery**
    3. Under **Single sign-on**, choose **SAML**
    4. Set **Identifier (Entity ID)** and **Reply URL (ACS URL)** from the Fentu FSM SP metadata
    5. Under **Attributes & Claims**, map:
       * `user.mail` → `email`
       * `user.givenname` → `firstName`
       * `user.surname` → `lastName`
    6. Download the **Certificate (Base64)** and the **App Federation Metadata URL**
  </Accordion>

  <Accordion title="Okta" icon="lock">
    1. In the **Okta Admin Console**, go to **Applications > Create App Integration**
    2. Select **SAML 2.0**
    3. Set **Single sign-on URL** to the Fentu ACS URL
    4. Set **Audience URI (SP Entity ID)** to the Fentu Entity ID
    5. Under **Attribute Statements**, map:
       * `email` → `user.email`
       * `firstName` → `user.firstName`
       * `lastName` → `user.lastName`
    6. Download the **Identity Provider Metadata** XML
  </Accordion>

  <Accordion title="Google Workspace" icon="google">
    1. In the **Google Admin Console**, go to **Apps > Web and mobile apps > Add App > Add custom SAML app**
    2. Download the **IdP metadata** from Google on the first screen
    3. Set **ACS URL** and **Entity ID** from the Fentu FSM SP metadata
    4. Under **Attribute mapping**, add:
       * `email` → Basic Information > Primary email
       * `firstName` → Basic Information > First name
       * `lastName` → Basic Information > Last name
  </Accordion>
</AccordionGroup>

### Step 3 — Enter IdP Details in Fentu FSM

<Steps>
  <Step title="Open SSO Configuration">
    Return to **Administration > Settings > Integrations > Single Sign-On**
  </Step>

  <Step title="Choose Protocol">
    Select **SAML 2.0** or **OIDC** depending on your IdP setup
  </Step>

  <Step title="Upload or Paste IdP Metadata">
    Either upload the IdP metadata XML file, or enter the values manually:

    | Field                              | Description                                           |
    | ---------------------------------- | ----------------------------------------------------- |
    | **IdP Entity ID**                  | Issuer URL from your identity provider                |
    | **IdP SSO URL**                    | The IdP endpoint where users are sent to authenticate |
    | **IdP Certificate**                | X.509 certificate used to sign SAML assertions        |
    | **Attribute Mapping — Email**      | IdP attribute that contains the user's email address  |
    | **Attribute Mapping — First Name** | IdP attribute for first name                          |
    | **Attribute Mapping — Last Name**  | IdP attribute for last name                           |
  </Step>

  <Step title="Save and Test">
    Click **Save**, then click **Test SSO Connection** to verify the configuration before enabling it for all users
  </Step>

  <Step title="Enable SSO">
    Toggle **SSO Enabled** on. Users will now be redirected to your IdP when they log in
  </Step>
</Steps>

<Warning>
  Test the SSO connection before enabling it for all users. If the configuration is incorrect, users may be locked out. Ensure at least one administrator account with a local password fallback exists before enabling SSO.
</Warning>

***

## Logging In with SSO

Once SSO is enabled, the login flow changes for your users:

<Steps>
  <Step title="Navigate to Fentu FSM">
    Go to your organization's Fentu FSM URL (e.g., `https://app.fentu.io`)
  </Step>

  <Step title="Enter Email">
    Type your organizational email address. Fentu FSM detects the SSO domain and shows the **"Sign in with SSO"** button
  </Step>

  <Step title="Redirect to IdP">
    Click the button. You are redirected to your company's identity provider login page
  </Step>

  <Step title="Authenticate">
    Log in with your organizational credentials (and complete MFA if required by your IdP)
  </Step>

  <Step title="Returned to Fentu FSM">
    After successful authentication, you are redirected back and logged in automatically
  </Step>
</Steps>

<Tip>
  Bookmark the Fentu FSM URL rather than saving a direct dashboard link. The SSO redirect flow starts from the login page.
</Tip>

***

## Managing SSO Users

### User Provisioning

SSO handles authentication only. User accounts must still be created in Fentu FSM before users can log in:

1. Create the user in **Administration > Users**
2. Set the user's **email address** to exactly match the email in your IdP
3. Assign the appropriate **role and branch**
4. The user does not need to set a Fentu password when SSO is active

<Note>
  The email address is the key that links the Fentu user account to the IdP identity. If they do not match exactly, authentication will fail.
</Note>

### Disabling SSO for a User

To allow a specific user to log in with a local password (for example, an emergency admin account):

1. Open the user record in **Administration > Users**
2. Toggle off **"Require SSO"**
3. Set a temporary password for the user
4. The user can now log in directly without going through the IdP

***

## Troubleshooting SSO

| Symptom                               | Likely Cause                                  | Resolution                                                 |
| ------------------------------------- | --------------------------------------------- | ---------------------------------------------------------- |
| "User not found" after IdP redirect   | Email in IdP does not match Fentu user record | Align email addresses between IdP and Fentu                |
| "Invalid signature" error             | Wrong IdP certificate entered                 | Re-download and upload the IdP signing certificate         |
| Redirect loop on login                | ACS URL misconfigured in IdP                  | Verify the ACS URL matches `https://app.fentu.io/saml/acs` |
| Users can't log in after enabling SSO | SSO enabled before testing                    | Use admin fallback account to correct the configuration    |
| "Attribute not found" for name        | Attribute mapping not set                     | Check attribute mapping in both IdP and Fentu SSO settings |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Two-Factor Authentication" icon="shield-halved" href="/api-reference/2fa">
    Add a second layer of security on top of SSO or password login
  </Card>

  <Card title="User Management" icon="users" href="/administration/users/user-management">
    Create and manage user accounts, roles, and branch assignments
  </Card>
</CardGroup>