User groups

Overview

The user groups settings allow you to keep the application groups of your users in sync with IdP groups and manage permissions and access from the IdP. To do this, you’ll need an attribute in the SAML assertion which has the names or IDs of user groups on the IdP. You can map these groups against the local groups in your Atlassian application.

For example, If you map the groups in the app like this:

SAML Single Sign On overview

The users belonging to the IdP group IdP_admins will be added to the group jira-administrators after SSO, IdP_users to the jira-software-users group, and so on.

This can also be used to revoke access. for example, if an employee leaves the company and removed from the IdP_users group on the IdP, he’ll be removed from the jira-software-users group during SSO and will lose access to Jira.

User Group Mapping is useful when:

  1. Managing groups and permissions related to those groups at IdP only
  2. Removing user access from the application as soon as it’s removed from the IdP.
  3. You have project access based on the groups and want to change the project of an employee by simply changing his group on the IdP.

How to configure group mapping

Follow these steps to reach these settings:

  1. Click on the Configure button present below the app name on the Manage Apps page.
  2. Click on Edit dropdown under the Actions column.
  3. Select User Groups.

Here are the options available to manage user groups:

Default Group Configurations

SAML Single Sign On Group configuration

Default group configuration gives you an option to choose a set of groups all users should be assigned while performing SSO.

1. Default Group

A set of groups that will be assigned after SSO to the type of users selected in Assign Default Group To option. This is useful when you want to assign application access to all the users.

2. Assign Default Group To

You can select the type of users to whom the default groups will be assigned after SSO:

  1. New Users: The default groups will be assigned only to users performing SSO for the first time

  2. All Users: The default groups will be assigned to each user after SSO every time. This means even if the user is removed from all the groups, the default groups will be assigned to them after SSO. This is useful if you start using SSO after you have some existing users in the system

  3. None: The default groups won’t be assigned after SSO.

Group Mapping

Mapping IdP groups to application groups allows you to assign and update user groups and permissions whenever their groups change on the IdP. For example, if a user is part of the administrators group on IdP, he can be assigned admin permission after SSO through mapping. If the user is removed from the administrators group on IdP in the future, he’ll be automatically removed from the application admin group after SSO.

Groups can be mapped in two ways, Manually or On-The-Fly

Manual Group Mapping is useful when your IdP group names and local application group names are different. In this case, you have to map each IdP group to the application group manually.

On-The-Fly Group Mapping can be used when your IdP group names and local application group names are an exact match. In this case, the app detects the groups and add users to those groups automatically.

1. Manual Group Mapping

SAML Single Sign On Mannual group mapping

Manual Group Mapping is useful when you want to manage groups from the IdP but the names of application groups and IdP groups are different. For example, if the name of the group in IdP is IdP_users but the name of a similar group in the application is jira-software-users. In such cases, you have to manually map each IdP group to the application group.

1. Disable Group Mapping

Selecting this option will disable group mapping for existing users, which means the existing application users won’t be added or removed from any groups during SSO. This option is enabled by default. It is useful when you just want to perform SSO for your users and not update their groups. This option should be kept checked if your users are part of the Read-Only internal directory.

2. Group Attribute

This is the name of the attribute in SAML assertion which has names of all the groups returned by IdP during SSO. To get this attribute, go to the SSO Endpoints menu and perform Test Configuration. On the resulting window, look for the attribute name against your groups.

Note: The group attribute is case sensitive

3. Restrict User Creation on Group Mapping

If this option is checked, the app will create new users after SSO only if one of their IdP groups are mapped to an application group in the app. Otherwise, the user won’t be created.

4. Group Mapping

Here, you can map IdP’s groups to the Atlassian application’s local groups. The IdP group names are case sensitive and should exactly match the group names received from the IdP. To check the group names, go to the SSO Endpoints menu and perform Test Configuration. On the resulting window, look for the values against your group attribute name.

2. On-The-Fly Group Mapping

SAML Single Sign On On fly group mapping

On-The-Fly Group Mapping is used when the name of groups on your IdP and SP are the same. In such cases, you don’t need to map each IdP group to the Atlassian application’s group individually. The app finds the group matching the IdP group in the application and assigns users to that group.

1. Create New Groups

If this option is enabled, the app will create new groups with the name of IdP groups in case no such group exists in the application. This is useful when you have added a new group in the IdP and want to provision users to that group just in time.

2. Keep Existing User Groups

This option makes sure that the user is added to new groups during SSO but is not removed from his existing groups if those groups are not found in the SAML assertion returned by the IdP.

3. Exclude Groups

Sometimes the application users are part of IdP groups as well as some internal groups like jira-software-users/confluence-users to maintain application access. Now, if these groups are not present in IdP’s assertion the user will be removed from these core groups. Enabling Keep Existing Groups option will mean that users won’t be removed from the IdP groups as well. This is where the Exclude Groups option comes in. Using this option, you can keep removing the user from IdP groups on the application while preserving selected local groups.