Mapping groups to user roles

Organizations with Single Sign-On enabled that are also synchronizing groups can automate user role management by mapping each group to a role in CARTO. This is a very beneficial approach for organizations with a large number of users.


  • Your organization is using Single Sign-On (SSO) to login in CARTO

  • You are synchronizing groups in CARTO coming from your SSO

    • At least one group needs to exist before enabling group role mapping

Enabling group role mapping

To get started and map your groups to roles, go to the Settings > SSO tab. If all the requirements are met, you will see a switch called "Enable role management by groups"

After enabling this option, you'll need to select one group: this group will be your first group of admins.

If the role management is controlled via groups, you will be able to select the role that should be assigned to new groups the first time they are synchronized. We recommend leaving this option as Viewers, unless onboarding new editors is the priority.

Once you start using groups for role management, roles will be assigned automatically and you won't be able to manually select a role for a specific user. Instead, assign that user to the correct groups in your IdP.

Mapping your existing groups to roles

After you have enabled the role management by groups, there will be a new column in the Groups section, called Group role.

If you change the role of a group, users from that group will acquire the new role the next time they log in.

What if a user belongs to two or more groups? Users will acquire the highest role according to the groups they belong to. For example, if user A belongs to both an "Editors" and a "Viewers" group, they'll be assigned the Editor role.

Pre-creating groups for role mapping

If you want to map groups that have not still been synchronized to CARTO, simply go to the Groups tab and click on "Create group". For each new group, you will need to indicate:

  • Group alias: the user-facing name for this group in CARTO (can be changed later)

  • SSO group ID: this needs to match the group ID coming from your SSO IdP.

Once the group is created, it will show as having 0 members, but you will be able to assign it a role already. Do this with as many groups as necessary, and your organization will be ready to onboard hundreds of users if necessary, without needing manual role management.

Last updated