Grouper TrueFoundry provisioner

External system

Grouper TrueFoundry external system

Links

• (Log in) https://<domain>.truefoundry.cloud

• (API) https://app.truefoundry.com/api/svc/v1

• (API Docs) https://www.truefoundry.com/docs/api-reference

• (SDK Docs) https://www.truefoundry.com/docs/truefoundry_sdk

Overview

The TrueFoundry Provisioner manages users, roles, teams, and team memberships in a TrueFoundry tenant via the native REST API.  http://localhost:8080/whatever

TrueFoundry has two distinct group-like concepts managed by this provisioner:

• Teams - groups of users, managed via the team manifest PUT endpoint. Members and managers are specified by email. The provisioner uses replaceGroupMemberships semantics (full member list is sent each time). TrueFoundry requires at least one member per team at all times. A configured default team member (service account) is always kept in every team so the team is never empty.

• Roles - RBAC roles assigned to individual users. Roles are account-scoped and created in the TrueFoundry UI by administrators. The provisioner assigns existing roles to users; it does not create roles. Every user must be in exactly one role at all times. The recommended pattern uses scripted Grouper groups with mutual-exclusion logic to enforce this constraint (see Setting up role groups below).

All provisioning is performed via the native REST API. The SCIM v2 endpoint is not used for user creation -- SCIM users have isEditable: false and cannot have roles assigned, making SCIM insufficient for full provisioning needs. SCIM PATCH is used only for display name updates on natively-registered users.

The provisioner class is edu.internet2.middleware.grouper.app.truefoundry.TrueFoundryProvisioner.

This provisioner works best if you set "replace memberships" to true.

You should add the team manager Grouper group to be a member of the Team member grouper group to have good results.

Provisioner configuration

The following configuration properties are specific to the TrueFoundry provisioner. These are set via the provisioner configuration in the Grouper loader properties (database or file), with the prefix provisioner.<configId>..

Naming requirements

Team and role names in TrueFoundry must follow these rules:

• Must start with a lowercase letter (a–z). Digits and hyphens are not allowed as the first character.

• Must end with a lowercase letter or digit (a–z, 0–9). Hyphens are not allowed as the last character.

• Middle characters may be lowercase letters (a–z), digits (0–9), or hyphens (-). No uppercase letters, underscores, spaces, or other special characters.

• Length must be between 3 and 36 characters inclusive.

Examples of valid names: my-team, read-only-member, ml-platform-v2.
Examples of invalid names: MyTeam (uppercase), -team (starts with hyphen), team- (ends with hyphen), ab (too short).

The provisioner validates names at provisioning time and will throw an error if a name does not conform.

Grouper folder structure

The provisioner uses the Grouper folder structure to distinguish between teams and roles. Create a folder hierarchy like the following under your provisioning root:

myOrg:apps:truefoundry:roles: <-- role groups go here myOrg:apps:truefoundry:teams: <-- team groups go here myOrg:apps:truefoundry:teamManagers: <-- (optional) team manager groups go here

Configure the groupType target group attribute with a translationScript expression that derives the type from the folder path. For example:

${grouperProvisioningGroup.getName().startsWith("myOrg:apps:truefoundry:roles:") ? "role" : "team"}

Attach the provisioning attribute to the parent folder (e.g. myOrg:apps:truefoundry) with scope sub so all groups under roles and teams are provisioned.

Setting up role groups

TrueFoundry has four built-in roles that the provisioner can assign to users. The group extension must exactly match the TrueFoundry role name.

The provisioner automatically determines the correct resourceType based on the role name (tenant-admin → tenant, all others → account).

Custom roles created by administrators in the TrueFoundry UI can also be managed by creating additional groups with matching extensions (e.g. myOrg:apps:truefoundry:roles:customrole1).

One-and-only-one role constraint

Every user must be in exactly one role group at all times. If a user is in multiple role groups the provisioner will keep assigning roles in an undefined order, leaving the user in whichever was last processed. If a user is in no role group the provisioner assigns the configured trueFoundryDefaultRole.

The recommended pattern uses two sibling folders to enforce mutual exclusion with scripted Grouper groups:

• roleAssignments: — contains simple assignment groups, one per role. Administrators add users here directly.

• roles: — contains scripted groups, one per role. These are the groups actually marked as provisionable. Each scripted group subtracts higher-priority roles to ensure no user is in two role groups at once.

The priority order (highest to lowest) is: tenant-admin > higher custom roles > member > read-only-member. Higher-priority roles take precedence; a user in roleAssignments:tenant-admin_assigned is removed from all lower-priority role groups by the scripting logic.

Example folder layout:

myOrg:apps:truefoundry:roleAssignments:tenant-admin_assigned <-- direct assignment group myOrg:apps:truefoundry:roleAssignments:subadmin_assigned myOrg:apps:truefoundry:roleAssignments:member_assigned myOrg:apps:truefoundry:roleAssignments:read-only-member_assigned myOrg:apps:truefoundry:roles:tenant-admin <-- scripted, provisionable myOrg:apps:truefoundry:roles:subadmin myOrg:apps:truefoundry:roles:member myOrg:apps:truefoundry:roles:read-only-member

Scripted group definitions (using Grouper composite / filter logic):

With this pattern a user can be added to multiple roleAssignments groups (e.g. promoted by accident) but will appear in only one roles group — the highest-priority one they qualify for — guaranteeing TrueFoundry receives exactly one role assignment per user.

Attach the provisioning attribute to myOrg:apps:truefoundry:roles (not roleAssignments) so only the scripted role groups are provisioned.

Setting up team manager groups (optional)

If trueFoundryAddTeamManagerMetadata is enabled, create a manager group for each team under a teamManagers folder. Set the md_trueFoundryTeamManager metadata on the team group to the path of the corresponding manager group. Members of the manager group who are also members of the team group will be added to the team's managers list in TrueFoundry.

For example:

• Team group: myOrg:apps:truefoundry:teams:engineering

• Manager group: myOrg:apps:truefoundry:teamManagers:engineering

• Metadata on the team group: md_trueFoundryTeamManager = myOrg:apps:truefoundry:teamManagers:engineering

Provisioning attributes

User (entity) attributes

TrueFoundry is purely email-based -- there are no display names shown in the product UI. It is recommended to use EPPN (eduPersonPrincipalName) as the email value if it is email-routable for all users, since it works best with SSO and handles users with multiple email addresses correctly.

Team (group) attributes

Role (group) attributes

Note: resourceType is not a configurable attribute. The provisioner automatically uses tenant for the tenant-admin role and account for all other roles.

CRUD operations