Atlassian SAML Handbook

User Groups

The User Groups tab provides a set of options that, if configured correctly, assign the user to groups in the application based on the user’s groups in the Identity Provider. The constraints for creation of new users can be set in this tab. With the options given in this tab a user can be assigned to application groups in a number of ways. User’s group membership can be assigned by default after successful SSO, by mapping group attributes to application groups in the Manual Group Mapping section and also by creating the Identity Provider groups received in SAML response on the application’s side and then assigning the user to the created groups.

The user’s group information is sent from the Identity Provider in the SAML response to any SSO attempt, similar to user profile attributes. The group attributes are sent in addition to profile attributes in the same SAML response. Unlike in the case of user profile attributes, there is no default group attribute that is always sent in a SAML response. The SAML response needs to be configured to contain the user’s group attributes. Typically group attributes contain just the names of the user’s group in the Identity Provider, but depending on the Identity Provider being used some of the attributes returned are used to describe various aspects of group.

Let’s consider a scenario where we use Okta as an Identity Provider. The SAML response from Okta does not contain any group attributes by default. In order to receive group attributes from Okta, the Group Attributes Statement section in the Configure SAML tab needs to be configured while creating a SAML application in Okta’s admin console :


The group attribute returned in the SAML response can be viewed by clicking the Test Configuration button in the Configure Identity Provider tab :


The User Group tab has the following features:

Disable User Creation


This option is used to restrict the creation of a new user in the application. Only users that are already existing the application’s user directory will be allowed to sign-in. Existing users are not affected by this option. If a new user attempts SSO and this option is checked, the user is redirected to a login page with the error “We couldn’t sign you in. Please contact your Administrator.” irrespective of the validity of the user’s credentials.

If new user creation needs to be disabled then the Disable User Creation option needs to be checked. Now SSO will not be successful unless the user’s profile already exists in the application. If an external directory is being used as a user store, then the behavior of this option depends on the access permissions that the application has for that directory. The recommended setting for this option for each type of permission is :

  • Read Only or Read Only With Local Groups  : New users cannot be created in the directory with either of these permissions, so the Disable User Creation option should be checked.
  • Read/Write : New user creation is possible with this permission, so there is no restriction on the setting for this option.

Default Group Configuration: If there are groups that every user needs to be assigned to after successfully performing SSO, then the options in this section should be configured. One or more groups need to be added in the default groups field, then the option to select which type of users should be assigned to these groups needs to be set. 

It is recommended that the groups with Global Permissions should be set as default groups. A user needs to be a member of at least one group with Global Permissions in order to access the application after signing in. Using this feature any user signing in will automatically be able to access the application without the need to explicitly map a group from Identity Provider to a group in the application with Global Permissions.

Default Groups


The default groups that users should be assigned to after successfully performing SSO are added in this field. There needs to be at least one default group configured, and that group should ideally have Global Permissions. Based on the application being used, an application group with Global Permissions is already loaded by default in this field. As mentioned earlier the default groups to be assigned should typically be groups with global permissions, but there is no such restriction. Any user not a member of at least one application group with Global Permissions will not be able to access the application content even after successfully performing SSO.

Assign Default Group To


This option can be used to set the type of users that will be assigned to the configured default groups after SSO. Default groups can be assigned based whether the user is an existing user or a new user. The possible settings for this option are :

  • New User: If the option is set to this value then the default groups will be assigned to a user only once, when the user successfully performs SSO for the first time. For any subsequent SSO operations performed, the user will not be assigned to any of the default groups.
  • All User: This value should be set when default groups should be assigned to every user after successfully performing SSO. This means that even existing users will be assigned to default groups each time they successfully attempt SSO. If they already have membership in any of the default groups, they retain this membership.
  • None: This option should be selected if default groups should not be assigned to any of the users after performing SSO. In this case, the group mappings done in the next section should contain at least one mapping for an application group with Global Permissions.  

Group Mapping Configuration


 The options provided in this section allow a user to be assigned to groups in the application based on the user’s groups in the Identity Provider. Here the user’s Identity Provider group information is received in an attribute value corresponding to an attribute name in the SAML response. As explained earlier, the SAML response has to be configured on the Identity Provider side to contain the user’s group attributes.

The groups can be mapped using two methods, Manual Group Mapping or On-The-Fly Group Mapping. In Manual Group Mapping, the group names received as an attribute value from the SAML response are mapped to groups in the application. In On-The-Fly Group Mapping the app creates groups with group names received in the SAML response, if such groups don’t already exist. The app then assigns the user to these created groups.

There are some options that are common to both methods of group mapping. They are explained below :

  • Disable Group Mapping: This option is used if users performing SSO should not be assigned to any of the mapped groups. The groups of existing users will not be affected and new users will not be assigned to any of the mapped groups.
    The setting of this option does not affect the functionality of the default groups section. For On-The-Fly group mapping, new groups are not created if this option is checked. If the app is using an external directory to manage users, the setting for this option depends on the directory permissions granted to the application : 

    • Read Only : The user’s groups cannot be updated with this permission, so this option should be checked.
    • Read Only With Local Groups or Read/Write : The user’s groups can be updated in this case, so there is no restriction on the setting for this option.
  • Group Attribute: This field will accept the attribute name that contains all the group names from the Identity Provider. The app will use the value in this field to find the user’s Identity Provider groups in the SAML response.

Manual Group Mapping


This method should be used if the group names used in the application are different from the group names in the Identity Provider. Here the user’s groups received in the response are mapped to groups in the Identity Provider. After a response is received from the Identity Provider, the app checks if any of the groups received from Identity Provider have been mapped to any groups in the Identity Provider. If it finds a mapping, then it assigns the user to the application group that has been mapped.

To map group attributes, first the name of the group attribute returned in the SAML response is needed. This attribute name should be added in the Group Attribute field discussed in the earlier section. The app provides an option to restrict the creation of new users based on whether any of the user’s groups have been mapped. The setting for this option has been discussed in the next section. Then the mappings for user’s Identity Provider groups to the groups in application are added. The process for doing this has been discussed in the next section.

Consider an example where a user belongs to group-A and group-B in the Identity Provider. These groups are mapped to group-1 and group-2 respectively. The SAML response returned by the Identity Provider will contain group-A and group-B in the group attribute. The app will read these group names and check if there are any mappings for any of them. It will find that group-A has been mapped to group-1 and group-B has been mapped to group-2. It will then assign the user to group-1 and group-2 in the application.

Let’s consider a scenario in which the user has been removed from group-B in the Identity Provider, but still a member of group-1 and group-2 in the application. Now when the app receives a SAML response, it finds only group-A in the group attribute. The app retains the user’s membership in group-1, but removes the user from group-2 as the mapped Identity Provider group group-B was not found. The app will remove users from application groups that have been mapped but the corresponding Identity Provider groups have not been received from the Identity Provider. Of course this is only possible when the Disable Group Mapping option has not been checked. If this option is checked, then the user will neither be assigned to new groups nor removed from existing groups.

The app provides the following options in the Manual Group Mapping section :

  • Restrict User Creation Based on Group Mapping: This option can be used to restrict the creation of new users based on whether any of the user’s Identity Provider groups have been mapped to groups in the application. A new user will be created only if at least one of the user’s Identity Provider groups has been mapped to a group in the application.
  • The last section can be used for Manual Group Mapping to add mappings from the user’s Identity Provider groups to the application groups. The app displays a list of all the applications groups, with an empty field next to each application group for the Identity Provider group to be mapped. An Identity Provider group must be entered next to an application group. If one of the values in the Group Attribute is that Identity Provider group, then the user will be assigned to the corresponding application group. There is a button provided next to each mapping to delete that mapping. The app allows the addition of extra mapping fields, either one at a time or 10 at a time using the buttons provided.

 

On-The-Fly Group Mapping


This method of group mapping is recommended for either of the following scenarios:

  • The group names in the application are the same as the group names in the Identity Provider.
  • The app needs to create new groups in the application with the same name as the groups in the Identity Provider. If some such groups already exist in the application, then the app just assigns the user to them.

In order to use this method, then the Group Attribute field is required. The app will assign users to groups or create new groups based on this field’s value. The user will be assigned to the application groups that have the same names as the groups in the response. If such groups don’t exist, then the groups are created. The app provides an option to disable the creation of new groups. The app provides an option to choose whether the existing group memberships of a user will be retained. Both these options are discussed in detail in the next section.

Let’s consider a situation where the groups returned in the response are group-A, group-B and group-C. Let’s say the application already has a group named group-C. After the user performs SSO, the user will be assigned to group-C. Since there are no groups named group-A and group-B in the application, these groups are created. After this the user is assigned to these created groups. The effect of the options in this section on the flow of this method of group mapping are explained in the next section.

The options provided in this section are :

  • Create New Groups: This option can be used to restrict the creation of groups in the application. If there is a group in the response that does not have a corresponding group in the application, then a new group for that group name will not be created. Let’s consider the example used earlier. If this option is not checked, then group-A and group-B will not be created in the application. The user will be assigned to only group-C.
  • Keep Existing User Groups: The app provides an option to retain the existing group memberships of a user. This option is checked by default.  Let’s say the user signing in is a member of an application group appGroup-1. If the groups received in the response are group-A and group-B, then the user will be assigned to these groups without being removed from appGroup-1. If this option is unchecked, then the Exclude Groups field is displayed.
  • Exclude Group: This field can be used only when the Keep Existing User Groups option is unchecked. This field is used to choose which existing group memberships should be retained. The user will be removed from all the existing groups not added this field. If the user is a member of application groups appGroup-1 and appGroup-2, and appGroup-1 is added in this field after unchecking Keep Existing User Groups. Let’s say the groups sent in the response are group-A and group-B. Now the user will be assigned to group-A and group-B, but will be removed from appGroup-2.  

Group mapping considerations if an external user directory is being used


In the case of an external directory being used for users, group mapping functionality depends on access permissions of the directory. The recommended settings for each type of permission are :

  • Read Only : The user’s groups cannot be updated in the directory. This means that the user cannot be assigned to both default groups and the mapped groups. This option should be ch.
  • Read Only With Local Groups : The user can be assigned to application groups, but not directory groups. Since all users in a directory are existing users, the Assign Default Groups To option should be set to All Users. If On-The-Fly group mapping is being used, then new groups will be created only if the application’s internal directory is the primary user directory. Typically the primary user directory is the first directory in the list of directories.
  • Read/Write : This permission allows the user to be assigned to any of the mapped or default groups. Here all users will be treated as existing users, so Assign Default Group To option should be set to All Users. If On-The-Fly group mapping is being used, then new groups will only be created in the primary user directory.