Skip to content

[No QA] Update Managing-Single-Sign-On-(SSO)-in-Expensify.md #79751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
stephanieelliott wants to merge 1 commit into from
+103 −60
Closed

[No QA] Update Managing-Single-Sign-On-(SSO)-in-Expensify.md #79751

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 103 additions & 60 deletions ...rticles/expensify-classic/domains/Managing-Single-Sign-On-(SSO)-in-Expensify.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,86 +1,129 @@
---
title: Managing Single Sign-On (SSO) and User Authentication in Expensify
description: Learn how to effectively manage Single Sign-On (SSO) and user authentication in Expensify alongside your preferred SSO provider.
keywords: [Expensify Classic, SAML, single sign-on, SSO]
description: Learn how to set up and manage SAML-based Single Sign-On (SSO) for secure member login in Expensify Classic.
keywords: [Expensify Classic, SAML SSO, single sign-on, identity provider, domain security, authentication, user login]
---

Set up secure and streamlined login across your organization by enabling SAML Single Sign-On (SSO) in Expensify Classic. This allows Workspace members to authenticate using your identity provider (IdP), rather than creating separate credentials.

Expensify supports Single Sign-On (SSO) through the SAML protocol, allowing you to optimize user authentication and improve security across your organization. Whether you're an IT admin configuring your domain or a team lead ensuring secure user access, this guide walks you through setting up and managing SAML SSO for your Expensify account
---

# Where to find SAML Single Sign-On (SSO) settings

Before setting up SSO, make sure your domain is verified.
[Learn how to claim and verify your domain](https://help.expensify.com/articles/expensify-classic/domains/Claim-And-Verify-A-Domain#step-2-verify-domain-ownership)

Once your domain is verified:

1. Go to **Settings > Domains > [Domain Name] > SAML**.
2. From the **SAML** section:
- Download Expensify’s **Service Provider metadata** to upload to your IdP.
- Enter your **IdP metadata** or upload the file from your provider.
- Toggle **SAML required for login** to enforce SSO-only login.

---

# Accessing SAML Settings
⚠️ **Pre-requisite:** Ensure your [domain is verified](https://help.expensify.com/articles/expensify-classic/domains/Claim-And-Verify-A-Domain#step-2-verify-domain-ownership).
# Who can manage SAML Single Sign-On (SSO)

1. Navigate to: **Settings > Domains > [Domain Name] > SAML**.
2. **From the Domains page:**
- Download Expensify's **Service Provider Metadata** to provide to your Identity Provider.
- Enter the **Identity Provider Metadata** from your SSO provider. (Contact your provider if unsure how to obtain this).
- Enable the **"SAML required for login"** option, ensuring users sign in via SSO only.
- Only **Domain Admins** can configure SAML for verified domains.
- SAML login applies to all Workspace members whose emails match the verified domain.

---

# Provider-Specific Setup Instructions
# How to set up SAML Single Sign-On (SSO) with your identity provider

Follow these links for configuration steps with your identity provider:

Click on your Identity (SAML) Provider for detailed steps:
- [Amazon Web Services (AWS SSO)](https://static.global.sso.amazonaws.com/app-202a715cb67cddd9/instructions/index.htm)
- [Google SAML (Gsuite)](https://support.google.com/a/answer/7371682)
- [Microsoft Entra ID (formerly Azure Active Directory)](https://learn.microsoft.com/en-us/entra/identity/saas-apps/expensify-tutorial)
- [Okta](https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-Expensify.html)
- [OneLogin](https://onelogin.service-now.com/support?id=kb_article&sys_id=e44c9e52db187410fe39dde7489619ba)
- [Oracle Identity Cloud Service](https://docs.oracle.com/en/cloud/paas/identity-cloud/idcsc/expensify.html#Expensify)
- [SAASPASS](https://saaspass.com/saaspass/expensify-two-factor-authentication-2fa-single-sign-on-sso-saml.html)
- Microsoft ADFS (instructions below).
- [Amazon Web Services (AWS SSO)](https://static.global.sso.amazonaws.com/app-202a715cb67cddd9/instructions/index.htm)
- [Google Workspace / SAML (Gsuite)](https://support.google.com/a/answer/7371682)
- [Microsoft Entra ID (formerly Azure AD)](https://learn.microsoft.com/en-us/entra/identity/saas-apps/expensify-tutorial)
- [Okta](https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-Expensify.html)
- [OneLogin](https://onelogin.service-now.com/support?id=kb_article&sys_id=e44c9e52db187410fe39dde7489619ba)
- [Oracle Identity Cloud Service](https://docs.oracle.com/en/cloud/paas/identity-cloud/idcsc/expensify.html#Expensify)
- [SAASPASS](https://saaspass.com/saaspass/expensify-two-factor-authentication-2fa-single-sign-on-sso-saml.html)
- Microsoft ADFS – see instructions below

**Note:** If your provider isn't listed, contact them directly for guidance.
**Note:** If your provider isn't listed, contact them directly for guidance with metadata and setup.

---

# Common Troubleshooting Scenarios
# How SAML Single Sign-On (SSO) affects login behavior

## User Login with SSO
- Employees using their **company email** or a **secondary linked email** (e.g., Gmail) will be prompted to log in through SSO.
- Secondary login setup guide: [Change or Add Email Address](https://help.expensify.com/articles/expensify-classic/settings/Change-or-add-email-address).
- Members with email addresses matching your verified domain will be prompted to log in through your configured IdP.
- Members using a personal or secondary email (e.g., Gmail) must [update their email address](https://help.expensify.com/articles/expensify-classic/settings/Change-or-add-email-address) to match the verified domain for SSO access.

## Error During SSO Setup?
- Use [samltool.com](https://samltool.com) to validate your configuration data.
- Contact your Account Manager or Concierge for further help.
---

## What is Expensify's Entity ID?
- Default: `https://expensify.com`
- For Multi-Domain setups: `https://expensify.com/mydomainname.com`.
# Troubleshooting SAML Single Sign-On (SSO)

## Managing Multiple Domains with One Entity ID
Yes, it's possible. Contact Concierge or your Account Manager to enable this feature.
## If setup fails or login doesn't work:

## Updating Microsoft Entra ID SSO Certificate
Steps to avoid configuration errors during certificate renewal:
1. **Create** a new certificate in Microsoft Entra.
2. **Remove** the old certificate before activating the new one.
3. Replace the **IDP** in Expensify with the new one.
4. Log in via SSO.
- Use [samltool.com](https://samltool.com) to validate your IdP metadata and certificate.
- Confirm that your public certificate is in **PEM** format.
- Make sure the email domain in your IdP exactly matches your verified domain in Expensify.
- Confirm that your domain is verified in Expensify before enabling SAML.

If issues persist, contact Concierge Support for assistance.
## What is Expensify’s Entity ID?

---
- Standard setup: `https://expensify.com`
- Multi-domain setup: `https://expensify.com/yourdomain.com`

## Can I manage multiple domains with one Entity ID?

Yes, managing multiple domains with one Entity ID is supported. Contact Concierge or your Account Manager to enable this feature.

# Advanced configurations for SAML Single Sign-On (SSO)

## Okta SCIM API and SAML provisioning

Once SAML is enabled:

1. Go to `Domains > [Domain Name] > SAML`.
2. Toggle on both **Enable SAML login** and **Require SAML login**.
3. In Okta, add Expensify as an app and configure attribute mappings.
4. Request SCIM API access via **concierge@expensify.com**.
5. Add the SCIM token in your Okta provisioning settings.

Refer to Okta’s documentation for complete instructions.

## Microsoft ADFS configuration

1. Open the **ADFS Management Console** and create a new trust.
2. Upload Expensify’s metadata XML file.
3. Map **LDAP attributes** (email or UPN) to outgoing claims.
4. Add two claim rules:
- Send LDAP Attributes as Claims
- Transform Incoming Claim to Name ID

## Microsoft Entra ID certificate update process

To avoid setup errors during certificate renewal:

1. Create the new certificate in Microsoft Entra.
2. Remove the old certificate before activating the new one.
3. Replace the existing IdP metadata in Expensify.
4. Log in via SSO to confirm the new certificate works.

# FAQ

## Can I use SAML for multiple Workspaces?

Yes, as long as all members are part of the same verified domain, SAML access applies across all Workspaces they belong to.

## How can I confirm my SAML SSO setup is correct?

Before enabling **Require SAML login**, make sure your SAML connection is working by testing both SP-initiated and IdP-initiated logins. You should also confirm that:

- The correct certificate and endpoints are in your Expensify metadata
- Members can log in successfully using the SAML flow

## Can I test a new SAML SSO setup without locking users out?

Yes. Disable **Require SAML login** before making changes. This allows users to log in with email and password if SAML setup fails. Once you’ve confirmed that login works, you can re-enable enforcement.

## What happens if a member can’t log in after SAML SSO is enabled?

First, confirm that the member’s email matches your verified domain and that their account exists in your Identity Provider (IdP) with the correct access permissions.

# Advanced Configurations

## Okta SCIM API for User Deactivation
Ensure your domain is verified and the SAML setup is complete. Then, do the following:
1. Go to **Settings > Domains > [Domain Name] > SAML**.
2. Enable SAML Login and toggle **Required for login**.
3. In Okta, add Expensify as an application, and configure user profile mappings.
4. Request **Okta SCIM API** activation via concierge@expensify.com.
5. Integrate the **SCIM token** with Okta API provisioning.

Refer to the full setup in Okta's documentation for attribute mapping and provisioning options.

## Microsoft ADFS SAML Authentication
1. Open **ADFS Management Console** and add a new trust.
2. Import Expensify's metadata XML from the SAML page.
3. Configure **LDAP Attributes** for email or UPN.
4. Add two claim rules:
- Send LDAP Attributes as Claims.
- Transform Incoming Claim (Name ID).
If they’re still unable to log in, follow the steps in [Troubleshoot SAML SSO login](LINK) to identify and resolve the issue.

Loading