User Groups
The User Group tab provides an option to update the user’s Atlassian application groups and create new groups on the Atlassian application based on the groups received in the response from OAuth/OpenID (OIDC) Provider.
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 a successful SSO.
- By mapping group attributes to application groups in the Manual Group Mapping section.
- By creating the OAuth/OpenID (OIDC) Provider groups received in response on the application’s side and then assigning the user to the created groups.
For simplicity, we are going to use ‘response’ at the place of ‘OAuth/OpenID (OIDC) response’ and ‘provider’ instead of ‘OAuth/OpenID (OIDC) Provider’ in this document.
At any SSO attempt, the provider sends the user group information in the response. Typically group attributes are sent in addition to profile attributes in the same response, but some providers send group attributes in a separate group response. Group attributes mainly contain group names and some attributes that describe various aspects of the group.
The group attribute names and values returned in the response can be viewed by clicking the Test Configuration button on the OAuth Configuration tab :
The attribute name which contains the names of the provider groups can be mapped to the application’s Group Attribute. Here in our example, the groups from the Provider are sent in an attribute named ‘groups’. This attribute will further be used during configuration.
The User Group tab has the following features
Default Group Configuration
This option is mainly used to give application access permissions to the users. This option allows the configuration of the groups that will be allocated to users at the time of SSO.
It is recommended that the groups with Access Permissions should be set as default groups. A user needs to be a member of at least one group with Access Permissions in order to access the application after signing in. Using this feature, any user signing in will be able to access the application directly without explicitly mapping the groups from a provider with the Access Permissions groups of the application.
Default Groups
The groups added to this field are assigned to users after successfully performing SSO. There needs to be at least one default group configured, and that group should ideally have Access Permissions (so that the user will be able to access the application after signing in). Based on the application being used, an application group with Access Permissions is already loaded by default in this field.
Assign Default Group To
This option can be used to set the type of users to whom Default groups will be assigned after SSO. Default groups can be assigned based on whether the user is an existing user or a new user. The possible settings for this option are:
- New User: If this option is set, then the default groups will be assigned to newly created users on performing SSO. The existing users will not be assigned to any of the default groups on performing SSO.
- All User: If this option is set, then default groups will be assigned to all users who successfully perform SSO. This means that both newly created users and existing users will be assigned to default groups at a successful SSO attempt. If a user is already a member of any of the default groups, they will continue to be a member.
- None: If this option is set, then default groups will not be assigned to any users. In this case, we recommend that the group mappings in the next section should contain at least one mapping for an application group with Access Permissions so that the user gets access to the application after signing in.
Group Mapping Configuration
Using options provided in this section, users are assigned to groups based on the groups received in the response.
The groups can be mapped using two methods, Manual Group Mapping or On-The-Fly Group Mapping. In Manual Group Mapping, an admin needs to map the group names received in the response to groups in the application. In On-The-Fly Group Mapping, the admin doesn’t need to map the groups, the response groups get automatically mapped to the application groups with the same name. If such groups with the same name don’t already exist then, the application creates groups with group names received in the response and assigns the user to these newly created groups.
There are some options that are common to both methods of group mapping. They are explained below :
Disable Group Mapping
Based on this option, the app decides whether to update the groups of an existing user or not whenever they attempt SSO. The groups of existing users will not be updated if this option is set. This option will not affect new users. The setting of this option does not affect the functionality of the default groups section.
If this option is set then the user’s groups will only be updated once, after the first successful SSO attempt. The groups of existing users will not be updated, irrespective of the groups received in the response.
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.
Group Attribute
At each SSO attempt, the provider sends a response that contains the user’s information and all the provider groups of the user. Fill this option with the attribute name from the response which has group names against it. The app will use the value in this field to find the user’s provider groups in the response. In the example provided below, the group attribute returned in the response is ‘groups’.
Manual Group Mapping
This method should be used if the group names used in the application are different from the group names in the provider. Here the user’s groups received in the response are mapped to groups in the local application.
For performing Manual Group mapping, a valid group attribute name from the response is needed. This attribute name is configured against 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 groups have been mapped. The setting for this option has been discussed in the next section. Then the mappings for the user’s provider groups to the groups in the application are added. The process for doing this has been discussed in the next section.
The app provides the following options in the Manual Group Mapping section :
Restrict User Creation Based on Group Mapping
Restrict the creation of new users based on whether any of the user’s OAuth/OpenID provider groups have been mapped to a group in the application in this section. This setting does not affect the existing users. The SSO is designed to create users in case a user is not found. This option gives the administrator more flexibility in terms of which users they want to get created. So this way not all users in the OAuth/OpenID Provider will get created, instead only the users in the groups which are meant for the Atlassian application will be created.
Add mappings
This section is used to manually map the user’s OAuth/OIDC provider groups to the Atlassian application groups. The app displays a list of 50 Atlassian applications groups, with an empty field next to each application group for the provider group to be mapped. A provider group must be entered next to an application group. If one of the mapped groups matches with groups received in the response, then the user will be assigned to the corresponding local group. You can add new group mappings by clicking the ‘+’ and ‘+10’ buttons provided. There is a ‘-‘ button provided next to each mapping to delete that mapping.
Consider an example where a user belongs to 3 groups named admin, developer, and tester in the OAuth/OIDC provider. In the Atlassian application, there are groups named ‘administrators’ and ‘local_developer’. The ‘administrators’ and ‘local_developer’ are mapped to ‘admin’ and ‘developer’ respectively.
At the time of SSO, if admin or developer groups are present in the response then the app will assign the respective mapped group from the Atlassian application to the user. In the example, at the time of SSO, the response will contain ‘admin’, ‘developer’ and ‘tester’ groups. The app will find that the ‘admin’ group has been mapped to the ‘administrators’ group and the ‘developer’ group has been mapped to the ‘local_developer’ group. So the ‘administrators’ and ‘local_developer’ groups will be assigned to the user.
Now as the user is part of both ‘administrators’ and ‘local_developer’ groups, the user has permissions of an administrator and a developer in the local Atlassian application.
Let’s consider a scenario in which the user has been removed from the group ‘admin’ in the provider. Now when the app receives a response, it finds only the group ‘developer’ in the group attribute. The app retains the user’s membership in the ‘local_developer’ group but removes the user from the ‘administrators’ group as the mapped provider group ‘admin’ was not found in the response. So the user no longer possesses the admin permissions in the Atlassian application as well.
The app removes users from application groups that have been mapped but the corresponding provider groups have not been received from the provider.
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 provider.
- The app needs to create new groups in the application with the same name as the groups in the provider. If such groups already exist in the application, then the app just assigns them to the user.
In this method, we require the Group Attribute field. The app will be able to
- Assign users to groups: The app assigns users to application groups with the same name as the groups in the response.
- Create new groups: If such groups don’t exist, the app creates the groups and assigns users.
- Remove users from groups: If a user is part of a group in the application and that group is not part of the response, the app removes the user from that group in the local application.
The app has settings to decide whether to create a group, update existing groups of users, etc. We will explore these settings in the following section.
The options provided in the On the Fly Group Mapping section are :
Create New Groups
If this option is enabled, the app will create new groups with the name of Provider groups in case no such group exists in the application. This is useful when you have added a new group in the Provider and want to provision users to that group just in time.
Let’s consider a situation where the admin, developer, and tester groups are received in the response from the Provider. Let’s say the application has a group named ‘admin’ and the Create New Groups option is enabled. At the time of SSO, the user will be assigned to the group ‘admin’ and since ‘developer’ and ‘tester’ are not present in the application, these groups will be created and then assigned to the user. But if this option is not checked, then groups ‘developer’ and ‘tester’ will not be created in the application. The user will be assigned only to the group ‘admin’.
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.
Keep Existing User Group
Based on this option, the app decides whether to keep the existing groups of a user or not. This option is checked by default. If this option is not checked then, at the time of SSO, the user is removed from all the local groups that are not present in the response.
Let’s say a user is a member of an application group ‘Local_Group’ and at the time of SSO, ‘admin’ and ‘developer’ groups are received in the response. Now if the Keep Existing User Groups option is not checked then, the user will be assigned to ‘admin’ and ‘developer’ groups and will be removed from ‘Local_Group’. But if the option is checked then the user will remain a member of ‘Local_Group’ and will be assigned to ‘admin’ and ‘developer’ groups as well.
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 app will remove the user from all the user’s groups that are not received in the response except the groups that are configured in this field.
If the user is a member of application groups Local_Group-1 and Local_Group-2, and Local_Group-1 is configured in this field. Let’s say the groups sent in the response are ‘admin’ and ‘developer’. Now the user will be assigned to groups ‘admin’ and ‘developer’ but will be removed from Local_Group-2. And as Local_Group-1 was added to Excluded groups field, its membership will be retained.
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 the access permissions of the directory. The recommended settings for each type of permission are :
- Read Only: The user groups cannot be updated in the directory. It is recommended to check the Disable Group Mapping option. If you’re using On-The-Fly group mapping, new groups won’t be created and only existing groups returned by the provider will be mapped. Make sure that all the groups in response are present in the Atlassian application or synced from the external directory, otherwise, the SSO will fail. The default groups won’t be assigned to any user.
- Read Only With Local Groups: Users can be added to or removed from local application groups. If you’re using On-The-Fly group mapping, the new groups will be created only if the application’s internal directory is the primary user directory. Local application groups can be assigned as default groups to all users. As all users are treated as existing users, it is recommended to Change the Assign Default Group To settings to All.
- Read/Write: The user groups can be updated. Users can be added to or removed from the application groups and new groups can also be created.