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: Send the identity provider group IDs used for role assignment. Wunderite maps these groups to the Admin or Member role in WorkOS. If a user does not belong to a mapped role group, Wunderite assigns the Member role by default.
The groups attribute does not appear in the attribute-mapping screen. Role mappings are configured separately under Groups and role assignments in WorkOS.
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