Document email-based role mappings

deploy-manage/users-roles/cloud-organization/configure-saml-authentication.md

@@ -16,7 +16,7 @@
 
 When users log in to {{ecloud}} for the first time using SSO, they’re automatically added to your organization and their accounts are automatically provisioned.
 
-You can also enhance security by enforcing SSO authentication for members of your organization, and centrally manage role assignments by mapping IdP groups to {{ecloud}} roles.
+You can also enhance security by enforcing SSO authentication for members of your organization, and centrally manage role assignments by mapping IdP groups or user emails to {{ecloud}} roles.
 
 On this page, you'll learn the following:
 
@@ -25,8 +25,8 @@
 * The [risks and considerations for using SAML SSO](#ec_risks_and_considerations)
 * How to [implement and test SAML SSO](#set-up-sso)
 * How to [enforce SAML SSO](#enforce-sso) for your organization
-* How to [map groups returned by your IdP to {{ecloud}} roles](#role-mappings)
+* How to [map IdP groups and user emails to {{ecloud}} roles](#role-mappings)
 * How to [disable SAML SSO](#ec_disable_sso)
 
 For detailed examples of implementing SAML SSO using common identity providers, refer to the following topics:
 
@@ -115,7 +115,7 @@
 1. Use placeholder values for the assertion consumer service (ACS) and SP entity ID/audience. Those values will be provided by {{ecloud}} in a later step.
 2. Configure your application to send an `email` attribute statement with the email address of your organization members. The email should match the domain that you claimed.
 3. Optionally configure the application to send `firstName` and `lastName` attribute statements, which will be used to set the respective fields of the user’s {{ecloud}} account.
-4. If you’re planning to use role mappings, configure the application to send a `groups` attribute statement with the groups that you want to map to roles in {{ecloud}}.
+4. If you’re planning to use group-based role mappings, configure the application to send a `groups` attribute statement with the groups that you want to map to roles in {{ecloud}}.
 5. Note the SAML issuer and the SSO URL, which is the URL of the IdP where users will be redirected at login.
 6. Download the public certificate of the SAML 2 application.
 
@@ -213,7 +213,7 @@
 
 ## Role mappings [role-mappings]
 
-To automate [role](user-roles.md) assignments to your {{ecloud}} organization’s members, you can use role mappings. Role mappings map groups returned by your IdP in the `groups` SAML attribute to one or more {{ecloud}} roles. The mapping will be evaluated and the applicable roles will be assigned each time your organization’s members log into {{ecloud}} using SSO.
+To automate [role](user-roles.md) assignments to your {{ecloud}} organization’s members, you can use role mappings. Role mappings evaluate rules based on IdP groups or user email addresses and assign one or more {{ecloud}} roles when the rules match. Mappings are evaluated and roles are assigned each time your organization’s members log in to {{ecloud}} using SSO.
 
 To ensure continuous access and control over your organization settings, the first role mapping of your SAML SSO configuration must include the **Organization owner** role.
 
@@ -232,10 +232,13 @@
 4. Click to configure the roles that you want to assign to users who meet the mapping rules, click **Add roles** and then select the roles. For more information, refer to [*User roles and privileges*](user-roles.md).
 5. In the **Mapping rules** section, add rules for the role mapping:
 
-    1. Select **All are true** or **Any are true** to define how the rules are evaluated.
-    2. Add group name or names that the member must have in their SAML assertion to be assigned the role.
+    1. Select **All are true** or **Any are true** to define how multiple rules are evaluated. **All are true** requires every rule to match; **Any are true** requires at least one rule to match.
+    2. Add one or more rules. Two rule types are available:
 
-        Use the wildcard character `*` to specify group name patterns. Wildcards will match 0 or more characters.
+        * **Group**: Matches against groups returned in the `groups` SAML attribute from your IdP.
+        * **Email**: Matches against the user's email address from the `email` SAML attribute.
+
+        Use the wildcard character `*` to specify patterns. Wildcards match 0 or more characters.
 6. If your role mapping contains the Organization owner role, then click **Run test** to run role mapping verification.
 7. Click **Save** to save the role mapping.