Mapping Data

The SAML SSO functionality includes out-of-the-box functionality for mapping data from your identity provider (IdP) to WordPress-native data.

This mapping can be customized and extended to match the way your IdP stores data.

User details

By default, the following fields are mapped:

• user_login field (equivalent to a user slug): email SAML attribute
• user_email: email SAML attribute
• first_name: firstName SAML attribute
• last_name: lastName SAML attribute

This can be filtered via the wpsimplesaml_attribute_mapping filter, which receives an associative array mapping user properties to SAML attribute name. (Note: only these four fields are supported.)

For example, for Active Directory (AD), you may want to use the AD claims instead:

add_filter( 'wpsimplesaml_attribute_mapping', function() {
    return [
        'user_email' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
        'first_name' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname',
        'last_name'  => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname',
        'user_login' => 'http://schemas.microsoft.com/identity/claims/displayname',
    ];
} );

Advanced user details

Aside from the direct mapping of these, you can also filter the final data before it is sent to WordPress, via the wpsimplesaml_user_data filter.

This filter receives the full user data being passed to wp_insert_user. You can use it to apply any other customization (including adding metadata) to this user data. You'll also receive the SAML attributes.

/**
 * Filters user data before insertion to the database
 *
 * @param array $user_data  User data being passed to wp_insert_user()
 * @param array $attributes Attributes array coming from SAML Response object
 */
apply_filters( 'wpsimplesaml_user_data', $user_data, $attributes );

Unique user matching

By default, when SAML SSO attempts to find an existing user, it'll look for any user with a matching email address (as returned from your mapping code). You may want to change this to deduplicate them based on other user data instead.

The wpsimplesaml_match_user filter allows you to implement your own user matching code:

/**
 * Filters matched user, allows matching via other SAML attributes
 *
 * @param null|false|\WP_User $user       User object or false if not found
 * @param string              $email      Email from SAMLResponse
 * @param array               $attributes SAML Attributes parsed from SAMLResponse
 */
$user = apply_filters( 'wpsimplesaml_match_user', null, $email, $attributes );

For example, if you have multiple corporate domains and need to deduplicate them:

// Treat all users from corporate domains as equal.
add_filter( 'wpsimplesaml_match_user', function ( $user, $email ) {
    $email_parts = explode( '@', $email );
    $domains = [
        'example.com',
        'example.org',
        'example.net',
    ];
    foreach ( $aliases as $alias ) {
        $aliased_user = get_user_by( 'email', $email_parts[0] . '@' . $alias );
        if ( $aliased_user ) {
            return $aliased_user;
        }
    }

    return $user;
}, 10, 2 );

Role mapping

Roles can also be mapped; see the user roles documentation for more details.