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' => '',
		'first_name' => '',
		'last_name'  => '',
		'user_login' => '',
} );

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 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 = [
	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.