Single Sign-On (SSO)

SSO lets your team sign in to Servelo through your company's identity provider (IdP) using SAML 2.0. Available on the Business plan.

How it works

Servelo acts as the SAML Service Provider (SP). Your identity provider (Azure AD, Google Workspace, Okta, or any SAML 2.0-compatible IdP) handles authentication and sends a signed assertion back to Servelo. Servelo validates the assertion, finds or creates the matching user account, and issues a session.

The flow:

1. User visits the Servelo login page, enters their org ID, and clicks Sign in with SSO.
2. Servelo redirects to your IdP with a SAML AuthnRequest.
3. Your IdP authenticates the user (password, MFA, conditional access, etc.).
4. Your IdP posts a signed SAML Response to Servelo's Assertion Consumer Service (ACS) URL.
5. Servelo validates the signature, extracts the user's email and name, and logs them in.

Setup overview

SSO setup has two sides: configuring Servelo as an application in your IdP, and entering your IdP's details into Servelo. Both steps are done by an admin.

Step 1: Register Servelo in your IdP

You need two values from Servelo to configure your IdP. Find them in Settings > Security > Single Sign-On:

Value	Where to paste it in the IdP
Entity ID	Identifier / Audience URI / Entity ID
ACS URL	Reply URL / Assertion Consumer Service URL

Both values are unique to your workspace and include your org slug. Use the Copy buttons in the settings panel to avoid typos.

Configuring Azure AD (Entra ID)

1. In the Azure Portal, go to Microsoft Entra ID > Enterprise applications.
2. Click New application, then Create your own application. Give it a name (e.g., "Servelo SSO") and select Integrate any other application you don't find in the gallery. Click Create.
3. Once created, click Set up single sign-on in the left sidebar, then choose SAML.
4. In Section 1: Basic SAML Configuration, click Edit and fill in:
   • Identifier (Entity ID): paste the Entity ID from Servelo. Click Add identifier.
   • Reply URL (Assertion Consumer Service URL): paste the ACS URL from Servelo. Click Add reply URL.
   • Leave Sign-on URL, Relay State, and Logout URL blank. Click Save.
5. In Section 2: Attributes & Claims, click Edit. The default configuration works as-is. Verify that the Unique User Identifier (Name ID) source attribute is set to user.mail. If it is not, click the Name ID row and change the source attribute to user.mail and save.
6. In Section 3: SAML Certificates, find Certificate (Base64) and click Download. Open the downloaded file in a text editor. You will see a block starting with -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----. Copy the entire contents including those header and footer lines.
7. Still in Section 3, copy the App Federation Metadata Url (you may need it for the IdP Entity ID field in Servelo).
8. In Section 4: Set up [your app name], copy the Login URL. This is the IdP SSO URL you will paste into Servelo.
9. Go to Users and groups in the left sidebar and add the users or groups who should be able to sign in via SSO. Only assigned users can authenticate.

Now go back to Servelo and complete Step 2 below.

Configuring Google Workspace

1. In the Google Admin Console, go to Apps > Web and mobile apps.
2. Click Add app > Add custom SAML app. Name it "Servelo" and click Continue.
3. On the Google Identity Provider details page:
   • Copy the SSO URL (this is the IdP SSO URL you will paste into Servelo).
   • Click Download Certificate and open the file in a text editor. Copy the entire contents including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
   • The Entity ID shown here is Google's IdP Entity ID. Copy it if you want to fill in the optional IdP Entity ID field in Servelo.
   Click Continue.
4. On Service provider details, enter:
   • ACS URL: paste the ACS URL from Servelo.
   • Entity ID: paste the Entity ID from Servelo.
   • Set Name ID format to EMAIL.
   • Set Name ID to Basic Information > Primary email.
   Click Continue, then Finish.
5. Under User access, click the app and enable it for the relevant organizational units or groups. Users who are not enabled will not be able to sign in.

Now go back to Servelo and complete Step 2 below.

Configuring Okta

1. In the Okta Admin Console, go to Applications > Create App Integration and choose SAML 2.0. Click Next.
2. Give the app a name (e.g., "Servelo") and click Next.
3. On the SAML Settings page, enter:
   • Single sign-on URL: paste the ACS URL from Servelo.
   • Audience URI (SP Entity ID): paste the Entity ID from Servelo.
   • Set Name ID format to EmailAddress.
   • Set Application username to Email.
4. Click Next. Select "I'm an Okta customer adding an internal app" and click Finish.
5. On the app's Sign On tab, scroll to the SAML Signing Certificates section. Find the active certificate, click its Actions menu, and select View IdP metadata to locate the certificate, or click Download certificate.
6. Still on the Sign On tab, click View SAML setup instructions. This page shows the Identity Provider Single Sign-On URL (IdP SSO URL) and Identity Provider Issuer (IdP Entity ID) you will need in Servelo.
7. Go to the Assignments tab and assign users or groups to the app.

Step 2: Enter IdP details in Servelo

Go to Settings > Security > Single Sign-On and fill in the following fields:

Field	Where to find it	Required
IdP Entity ID	Azure: the App Federation Metadata URL shown in Section 3. Google: the Entity ID on the IdP details page. Okta: the Identity Provider Issuer URL. Leave blank if your IdP does not provide one.	Optional
IdP SSO URL	Azure: the Login URL from Section 4 ("Set up [app name]"). Google: the SSO URL from the Google IdP details page. Okta: the Identity Provider Single Sign-On URL from the SAML setup instructions page.	Required
IdP Signing Certificate	Paste the contents of the Base64 certificate file you downloaded. Include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, or just the raw Base64 block without them. Servelo accepts either format.	Required
Allowed email domain	Enter only the domain part, e.g. yourcompany.com (no @ symbol). When set, only users whose email ends in this domain can sign in via SSO. Leave blank to allow any domain your IdP returns.	Optional

Once the fields are filled in, toggle Enable SSO on and click Save SSO settings. Test the login flow in a private browser window before turning on Require SSO.

Testing SSO

1. Open a private/incognito browser window.
2. Go to the Servelo login page and enter your org ID.
3. Click Sign in with SSO.
4. You should be redirected to your IdP's login page. Sign in with a user assigned to the Servelo app.
5. After authentication, your IdP redirects back to Servelo and you should land on the dashboard.

If you see an error, check the Troubleshooting section below.

Requiring SSO

Once SSO is working correctly, you can turn on Require SSO in the settings panel. When this is enabled:

• Password login is blocked for all users in this workspace.
• Magic link login is blocked.
• Users must sign in through your IdP via the SSO button.
• The existing Google and Microsoft OAuth buttons are not affected.

User provisioning

Servelo uses just-in-time provisioning. When a user authenticates through SSO for the first time, Servelo checks for an existing account with that email address:

• Account exists: the user is logged in normally. Their existing role (Technician, Admin, etc.) is preserved. No role changes occur.
• No account exists: a new account is created automatically with the Technician role. An admin can then promote the user in Settings > Team if needed.

Deprovisioning is not automatic. If a user is removed from your IdP, they lose the ability to sign in via SSO, but their Servelo account remains. Deactivate the account manually in Settings > Team to revoke all access.

SSO and MFA

If a user has Servelo's built-in MFA enabled, they will be prompted for their authenticator code after successful SSO authentication. This is in addition to any MFA your IdP enforces. In most setups, you will want to rely on your IdP's MFA (Azure Conditional Access, Google 2-Step, Okta MFA policy) and disable Servelo's built-in MFA for SSO users to avoid double prompts.

SP metadata

Servelo generates a standard SAML SP metadata XML document for your workspace. Some IdPs can import this directly instead of requiring manual field entry. The metadata URL is:

https://api.serveloapp.com/api/auth/sso/{your-org-slug}/metadata

A link to your workspace's metadata XML is shown in the SSO settings panel once SSO is enabled.

Troubleshooting

Error	Likely cause
SSO not configured for this organization	SSO is not enabled in Settings > Security, or the IdP certificate/URL fields are empty.
No email address in SSO response	The IdP is not sending an email address in the NameID or attributes. Check the NameID format and attribute mapping in your IdP.
SSO requires an @domain.com email address	The authenticated user's email domain does not match the Allowed email domain setting. Either update the domain restriction or assign the correct user in your IdP.
SSO authentication failed: Invalid signature	The certificate saved in Servelo doesn't match the one your IdP is signing with. Re-download the certificate from your IdP and re-paste it in Servelo.
Account is deactivated	The Servelo account for this email has been manually deactivated. Reactivate it in Settings > Team.
Redirect loop or blank page after IdP login	The ACS URL in your IdP does not exactly match Servelo's ACS URL (including trailing slashes). Copy it fresh from the settings panel.

Plan requirement

SAML SSO is available on the Business plan. The Google and Microsoft OAuth sign-in buttons on the login page are available on all plans at no extra cost, but are not configurable per-workspace and do not support IdP-side access control or domain enforcement.