Merge pull request #106279 from paulgarn/grpclaimsupdate

Update group claims doc for Application Assigned Groups preview

Author: megvanhuygen

articles/active-directory/hybrid/how-to-connect-fed-group-claims.md

@@ -25,14 +25,14 @@ Azure Active Directory can provide a users group membership information in token
 > There are a number of caveats to note for this preview functionality:
 >
 >- Support for use of sAMAccountName and security identifier (SID) attributes synced from on-premises is designed to enable moving existing applications from AD FS and other identity providers. Groups managed in Azure AD do not contain the attributes necessary to emit these claims.
->- In larger organizations the number of groups a user is a member of may exceed the limit that Azure Active Directory will add to a token. 150 groups for a SAML token, and 200 for a JWT. This can lead to unpredictable results. If this is a potential issue we recommend testing and if necessary waiting until we add enhancements to allow you to restrict the claims to the relevant groups for the application.  
+>- In larger organizations the number of groups a user is a member of may exceed the limit that Azure Active Directory will add to a token. 150 groups for a SAML token, and 200 for a JWT. This can lead to unpredictable results. If your users have large numbers of group memberships, we recommend using the option to restrict the groups emitted in claims to the relevant groups for the application.  
 >- For new application development, or in cases where the application can be configured for it, and where nested group support isn't required, we recommend that in-app authorization is based on application roles rather than groups.  This limits the amount of infomation that needs to go into the token, is more secure, and separates user assignment from app configuration.
 
 ## Group claims for applications migrating from AD FS and other identity providers
 
-Many applications that are configured to authenticate with AD FS rely on group membership information in the form of Windows AD group attributes.   These attributes are the group sAMAccountName, which may be qualified by-domain name, or the Windows Group Security Identifier (GroupSID).  When the application is federated with AD FS, AD FS uses the TokenGroups function to retrieve the group memberships for the user.
+Many applications configured to authenticate with AD FS rely on group membership information in the form of Windows AD group attributes.   These attributes are the group sAMAccountName, which may be qualified by-domain name, or the Windows Group Security Identifier (GroupSID).  When the application is federated with AD FS, AD FS uses the TokenGroups function to retrieve the group memberships for the user.
 
-To match the token an app would receive from AD FS, group and role claims may be emitted containing the domain qualified sAMAccountName rather than the group's Azure Active Directory objectID.
+An app that has been moved from AD FS needs claims in the same format. Group and role claims may be emitted from Azure Active Directory containing the domain qualified sAMAccountName or the GroupSID synced from Active Directory rather than the group's Azure Active Directory objectID.
 
 The supported formats for group claims are:
 
@@ -47,31 +47,33 @@ The supported formats for group claims are:
 
 ## Options for applications to consume group information
 
-One way for applications to obtain group information is to call the Graph groups endpoint in order to retrieve the group membership for the authenticated user. This call ensures that all the groups a user is a member of are available even when there are a large number of groups involved and the application needs to enumerate all groups the user is a member of.  Group enumeration is then independent of token size limitations.
+Applications can call the MS Graph groups endpoint to obtain group information for the authenticated user. This call ensures that all the groups a user is a member of are available even when there are a large number of groups involved.  Group enumeration is then independent of token size limitations.
 
-However, if an existing application already expects to consume group information via claims in the token it receives, Azure Active Directory can be configured with a number of different claims options to fit the needs of the application.  Consider the following options:
+However, if an existing application expects to consume group information via claims, Azure Active Directory can be configured with a number of different claims formats.  Consider the following options:
 
-- When using group membership for in-application authorization purposes it’s preferable to use the Group ObjectID, which is immutable and unique in Azure Active Directory and available for all groups.
-- If using the on-premises group sAMAccountName for authorization, use domain qualified names;  there’s less chance of situations arising were names clash. sAMAccountName on its own may be unique within an Active Directory domain, but if more than one Active Directory domain is synchronized with an Azure Active Directory tenant there is a possibility for more than one group to have the same name.
+- When using group membership for in-application authorization purposes it is preferable to use the Group ObjectID. The Group ObjectID is immutable and unique in Azure Active Directory and available for all groups.
+- If using the on-premises group sAMAccountName for authorization, use domain qualified names;  there’s less chance of names clashing. sAMAccountName may be unique within an Active Directory domain, but if more than one Active Directory domain is synchronized with an Azure Active Directory tenant there is a possibility for more than one group to have the same name.
 - Consider using [Application Roles](../../active-directory/develop/howto-add-app-roles-in-azure-ad-apps.md) to provide a layer of indirection between the group membership and the application.   The application then makes internal authorization decisions based on role clams in the token.
-- If the application is configured to get group attributes that are synced from Active Directory and a Group doesn't contain those attributes it won't be included in the claims.
-- Group claims in tokens include nested groups.   If a user is a member of GroupB and GroupB is a member of GroupA, then the group claims for the user will contain both GroupA and GroupB. For organizations with heavy usage of nested groups and users with large numbers of group memberships the number of groups listed in the token can grow the token size.   Azure Active Directory limits the number of groups it will emit in a token to 150 for SAML assertions, and 200 for JWT to prevent tokens getting too large.  If a user is a member of a larger number of groups than the limit, the groups are emitted along with a link to the Graph endpoint to obtain group information.
+- If the application is configured to get group attributes that are synced from Active Directory and a Group doesn't contain those attributes, it won't be included in the claims.
+- Group claims in tokens include nested groups except when using the option to restrict the group claims to groups assigned to the application.  If a user is a member of GroupB and GroupB is a member of GroupA, then the group claims for the user will contain both GroupA and GroupB. When an organization's users have large numbers of group memberships, the number of groups listed in the token can grow the token size.  Azure Active Directory limits the number of groups it will emit in a token to 150 for SAML assertions, and 200 for JWT.  If a user is a member of a larger number of groups, the groups are omitted and a link to the Graph endpoint to obtain group information is included instead.
 
-> Prerequisites for using Group attributes synchronized from Active Directory:   The groups must be synchronized from Active Directory using Azure AD Connect.
+## Prerequisites for using Group attributes synchronized from Active Directory
+
+Group membership claims can be emitted in tokens for any group if you use the ObjectId format. To use group claims in formats other than the group ObjectId, the groups must be synchronized from Active Directory using Azure AD Connect.
 
 There are two steps to configuring Azure Active Directory to emit group names for Active Directory Groups.
 
 1. **Synchronize group names from Active Directory**
-Before Azure Active Directory can emit the group names or on premises group SID in group or role claims, the required attributes need to be synchronized from Active Directory.  You must be running Azure AD Connect version 1.2.70 or later.   Prior to version 1.2.70 Azure AD Connect will synchronize the group objects from Active Directory, but doesn’t include the required group name attributes by default.  You should upgrade to the current version.
+Before Azure Active Directory can emit the group names or on premises group SID in group or role claims, the required attributes need to be synchronized from Active Directory.  You must be running Azure AD Connect version 1.2.70 or later.   Earlier versions of Azure AD Connect than 1.2.70 will synchronize the group objects from Active Directory, but will not include the required group name attributes.  Upgrade to the current version.
 
 2. **Configure the application registration in Azure Active Directory to include group claims in tokens**
-Group claims can be configured either in the Enterprise Applications section of the portal for a Gallery or Non-Gallery SAML SSO application, or using the Application Manifest in the Application Registrations section.  To configure group claims in the application manifest see “Configuring the Azure Active Directory Application Registration for group attributes” below.
+Group claims can be configured in the Enterprise Applications section of the portal, or using the Application Manifest in the Application Registrations section.  To configure group claims in the application manifest see “Configuring the Azure Active Directory Application Registration for group attributes” below.
 
-## Configure group claims for SAML applications using SSO configuration
+## Add group claims to tokens for SAML applications using SSO configuration
 
-To configure Group Claims for a Gallery or Non-Gallery SAML application, open Enterprise Applications, click on the application in the list and select Single Sign On configuration.
+To configure Group Claims for a Gallery or Non-Gallery SAML application, open **Enterprise Applications**, click on the application in the list, select **Single Sign On configuration**, and then select **User Attributes & Claims**.
 
-Select the edit icon next to "Groups returned in token"
+Click on **Add a group claim**  
 
 ![claims UI](media/how-to-connect-fed-group-claims/group-claims-ui-1.png)
 
@@ -81,19 +83,29 @@ Use the radio buttons to select which groups should be included in the token
 
 | Selection | Description |
 |----------|-------------|
-| **All groups** | Emits security groups and distribution lists.   It also causes Directory Roles the user is assigned to be emitted in a 'wids' claim, and any application roles the user is assigned to be emitted in the roles claim. |
+| **All groups** | Emits security groups and distribution lists and roles.  |
 | **Security groups** | Emits security groups the user is a member of in the groups claim |
-| **Distribution lists** | Emits distribution lists the user is a member of |
-| **Directory roles** | If the user is assigned directory roles they are emitted as a 'wids' claim (groups claim won't be emitted) |
+| **Directory roles** | If the user is assigned directory roles, they are emitted as a 'wids' claim (groups claim won't be emitted) |
+| **Groups assigned to the application** | Emits only the groups that are explicitly assigned to the application and the user is a member of |
 
 For example, to emit all the Security Groups the user is a member of, select Security Groups
 
 ![claims UI](media/how-to-connect-fed-group-claims/group-claims-ui-3.png)
 
-To emit groups using Active Directory attributes synced from Active Directory instead of Azure AD objectIDs select the required format from the drop-down.  This replaces the object ID in the claims with string values containing group names.   Only groups synchronized from Active Directory will be included in the claims.
+To emit groups using Active Directory attributes synced from Active Directory instead of Azure AD objectIDs select the required format from the drop-down. Only groups synchronized from Active Directory will be included in the claims.
 
 ![claims UI](media/how-to-connect-fed-group-claims/group-claims-ui-4.png)
 
+To emit only groups assigned to the application, select **Groups Assigned to the application**
+
+![claims UI](media/how-to-connect-fed-group-claims/group-claims-ui-4-1.png)
+
+Groups assigned to the application will be included in the token.  Other groups the user is a member of will be omitted.  With this option nested groups are not included and the user must be a direct member of the group assigned to the application.
+
+To change the groups assigned to the application, select the application from the **Enterprise Applications** list and then click **Users and Groups** from the application’s left-hand navigation menu.
+
+See the document [Methods for assigning users and groups to an app](../../active-directory/manage-apps/methods-for-assigning-users-and-groups.md#assign-groups) for details of managing group assignment to applications.
+
 ### Advanced options
 
 The way group claims are emitted can be modified by the settings under Advanced options
@@ -109,6 +121,12 @@ Some applications require the group membership information to appear in the 'rol
 > [!NOTE]
 > If the option to emit group data as roles is used, only groups will appear in the role claim.  Any Application Roles the user is assigned will not appear in the role claim.
 
+### Edit the group claims configuration
+
+Once a group claim configuration has been added to the User Attributes & Claims configuration, the option to add a group claim will be greyed out.  To change the group claim configuration click on the group claim in the **Additional claims** list.
+
+![claims UI](media/how-to-connect-fed-group-claims/group-claims-ui-7.png)
+
 ## Configure the Azure AD Application Registration for group attributes
 
 Group claims can also be configured in the [Optional Claims](../../active-directory/develop/active-directory-optional-claims.md) section of the [Application Manifest](../../active-directory/develop/reference-app-manifest.md).
@@ -117,12 +135,14 @@ Group claims can also be configured in the [Optional Claims](../../active-direct
 
 2. Enable group membership claims by changing the groupMembershipClaim
 
-   The valid values are:
+Valid values are:
 
-   - "All"
-   - "SecurityGroup"
-   - "DistributionList"
-   - "DirectoryRole"
+| Selection | Description |
+|----------|-------------|
+| **"All"** | Emits security groups, distribution lists and roles |
+| **"SecurityGroup"** | Emits security groups the user is a member of in the groups claim |
+| **"DirectoryRole** | If the user is assigned directory roles, they are emitted as a 'wids' claim (groups claim won't be emitted) |
+| **"ApplicationGroup** | Emits only the groups that are explicitly assigned to the application and the user is a member of |
 
    For example:
 
@@ -134,7 +154,7 @@ Group claims can also be configured in the [Optional Claims](../../active-direct
 
 3. Set group name configuration optional claims.
 
-   If you want the groups in the token to contain the on premises AD group attributes in the optional claims section specify which token type optional claim should be applied to, the name of optional claim requested and any additional properties desired.  Multiple token types can be listed:
+   If you want the groups in the token to contain the on premises AD group attributes, specify which token type optional claim should be applied to in the optional claims section.  Multiple token types can be listed:
 
    - idToken for the OIDC ID token
    - accessToken for the OAuth/OIDC access token
@@ -199,4 +219,6 @@ To emit group names to be returned in netbiosDomain\samAccountName format as the
 
 ## Next steps
 
-[What is hybrid identity?](whatis-hybrid-identity.md)
+[Methods for assigning users and groups to an app](../../active-directory/manage-apps/methods-for-assigning-users-and-groups.md#assign-groups)
+
+[Configure role claims](../../active-directory/develop/active-directory-enterprise-app-role-management.md)