Single Sign-On (SSO) Configuration

Configuring Single Sign-On (SSO) for your FieldPulse organization enables your team members to authenticate using your existing identity provider, streamlining access management and strengthening your security posture. This article covers SAML 2.0-based SSO configuration for enterprise identity providers including Okta, Azure AD, and Ping Identity.

What Is SSO and Why Implement It?

In my experience working with organizations of various sizes, the decision to implement SSO typically comes down to a few key factors. When you have more than fifteen or twenty team members, the overhead of managing individual passwords and access requests starts to compound. SSO allows you to:

Centralize authentication through your existing IdP
Enforce your organization's password policies and MFA requirements
Automate user provisioning and deprovisioning
Reduce password reset requests to your support team
Maintain audit trails of authentication events in your primary security systems

What I typically recommend is that you plan your SSO rollout alongside a review of your user roles and permissions. This ensures that when users authenticate via SSO, they land in FieldPulse with appropriate access levels already configured.

Prerequisites

Before you begin configuration, you'll need the following:

Administrator access to both FieldPulse (Admin or Owner role) and your identity provider
SAML 2.0 support in your IdP — FieldPulse does not currently support OAuth/OIDC for SSO
A verification method for your organization's domain (typically via DNS TXT record)
A test user account that is not currently used in production FieldPulse workflows

From a governance perspective, it's worth noting that SSO is only available on FieldPulse Business and Enterprise plans. If you're on our Essential plan, you'll need to upgrade before these options become visible in your admin console.

Step 1: Initiate SSO Configuration in FieldPulse

To begin, navigate to Admin > Security > Single Sign-On. You will see a toggle labeled "Enable SSO Authentication." Do not enable this until you have completed the configuration process — doing so prematurely can lock users out of their accounts.

Click Configure SAML to open the service provider metadata panel. FieldPulse will generate:

Entity ID: A unique identifier for your organization (typically https://fieldpulse.com/saml/{your-org-id})
Assertion Consumer Service URL: The endpoint where your IdP should send authentication responses
Service Provider Certificate: Used to validate signed requests (optional, depending on your security requirements)

Copy these values or download the SP metadata XML file. You'll need this information when configuring your identity provider in the next step.

Step 2: Configure Your Identity Provider

The exact steps vary by provider, but the general pattern is consistent. What I typically recommend is creating a dedicated SAML application in your IdP rather than using a generic template, as this gives you finer control over attribute mapping.

Okta Configuration

In the Okta Admin Console, go to Applications > Create App Integration
Select SAML 2.0
Paste the Entity ID and Assertion Consumer Service URL from FieldPulse
Set Name ID format to EmailAddress
Configure attribute statements (see table below)
Complete setup and copy the IdP metadata URL or XML

Azure Active Directory Configuration

In Azure Portal, navigate to Enterprise Applications > New Application
Select Create your own application and name it "FieldPulse"
Choose Integrate any other application you don't find in the gallery
In Single sign-on, select SAML
Enter the Entity ID and Reply URL from FieldPulse
Verify your domain and configure user assignments

Required Attribute Mapping

Regardless of your IdP, you must map these attributes:

FieldPulse Attribute	SAML Attribute Name	Description
Email	`email` or `mail`	Primary identifier; must match FieldPulse user email
First Name	`firstName` or `givenName`	Used for profile display
Last Name	`lastName` or `surname`	Used for profile display
Role (optional)	`fieldpulseRole`	Maps to FieldPulse role on initial provisioning

In my experience, the optional fieldpulseRole attribute is particularly useful if you're provisioning many users at once and want to automate role assignment. The value must exactly match an existing role name in your FieldPulse organization (case-sensitive).

Step 3: Complete FieldPulse Configuration

Return to Admin > Security > Single Sign-On in FieldPulse. You'll now need to provide your IdP metadata:

Paste the IdP metadata XML or provide the metadata URL
Verify that the Login URL and X.509 Certificate populate automatically
Review the Sign-out URL (optional — configures SLO if your IdP supports it)
Click Validate Configuration

FieldPulse will attempt a test authentication against your IdP. This validation checks certificate chain validity, endpoint reachability, and basic attribute parsing. It does not actually authenticate a user — you'll do that in the final step.

Step 4: Testing and Gradual Rollout

This is where, in my experience, many implementations encounter friction. I strongly recommend a phased approach rather than enabling SSO organization-wide immediately.

Enable for test users: Add one or two volunteer accounts to the SSO policy
Verify the authentication flow: Confirm that users can sign in, access work orders, and maintain session persistence
Check mobile app behavior: The FieldPulse mobile app supports SSO, but the initial authentication flow differs slightly from web
Document your rollback plan: Keep at least one non-SSO admin account available in case of configuration issues

Once you've validated the test group, you can enable Enforce SSO for all users. At this point, direct username/password authentication is disabled for all members except those explicitly excluded.

Mobile App Considerations

The FieldPulse mobile app handles SSO authentication through an embedded browser flow. When a user taps "Sign in with SSO," they're presented with your identity provider's login page. After successful authentication, control returns to the app automatically.

What I typically recommend for mobile deployments is confirming with your IT team that your IdP's mobile login experience is optimized. Some providers show a desktop-oriented login page in the embedded browser, which can be difficult to navigate on smaller screens. Most modern IdPs offer responsive authentication flows that adapt appropriately.

For additional mobile security configuration, see Enabling Two-Factor Authentication.

Troubleshooting Common Issues

"SAML Response Invalid" Error

This usually indicates a certificate mismatch or clock skew between your IdP and FieldPulse. Verify that:

Your IdP certificate has not expired
System clocks are synchronized (SAML is time-sensitive)
The Audience or Entity ID in the SAML response matches your FieldPulse configuration exactly

User Lands on FieldPulse Login Page Instead of IdP

Confirm that you have enabled Enforce SSO for all users. Until this toggle is active, FieldPulse presents both authentication options, and users may select the wrong one.

Role Assignment Not Working

The fieldpulseRole attribute is only evaluated during initial user provisioning. Existing users will not have their roles modified by SAML attributes. If you need to bulk-update roles, use the user management interface or contact FieldPulse support for assistance with a CSV-based role update.

Migrating from Another SSO Provider

If you're switching identity providers — for example, migrating from Okta to Azure AD — the transition requires careful timing. What I typically recommend is:

Configure the new IdP alongside the existing one (FieldPulse supports multiple IdP configurations)
Test thoroughly with a pilot group
During a maintenance window, disable the old IdP and enable the new one
Monitor authentication success rates and error logs for 24–48 hours

User accounts and historical data remain intact through this transition — only the authentication pathway changes.