> For the complete documentation index, see [llms.txt](https://help.filed.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.filed.com/reference/workspace-and-settings/sso.md).

# SSO

Enterprise single sign-on (SSO) lets your whole team authenticate through your firm's existing identity provider (IdP) instead of individual Filed credentials. Once SSO is configured for a domain, members with a matching email address sign in using **Continue with SSO** and are provisioned into your workspace automatically on their first login.

The SSO tab is visible to admins only. Non-admin members who navigate to this page see a message: "Only admins can manage SSO."

## Supported protocols

Filed supports two SSO protocols:

* **OIDC (OpenID Connect)** - the recommended choice for modern identity providers such as Okta, Microsoft Entra ID (Azure AD), Google Workspace, and Cisco Duo.
* **SAML 2.0** - for providers that do not support OIDC or where your IT policy requires SAML.

The protocol is set when the provider is first created and cannot be changed afterwards; to switch protocols, delete and re-create the provider.

## Before you begin

Before configuring SSO in Filed, have the following ready:

* Admin role in Filed
* Admin access to your identity provider's admin console
* For OIDC: the issuer URL, a client ID, and a client secret from your IdP's application registration
* For SAML: the IdP sign-on URL (entry point), the IdP signing certificate (PEM format), a callback URL, and a service-provider entity ID

## Adding an SSO provider

Click **Add provider** in the top-right corner of the SSO page to open the provider dialog. Fields common to both protocols:

* **Protocol** - OIDC or SAML (cannot be changed after creation)
* **Provider ID** - a short name you choose for this SSO connection, such as `acmecpa-entra`. It becomes part of the callback URL you register with your identity provider, so pick something simple: lowercase letters, numbers, and hyphens, no spaces. It cannot be changed later. If you leave it blank, Filed generates a long random ID for you - this works, but your callback URL is easier to read (and to register ahead of time) if you set your own.
* **Email domain** - the domain portion of your team's email addresses (e.g. `acmecpa.com`); Filed uses this to route sign-ins correctly
* **Default role** - the role automatically assigned to members provisioned by this provider (Level 1, Level 2, Level 3, or Admin)

### OIDC configuration

Additional fields for OIDC providers:

* **Issuer URL** - the base URL of the identity provider's OpenID Connect discovery endpoint, e.g. `https://login.microsoftonline.com/<tenant>/v2.0`. Must be an HTTPS URL.
* **Client ID** - the application/client ID from your IdP's app registration
* **Client secret** - the secret associated with the client ID (shown as a password field; when editing an existing provider, leave this blank to keep the current secret)

Filed automatically derives the discovery endpoint from the issuer URL using the standard `/.well-known/openid-configuration` path. The required scopes are `openid`, `profile`, and `email`; ensure these are enabled in your IdP application.

The callback URL to register in your IdP is:

```
https://web.apps.filed.com/api/auth/sso/callback/<provider-id>
```

Replace `<provider-id>` with the Provider ID you set (or the auto-generated UUID shown after creation).

### SAML configuration

Additional fields for SAML providers:

* **Issuer** - the entity ID or issuer string for the identity provider
* **IdP sign-on URL (entry point)** - the URL your IdP uses to handle authentication requests; must be HTTPS
* **Callback URL** - the URL Filed uses to receive SAML assertions; register this in your IdP as the ACS (Assertion Consumer Service) URL
* **Service-provider entity ID** - the identifier Filed presents to the IdP as the service provider
* **IdP signing certificate** - the PEM-encoded certificate used to verify SAML assertions; paste the full certificate text into the textarea

When editing an existing SAML provider, leaving any credential field blank keeps the current value on file.

## Default role for new members

Each provider has a **Default role** setting (Level 1, Level 2, Level 3, or Admin). A member provisioned on their first SSO login receives this role automatically. You can change a provisioned member's role at any time from the Members tab, without affecting the provider's default.

## Setting up Microsoft Entra ID SSO (OIDC)

Microsoft Entra ID (formerly Azure AD) supports OIDC through an app registration in the Microsoft Entra admin center. The setup has two halves: first you register Filed as an application in Entra, then you copy three values from that registration (issuer URL, client ID, client secret) into the Add provider dialog in Filed.

The examples below use a fictional firm, Acme CPA, whose team signs in with `@acmecpa.com` email addresses.

### Step 1: Decide on a Provider ID

Before touching Entra, pick a Provider ID, for example `acmecpa-entra`. You need it now because it is part of the redirect URI you register in Entra:

```
https://web.apps.filed.com/api/auth/sso/callback/acmecpa-entra
```

### Step 2: Register Filed as an application in Entra

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as an administrator.
2. Go to **Identity > Applications > App registrations** and click **New registration**.
3. Name the application something recognizable, such as `Filed SSO`.
4. Under **Supported account types**, keep the default **Accounts in this organizational directory only (single tenant)**.
5. Under **Redirect URI**, choose **Web** from the platform dropdown and paste your callback URL, e.g. `https://web.apps.filed.com/api/auth/sso/callback/acmecpa-entra`.
6. Click **Register**.

### Step 3: Copy the IDs from the Overview page

After registration, Entra shows the app's **Overview** page. Copy two values from it:

* **Application (client) ID** - a value like `1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d`. This goes into the **Client ID** field in Filed.
* **Directory (tenant) ID** - a value like `9f8e7d6c-5b4a-3c2d-1e0f-9a8b7c6d5e4f`. You use it to build the **Issuer URL** for Filed:

```
https://login.microsoftonline.com/9f8e7d6c-5b4a-3c2d-1e0f-9a8b7c6d5e4f/v2.0
```

Replace the middle segment with your own Directory (tenant) ID. Do not add a trailing slash.

### Step 4: Create a client secret

1. In the app registration, go to **Certificates & secrets** and click **New client secret**.
2. Give it a description (e.g. `Filed SSO secret`) and choose an expiry. Entra defaults to 180 days; choose the longest period your IT policy allows and set a reminder before it expires. When the secret expires, SSO sign-ins stop working until you create a new secret and update the provider in Filed.
3. Click **Add**, then copy the secret from the **Value** column right away - it looks something like `Q3x8~kZ2mNp...` and is shown in full only once. Make sure you copy **Value**, not **Secret ID** (the Secret ID is another UUID and will not work).

### Step 5: Check API permissions

Under **API permissions**, confirm the delegated Microsoft Graph permissions **openid**, **profile**, and **email** are present so Filed can read the user's identity. New registrations include `openid` and `profile` (via User.Read) by default; add **email** with **Add a permission > Microsoft Graph > Delegated permissions** if it is missing.

### Step 6: Create the provider in Filed

In Filed, go to **Settings > SSO**, click **Add provider**, and fill in the dialog:

| Field in Filed | What to enter (Acme CPA example)                                              |
| -------------- | ----------------------------------------------------------------------------- |
| Protocol       | OIDC                                                                          |
| Provider ID    | `acmecpa-entra` (the one from Step 1)                                         |
| Email domain   | `acmecpa.com`                                                                 |
| Issuer URL     | `https://login.microsoftonline.com/9f8e7d6c-5b4a-3c2d-1e0f-9a8b7c6d5e4f/v2.0` |
| Client ID      | `1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d`                                        |
| Client secret  | the **Value** copied in Step 4                                                |
| Default role   | the role new team members should receive, e.g. Level 1                        |

Click **Add provider**. Team members with an `@acmecpa.com` email can now sign in with **Continue with SSO** and are added to the workspace automatically on first login.

**If sign-in redirects back to Filed with `missing_user_info`**, Filed could not read an email address for the signing-in user. This is unrelated to the ID token's optional claims (adding **email** under **Token configuration** does not fix it) - Filed reads the user's email from Microsoft Graph's userinfo endpoint, which returns an email only if the user's **Email** attribute is populated in Entra. To fix it:

1. In the Entra admin center, go to **Users**, open the affected user, and select the **Properties** tab.
2. Under **Contact Information**, check the **Email** field. If it is blank, click the edit (pencil) icon and set it to the user's `@yourdomain.com` address, then save.
3. Have the user sign in again.

This must be set for every user who will sign in via Entra SSO, not just admins. Accounts that were originally invited as B2B guests (their **Mail nickname** ends in `#EXT#`) are especially likely to have this field blank even after being converted to full members.

## Setting up Duo SSO (OIDC)

Cisco Duo supports OIDC via its "Generic OIDC Relying Party" application type in the Duo Admin Panel. The configuration maps as follows:

* The **Issuer URL** in Filed comes from the Duo OpenID Connect metadata; it follows the pattern `https://sso-<id>.sso.duosecurity.com/oidc/<client-id>` - copy the exact value from the Duo metadata endpoint rather than constructing it manually.
* The **Client ID** and **Client secret** come from the Duo "Generic OIDC Relying Party" application settings.
* Register `https://web.apps.filed.com/api/auth/sso/callback/<provider-id>` as the redirect URI in the Duo application.
* Ensure that the **openid**, **profile**, and **email** scopes are enabled in the Duo application so Filed can read the user's identity.

**Walkthrough: add an OIDC provider**

1. Click **Add provider**. Keep **Protocol** set to OIDC (or choose SAML), then fill in the **Email domain**, **Issuer URL**, **Client ID**, and **Client secret**, optionally set a **Provider ID**, and choose a **Default role for new members**.

![The Add SSO provider dialog with the OIDC fields filled in](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/sso-add-provider/image1.webp)

2. Click **Add provider**. The new provider appears in the table showing its domain, protocol, and default role.

![The new provider listed in the SSO table](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/sso-add-provider/image2.webp)

## Editing an existing provider

Open the three-dot menu on a provider row and select **Edit** to re-open the dialog in edit mode. All fields except Protocol and Provider ID can be changed (those two are fixed after creation). For OIDC, leaving the client secret blank preserves the current secret; for SAML, leaving credential fields blank preserves existing values.

Domain changes take effect immediately; sign-in requests from the old domain will no longer match this provider.

**Walkthrough: change a provider's default role**

1. Open the **⋯** menu on a provider row and select **Edit**. The Edit SSO provider dialog opens with the current values (Protocol and Provider ID are fixed).

![The Edit SSO provider dialog](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/sso-edit-provider/image1.webp)

2. Change the **Default role for new members** and click **Save changes**. The updated role is reflected in the provider row.

![The default role changed in the edit dialog](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/sso-edit-provider/image2.webp)

## Removing a provider

Open the three-dot menu on the provider row and select the remove option; a confirmation dialog prompts before deletion. Once removed, the SSO login path for that domain is gone. Existing members provisioned through the provider retain their workspace access and role; they simply can no longer sign in via SSO and would need an alternative authentication method set up.

**Walkthrough: remove a provider**

Open the **⋯** menu on a provider row and select **Remove**. A confirmation dialog warns that members from that domain will no longer be able to sign in via SSO. Confirm to delete the provider.

![The Remove SSO provider confirmation dialog](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/sso-remove-provider/image1.webp)

## Troubleshooting

**Sign-in redirects back with `error=invalid_provider&error_description=missing_user_info`** - Filed exchanged the authorization code successfully but could not find an email address for the user. For Entra ID, see [If sign-in redirects back to Filed with `missing_user_info`](#setting-up-microsoft-entra-id-sso-oidc) above - this means the user's **Email** attribute is not set in the identity provider's directory, not a Filed-side misconfiguration. For other OIDC providers, verify the `email` scope is consented and that the signing-in user actually has an email address on file with the provider.

**Sign-in fails with a scope or claim error** - Filed cannot read the user's email or name from the IdP token. Verify that the `profile` and `email` scopes are enabled and consented in your IdP application, and that the application is configured to include these claims in the ID token.

**Sign-in fails with an issuer or provider error** - The issuer URL in Filed may not match what the IdP presents. Double-check the issuer URL in Filed against the `issuer` value in your IdP's `.well-known/openid-configuration` response. Ensure there is no trailing slash mismatch.

**General checklist:**

* For OIDC: callback URL registered in the IdP exactly matches `https://web.apps.filed.com/api/auth/sso/callback/<provider-id>`
* Email domain on the provider matches the domain of the accounts signing in
* For SAML: certificate is the full PEM block including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`
* For OIDC: issuer is an HTTPS URL with no trailing slash


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.filed.com/reference/workspace-and-settings/sso.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.