Enterprise SSO

Enterprise SSO lets your organization authenticate via your own identity provider (IdP) using SAML 2.0. Users with a matching email domain are automatically routed to your IdP at sign-in — no individual invites required.

Supported identity providers

---

Setting up SSO

1. Open the SSO panel

1. Sign in as an Admin on the Enterprise plan
2. Go to Settings in the sidebar
3. Scroll to the Single Sign-On (SSO) section
4. Click Add connection

2. Choose your identity provider

Select your IdP from the provider picker. ChangeVault pre-fills sensible defaults for attribute mappings.

3. Enter basic details

4. Configure the IdP connection

Option A — Metadata URL (recommended)

Paste your IdP's federation metadata URL. ChangeVault fetches the certificate and endpoints automatically.

Option B — Manual

Enter the IdP Entity ID, SSO URL and X.509 certificate (PEM format) individually.

5. Configure ChangeVault as a Service Provider in your IdP

After creating the connection, ChangeVault shows two values to copy into your IdP:

---

Provider-specific instructions

Microsoft Entra ID

1. In the Azure Portal → Entra ID → Enterprise applications → New application
2. Choose Create your own application → Non-gallery → name it ChangeVault → Create
3. Go to Single sign-on → SAML
4. Under Basic SAML Configuration:
   • Identifier (Entity ID): paste the SP Entity ID from ChangeVault
   • Reply URL (ACS URL): paste the ACS URL from ChangeVault
5. Under SAML Signing Certificate, copy the App Federation Metadata URL and paste it as the Metadata URL in ChangeVault
6. Under Users and groups, assign users or groups to the application
7. To send group membership claims for role mapping: go to Token configuration → Add groups claim → select Security groups

Google Workspace

1. In the Google Admin Console → Apps → Web and mobile apps → Add app → Add custom SAML app
2. Download the IdP metadata or copy the SSO URL and certificate
3. Set the ACS URL and Entity ID from ChangeVault
4. Add attribute mappings: email, firstName, lastName
5. Assign users or organizational units to the app

Okta

1. In Okta → Applications → Create App Integration → SAML 2.0
2. Set the Single sign-on URL (ACS URL) and Audience URI (SP Entity ID) from ChangeVault
3. Add attribute statements for email, firstName, lastName
4. Add a Group Attribute Statement named groups (regex: .*) for role mapping
5. Copy the Identity Provider metadata URL from the Sign On tab and paste it in ChangeVault

---

Group → role mapping

You can automatically assign ChangeVault roles based on the IdP group a user belongs to.

How it works

When a user signs in via SSO for the first time (or rejoins the organization), ChangeVault reads the SAML attribute containing their groups and assigns the matching role. If no mapping matches, the user keeps the default Member role.

Configuring mappings

1. In Settings → SSO, expand a connection and click Group → Role mappings

2. Set the Group attribute name — the SAML attribute your IdP sends group data in:

   Provider	Typical attribute name
   Entra ID	http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
   Google Workspace	groups
   Okta	groups

3. Add mapping rows:

   Group value	ChangeVault role
   IT-Admins	Admin
   IT-Staff	Member
   IT-Viewers	Reader

4. For Entra ID, group values can be the group's display name or its Object ID (GUID) depending on how you configured the token claims.

---

Sign-in flow

Once SSO is configured and active:

1. A user visits https://app.changevault.dev/sign-in
2. They type their email address (e.g. alice@contoso.com) and click Continue
3. ChangeVault detects the contoso.com domain and redirects to your IdP
4. The user authenticates with their company credentials
5. The IdP redirects back to ChangeVault with a SAML assertion
6. ChangeVault creates or updates the user's account and applies any group → role mappings
7. The user lands in the dashboard

---

Managing connections

Removing a connection does not delete existing user accounts — it only prevents future SSO sign-ins via that connection.

---

Troubleshooting