SCIM provisioning

SCIM lets your identity provider (IdP) manage who is in your TaskView organization. The IdP creates people, changes their details and turns their access off; TaskView follows. Groups from the IdP can be linked to projects, so people who join a group are added to the project with a role you choose.

SCIM works on top of an SSO configuration: each SSO config has its own SCIM token and its own set of provisioned users and groups.

Turning SCIM on

1. Open your organization's settings → SSO tab. You need the admin or owner role.
2. Make sure the SSO email domain is verified (see Domain verification). SCIM requests are refused with 403 until it is.
3. In the SSO config card, switch on SCIM Provisioning.
4. Click Generate SCIM Token and copy the token. It is shown only once; TaskView stores only its hash. Regenerate Token replaces it, and the old token stops working.
5. In your IdP, set the SCIM base URL to the SCIM Endpoint URL shown in the card (<API URL>/scim/v2) and the token as a Bearer token.

Turning SCIM off

Switch off SCIM Provisioning in the SSO config card. Then:

• The token is deleted. Requests from the IdP are refused with 401.
• Nothing is removed. People stay in the organization and its projects. SCIM users, the remembered access of deactivated users, groups and their project links stay in the database. The Groups list is hidden while SCIM is off.
• Group links stop working, since the IdP no longer sends changes.
• SSO sign-in adds people again. As without SCIM, anyone from the SSO domain who signs in is added to the organization with the default role (member).

Turning it back on

1. Switch SCIM Provisioning on and click Generate SCIM Token: the old token is gone.
2. Put the new token into your IdP.

The kept SCIM users, groups and links apply again, and changes the IdP sends from then on are handled as usual. Changes made in the IdP while SCIM was off reach TaskView only if the IdP sends them again.

A deactivated person who got back in while SCIM was off stays in the organization, but their next SSO sign-in is refused, since their SCIM record is still deactivated. For the IdP they are already deactivated, so it may never send anything about them: remove them from the organization by hand.

People

Rules that always apply:

• Email. TaskView takes the address from emails (the primary one, otherwise the work one, otherwise the first). If there is none, userName is used when it is an email address. Without an address the request is refused with 400.
• Domain. The address must belong to the SSO config's email domain, otherwise the request is refused with 400.
• Owner. The organization owner cannot be deactivated or deleted over SCIM (400).
• Existing members. When the IdP looks a person up by userName or email and they are already a member of the organization (added by hand or before SCIM was turned on), TaskView links them to the IdP instead of creating a duplicate. Only addresses in the SSO domain are linked.
• Members added by hand who the IdP never sent are not touched by SCIM.

Signing in with SCIM on

While SCIM is on, the IdP decides who may enter the organization. When someone signs in through this SSO config:

• an active SCIM user or an existing member of the organization signs in as usual;
• a deactivated SCIM user is refused with "Your access to the organization is turned off";
• anyone else is refused with "You have not been added to the organization yet": SSO no longer adds new people on their first sign-in.

With SCIM off, SSO works as described in User provisioning: new people are added on their first sign-in.

When SSO and SCIM disagree

In the IdP, access to the application over SSO and provisioning over SCIM are often set up separately, so they can get out of step:

• Deactivated over SCIM, but the IdP still lets them sign in. TaskView refuses the sign-in: with the same address the person sees "Your access to the organization is turned off", with an address SCIM has not seen "You have not been added to the organization yet". Their sessions were already closed when SCIM deactivated them.
• Blocked from signing in at the IdP, but still active over SCIM. The IdP stops new sign-ins, but TaskView has not been told anything: the person stays in the organization and its projects, and sessions that are already open keep working until they expire.

Groups and projects

Groups sent by the IdP appear in the SSO config card under SCIM Provisioning → Groups (visible while SCIM is on), with the number of members. A group can be linked to one or more projects, each with a default role.

SCIM only adds people to projects. It never removes anyone and never changes the roles of someone who is already in a project:

A person who was removed from a project by hand is added again only by a new event: they leave the group and join it again, they join another group linked to the same project, or the link is removed and created again.

People are added only if they are an active SCIM user and a current member of the organization. Archived projects are not filled, and the project owner is skipped.

Linking a group

1. In the Groups list, click Add project next to the group.
2. Choose a project and a default role. The role must exist in that project; create it in the project's settings first if needed.
3. Click Link.

Linking the same project again with another role changes the default role for people who join later. People already in the project keep their roles.

Who can link: organization owners and admins, the same people who manage SSO. They can link any active project of the organization, even one they are not a member of. In this list they see only project and role names; opening a project still requires being a member of it.

What else changes a link

• The IdP deletes the group: its links are deleted, people stay in the projects.
• The project or the role is deleted: the link is deleted.
• The project is archived: the link stays, but nobody is added while the project is archived.

Supported SCIM operations

Base path: /scim/v2. Every request needs Authorization: Bearer <SCIM token>.

Group names do not have to be unique: two groups may share a displayName. Only externalId identifies a group.

Provider notes

Pocket ID

• Restrict the OIDC client used for SCIM to user groups. Otherwise Pocket ID also sends its built-in API user, which has no email, and the sync fails with 400.
• During a sync Pocket ID deletes SCIM users it did not create itself, such as ones connected by another provider. If it has a user with the same email, that user takes their place; otherwise the person is removed from the organization. Members added by hand and never sent over SCIM are not affected.
• When a user is taken out of a group on the user's page, Pocket ID v2.18.0 does not send the change. Change membership on the group's page instead. Leaving a group does not remove anyone from a project anyway, but TaskView keeps showing the person in the group.

API endpoints for group links

Require authentication and the organization admin or owner role.

Database tables