The intended audience for this article is Technical Agent Admins with SSO.

To complete this setup step, you'll need administrative access to your identity provider.

The purpose of this step is to provide more information about the required mappings for an SSO integration to work. WorkOS will prompt you to map the following Wunderite user attributes from your IdP:

idpId: should map to the attribute within the IdP that specifies the user’s ID.
email: should map to the attribute within the IdP that specifies the user’s email address.
firstName: should map to the attribute detailing the user’s first name.
lastName: should map to the attribute detailing the user’s last name.
segment_names: should map to the attribute that sends the names of the segment groups each user belongs to. This is only required for Wunderite teams with segments enabled.
If segments already exist in Wunderite, or are pulling from AMS360 into Wunderite, the names passed from the IdP must be exact matches to the segment name(s) in Wunderite.
groups: should map to the attribute that sends the IDs of each user's groups used for role assignment. Any information intended to be used to determine the user's role in Wunderite must be sent to WorkOS as a set of IDs from the IdP under groups. These IDs then get mapped to our WorkOS roles in the 'Groups and role assignments' section. If no groups are found or groups is empty, the user will be assigned the Member role by default.
When reviewing attributes, groups will not appear within the mappings. The groups attribute is used later in the process to configure role mappings in WorkOS.

Mapping Support for Common IdPs

Below are additional setup notes for IdPs commonly used by Wunderite customers.

Auth0

Any roles and segments pulled from Auth0 need to be sent via a custom action by navigating to Actions, then selecting Library and finally selecting Custom Action. For more details, see Auth0’s documentation. The action then needs to be added as a Post Login trigger (Actions → Triggers → post-login).

For example:

/** Action for passing roles into "groups" and "segments" and ensuring we have names **/
exports.onExecutePostLogin = async (event, api) => {
    // Ensure we always have a given and family name
    // Auth0 doesn't create those fields if a user is created unless it's done by signing in with Google
    const name = event.user.name || '';
    const nameParts = name.trim().split(/\s+/);

    const givenName = event.user.given_name || nameParts[0] || 'GivenName';
    const familyName = event.user.family_name || nameParts.slice(1).join(' ') || 'FamilyName';
    
    api.samlResponse.setAttribute('given_name', givenName);
    api.samlResponse.setAttribute('family_name', familyName);

    // Process out roles and segments
    const roles = event.authorization?.roles || [];
    const groups = roles.filter(role => role.startsWith('Wunderite'));
    const segments = roles.filter(role =>
        role.startsWith('Status Quo') || role === 'Default Segment'
    );

    api.samlResponse.setAttribute('groups', groups);
    api.samlResponse.setAttribute('segments', segments);
};

Okta

Skipping Custom Attributes

The WorkOS guide will step the user through creating custom attributes. If the agency doesn’t want to create custom attributes, Attribute Statements can be created instead. To configure this in Okta navigate to Applications → [App name] → Sign On → Edit SAML Settings. Specific expressions for handling groups and segments will depend on how the agency is currently handling that data in their IdP.

Legacy Configuration Segment Regex

If using the legacy configuration and setting up segments with a common prefix, use the regex Matches regex ^(Default Segment|{COMMON PREFIX}.*)$

Entra ID

Once the custom Enterprise App is created and connected to WorkOS, ensure the following:

For segment-enabled teams, there should be an IdP group for each segment that needs to be represented in Wunderite. If segments already exist in Wunderite, the IdP group name must exactly match the Wunderite name so the initial sync can correctly associate the IdP group with the existing Wunderite segment.
For each group name used for Admin and Agent roles, set up the group to be passed in Attributes & Claims.
1. Add a New Claim for groups with the claim name segments. Populate this claim with the group values that match the segments configured within Wunderite. Values must match exactly.
2. Add New Claim for the admin role with the claim name groups. Populate this claim with the Wunderite Admin group value, and provide the exact name used so Wunderite can configure the WorkOS Groups and role assignments setting for the admin role.

Continue to Step 3: Configure Directory Sync with Your Identity Provider

Step 2: Map Identity Provider Attributes, Roles, and Segments