SAML SSO Integration

Overview

Configure Workvivo as a Service Provider (SP) in your identity provider to enable single sign-on for all employees using your existing IdP (e.g. Okta, Azure AD, OneLogin, Ping Identity).

Managing separate credentials for every enterprise application creates friction for employees and risk for security teams. Employees forget passwords, get locked out, and resort to insecure workarounds. Security teams lose visibility into who's accessing what, and offboarding becomes a race to disable accounts across dozens of systems before a departing employee retains access.

SAML SSO eliminates these problems for Workvivo. By configuring Workvivo as a Service Provider in your existing identity provider, employees authenticate through your IdP and access Workvivo without a separate Workvivo-managed password. When an employee is deactivated in your IdP, future SSO authentication attempts are blocked by the IdP. Pair SAML with SCIM or user deactivation in Workvivo when you also need automated account lifecycle management and access revocation inside Workvivo.

Workvivo supports SAML 2.0, the industry standard for enterprise single sign-on, and is compatible with all major identity providers.

Value & Benefits

Eliminate password fatigue for employees. Employees access Workvivo using the same credentials they use for all other enterprise applications - no additional password to remember or manage.

Centralise access control. All authentication flows through your IdP, giving security teams a single point of control for granting, monitoring, and revoking Workvivo access.

Strengthen security posture. Leverage your IdP's existing security policies (MFA, conditional access, device trust, IP restrictions) for Workvivo access without configuring them separately.

Simplify offboarding. When an employee is deactivated in your IdP, they lose the ability to authenticate through SAML. Use SCIM provisioning or Workvivo user deactivation alongside SAML when you need automated Workvivo account updates as part of the same offboarding process.

Reduce IT support burden. Fewer password reset requests, fewer lockout tickets, and fewer "I can't log in" queries, because employees authenticate through the system they already know.

Applications

Enterprise-wide SSO deployment. Configure Workvivo as a SAML SP in your primary IdP (Okta, Azure AD, OneLogin, Ping Identity) so all employees access Workvivo through your standard authentication flow.

MFA enforcement. Leverage your IdP's multi-factor authentication policies to require MFA for Workvivo access, without configuring MFA separately within Workvivo.

Conditional access policies. Use your IdP's conditional access rules to restrict Workvivo access based on device compliance, network location, or risk level, ensuring only trusted devices and locations can reach the platform.

Frontline worker authentication. Enable SSO for frontline and deskless workers using shared device flows or simplified authentication methods supported by your IdP (e.g., certificate-based auth, QR code login).

Security monitoring and audit. Use the Workvivo SIEM API to monitor SAML authentication events (successful logins, failed attempts) and feed them into your security operations platform for anomaly detection.

Technical Details

SAML SSO is configured through the Workvivo Admin Hub. No API development or custom code is required for the SSO setup itself.

Setup Steps

1. Navigate to Admin Hub > Provisioning > Authentication and System Settings.
2. In your IdP (Okta, Microsoft Entra ID, OneLogin, Ping Identity, etc.), create a new SAML application for Workvivo.
3. Configure the Workvivo SP metadata in your IdP. For a standard organisation setup, the SP metadata is available at https://{your-workvivo-domain}/saml/metadata; the ACS URL is https://{your-workvivo-domain}/saml/acs; and the Single Logout URL, if required by your IdP, is https://{your-workvivo-domain}/saml/sls.
4. Configure the IdP NameID to send the Workvivo user identifier. By default, Workvivo matches the SAML NameID to the user's email address, although your Workvivo configuration can be set to match another identifier.
5. Copy the IdP values into Workvivo's authentication settings: SAML IDP Entity ID URL, SAML Single Sign On Service URL, optional SAML Single Logout Service URL, and SAML X509 Certificate.
6. Set Authentication Mode to SAML or Mixed. Use Mixed when some users still need Workvivo-managed password login.
7. Test the connection with a pilot user before enabling SAML for a wider audience.

For multi-SAML configurations, Workvivo generates per-configuration URLs that include a settings identifier, such as https://{your-workvivo-domain}/saml/metadata-multi/{sid} and https://{your-workvivo-domain}/saml/acs-multi/{sid}. Use the standard URLs above only for the organisation-level SAML configuration.

SAML Attributes

For normal SAML login, Workvivo uses the assertion NameID to find the Workvivo user. The default matching field is the user's email address.

If SAML Just-in-Time (JIT) provisioning is enabled for your organisation, Workvivo also expects the following attributes before it can create a missing user:

Optional JIT attributes include HireDate, DirectDial, and MobileNumber. ProfilePhotoURL may be included in the SAML assertion, but the current login flow does not apply it to the created Workvivo user.

Complementary API: SIEM Authentication Events

Before using the complementary SIEM API, complete Quick Start to create an app and API key and find your Base URL and Workvivo-Id.

While SSO configuration is handled through the Admin Hub, the SIEM API lets you programmatically monitor authentication events - including SAML logins and failures. This is useful for security monitoring, anomaly detection, and compliance reporting.

curl -X GET "https://api.workvivo.com/v1/siem/{fromEpoch}/{toEpoch}" \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json"

curl -X GET "https://api.workvivo.com/v1/siem/users/{userID}/events/{fromEpoch}/{toEpoch}" \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json"

{
    "data": [
        {
            "id": 60365,
            "created_at_timestamp": 1756217495,
            "created_at": "2025-08-26T14:11:35Z",
            "workvivo_id": 3,
            "user_email": "ja@workvivo.com",
            "event": "loginSaml",
            "ip_address": "172.2.2.2",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
            "note": "n/a"
        }
    ],
    "status": "success",
    "meta": {
        "range": [
            {
                "from_epoch_timestamp": 1756216800,
                "from_epoch_datetime": "Tue, Aug 26, 2025 2:00 PM",
                "to_epoch_timestamp": 1756220400,
                "to_epoch_date": "Tue, Aug 26, 2025 3:00 PM"
            }
        ]
    }
}

The fromEpoch and toEpoch parameters are Unix timestamps. The maximum duration for the organisation-wide SIEM endpoint is one hour. If the timestamps are omitted from the organisation-wide endpoint, the API returns events for the last five minutes. For user-specific requests, the maximum duration is 31 days; if the timestamps are omitted from the user-specific endpoint, the API returns events for that user for the last 7 days.

SAML-Related SIEM Events

JavaScript Integration Example

Load SAML authentication events from the SIEM endpoint and alert when repeated failures exceed your chosen threshold.

const apiUrl = 'https://api.workvivo.com/v1';
const headers = {
    Authorization: `Bearer ${process.env.WORKVIVO_TOKEN}`,
    'Workvivo-Id': process.env.WORKVIVO_ORG_ID,
    Accept: 'application/json',
};

export async function monitorSamlLogins() {
    const toEpoch = Math.floor(Date.now() / 1000);
    const fromEpoch = toEpoch - 60 * 60;
    const response = await fetch(`${apiUrl}/siem/${fromEpoch}/${toEpoch}`, {
        headers,
    });

    if (!response.ok) {
        throw new Error(`SIEM request failed: ${response.status}`);
    }

    const result = await response.json();
    const failuresByUser = new Map();

    for (const event of result.data ?? []) {
        if (event.event !== 'loginSamlFailed') {
            continue;
        }

        const user = event.workvivo_id ?? event.user_email ?? 'unknown';
        failuresByUser.set(user, (failuresByUser.get(user) ?? 0) + 1);
    }

    for (const [user, failures] of failuresByUser) {
        if (failures >= 5) {
            await sendSecurityAlert({ user, failures, fromEpoch, toEpoch });
        }
    }
}

async function sendSecurityAlert(details) {
    // Send the alert to your SIEM, security operations, or paging system.
}