SCIM overview

Automatically provision users and teams with TeamRetro SCIM

System for Cross-domain Identity Management (SCIM) is a protocol for user management across multiple applications. It allows your IT or Operations team to provision, deprovision, and update user or team data in TeamRetro using your existing identity provider. SCIM support is included in TeamRetro ENTERPRISE subscriptions

TeamRetro SCIM supports:

Provisioning/deprovisioning of users
Provisioning/deprovisioning of user account roles
Provisioning/deprovisioning of teams
Provisioning/deprovisioning of user team roles (per team)
Updating team names
Updating user names

Detailed setup instructions for common identity providers can be found below:

Our SCIM API documentation can be found at SCIM API Documentation

Prerequisites

You must have SAML single-sign-on enabled for your organization.

Background: TeamRetro User Model

TeamRetro supports two layers of user roles. At the whole-of-account level, a user can be an Account Owner, Account Administrator or Account User. Additionally, within each team, the user can be either a Team Administrator or a Team Member. Further information on the specific capabilities of each role can be found in our Roles and Permissions Overview .

An example of how this may appear for a small enterprise is below.

Provisioning Account Roles

Account roles can be provisioned by creating SCIM groups for the Account Owners and Account Administrators. By default, TeamRetro will look for a group named TeamRetro-Account-Owners and a group named TeamRetro-Account-Admins. If you have a standard group naming scheme you'd like to use, you can adjust the expected group names via the TeamRetro administration panel under Account > Settings > SCIM & API > Account Role Groups

For example, if you configure the following groups in your identity provider:

TeamRetro-Account-Owners
- ab@acme.org
TeamRetro-Account-Admins
- bc@acme.org
- cd@acme.org

Following SCIM synchronization, if we start with the account from the previous documentation section, the new state will appear as below:

Notes on behavior:

All users sent by SCIM to TeamRetro have at minimum the Account Users role
SCIM provisioned account roles are
- ie. Existing Account Owners will continue to have account owner access
- ie. Existing Account Admins will continue to have account admin access
- ie. Existing Account Users will continue to have account user access
User's roles at the team-level are not affected

Provisioning Teams and Team Roles

In addition to provisioning account level roles, you can provision the creation of new Teams and assign users Team Roles via SCIM groups. By default, TeamRetro will look for any SCIM groups matching the TeamRetro-{{TeamName}}-Team-Admins or TeamRetro-{{TeamName}}-Team-Members pattern (based on a group name prefix and suffix match), and create a new team (if required) and provision the team roles. If you have a standard group naming scheme you'd like to use, you can adjust the expected group prefix / suffixes via the TeamRetro administration panel under Account > Settings > SCIM & API > Team Provisioning / Team Role Groups

For example, if you configure the following groups in your identity provider:

TeamRetro-Development-Team-Admins
- ab@acme.org
TeamRetro-Development-Team-Members
- cd@acme.org
TeamRetro-Sales-Team-Admins
- bc@acme.org
TeamRetro-Sales-Team-Members
- de@acme.org
- ef@acme.org

Following SCIM synchronization, if we start with the account from the previous documentation section, the new state will appear as below:

Notes on behaviour:

If the team name matches an existing team (eg. Development) - the existing team will be updated
If the team name does not match an existing team (eg. Sales) - a new team will be created (requires sufficient team slots on your subscription)
SCIM provisioned team roles are
- Existing Team Administrators will continue to have the team administrator role
- Existing Team Members will continue to have the team member role
Removing an SCIM team group will result in the Team being deleted only if all team members were provisioned via SCIM.
Any users added to a team will also have the Account User role
User's roles at the account-level are not affected