Give SCIM groups a role

When your identity provider (IdP) pushes groups to HelpDocs over SCIM, you can pick a role for each group. HelpDocs then sets each member's role from their groups. SCIM is in beta. See Provision users with SCIM (beta) first.

How roles are worked out

Each person gets the highest role from their groups that have a role.
People in no group with a role get your Default role. You set it under New people in Settings > Sign-in & access.
A group with No role doesn't affect anyone's role. Adding someone to it or removing them from it leaves their role alone.
The account owner's role never changes.

From lowest to highest, the roles are Read only, Writer, Editor, and Administrator. A group can't give the Owner role.

Roles are worked out again whenever:

someone joins or leaves a group that has a role,
a group that has a role is deleted, or
you change a group's role.

Pick a role for a group

Go to Settings > Sign-in & access.

In the SCIM provisioning section, find Group roles. Each group your IdP has pushed is listed with its number of members.

Open the Role dropdown for the group and pick a role, or No role.

Check the message in Change role for <group>?.

Select Change role.

HelpDocs shows Role saved, and tells you how many people's roles changed.

If no groups are listed, you'll see "Groups your identity provider sends will show here." Push a group from your IdP first.

Changing a role can remove access

When you change a group's role, everyone in the group gets the highest role from all their groups. That replaces any role that was set by hand.

For example, if someone was made an Editor by hand and you give their group the Read only role, they become Read only, unless another of their groups gives a higher role.

Before you pick a role, check who's in the group.

Members are managed by your IdP

Members your IdP manages have a Managed badge in Settings > People. Groups your IdP pushes are managed by your IdP too. HelpDocs refuses these changes and shows a message that starts "Managed by your identity provider":

Changing a managed member's role, or removing them.
Adding anyone to, or removing anyone from, a group your IdP pushed. This includes members your IdP doesn't manage.
Renaming or deleting a group your IdP pushed.

If a change includes even one managed person, such as a bulk edit of several people, HelpDocs refuses all of it and changes nothing. The message lists the managed people.

You can still add managed members to groups you made in HelpDocs, and remove them from those groups.

These rules don't apply to the account owner or HelpDocs staff.

Make the other changes in your IdP, or change the group's role here.

Link existing groups

When your IdP pushes a group, HelpDocs normally creates a new group, even if you already have a HelpDocs group with the same name. If your articles already use a HelpDocs group for permissions, link it instead. Your IdP then takes over that group, and its article permissions keep working.

Link the group before your IdP pushes it for the first time. You can link groups as soon as the SCIM beta is on, before you create a token.

Go to Settings > Sign-in & access.

In the SCIM provisioning section, find Link existing groups and select Link a group.

In HelpDocs group, choose your existing group.

In Group name in your identity provider, enter the group's name exactly as your IdP will send it. Capital letters don't matter. HelpDocs fills in the HelpDocs group's name to start with.

Read the warning. If the group has members, select I understand members will be replaced.

Select Link group.

HelpDocs shows Group linked, and the link shows in the table with its HelpDocs group and Identity provider group. Until your IdP sends a group with that name, nothing about your existing group changes.

When your IdP first sends a group with that name, it takes over the HelpDocs group:

The group is renamed to the name your IdP sends.
Its members are replaced with your IdP's list. People who were added by hand and aren't in your IdP's list are removed. HelpDocs staff stay.
Its article permissions keep working, because it's still the same group.
The link is used up, so it leaves the table. The group shows under Group roles with No role. Pick a role if you want one.

You can't link the [Public] group, a group your IdP has already sent, or a group that's already linked. If there's nothing left to link, Link a group is turned off.

To remove a link before your IdP sends the group, select Remove next to it. HelpDocs shows Link removed. Your group doesn't change.

If your IdP deletes a linked group

If your IdP later deletes a group it took over, HelpDocs keeps the group but removes all its members. Its article permissions stay as they are. It becomes an ordinary HelpDocs group again, and you can link it again.

If your IdP already sent the group

You can't link a group your IdP has already sent. Instead:

In your IdP, unassign the group from the HelpDocs app, or stop pushing it. Your IdP deletes its copy of the group in HelpDocs.

In HelpDocs, link your existing group to the IdP group's name.

In your IdP, push the group again.

Whether unassigning a group deletes it in HelpDocs depends on your IdP and its settings. Check that the IdP's copy of the group is gone from Group roles before you push it again.

Every link you add or remove, and every role change, is recorded in your Audit log under your name.