Assign roles from your identity provider

When people sign in to VendorLogic through your company single sign-on, the identity provider decides who is what. VendorLogic never guesses a role from an email address, a domain or a company name. A person who signs in with no role mapped gets the WorkOS default role (member), which in a vendor organization is the read-mostly User. That is why the first person who sets up SSO is not an administrator by default.

The roles you can assign#

Staff slugs (staff, staff-admin) never apply to a vendor organization. Customer slugs never raise privileges in a vendor organization.

The role is recalculated at every SSO sign-in. A person already in the organization is upgraded or changed when WorkOS names a fitting role; the default member never demotes them. Changing a group in your provider takes effect the next time that person signs in (https://workos.com/docs/sso/identity-provider-role-assignment).

Owner of record#

Each organization has one Owner (the person who can transfer ownership). Staff onboard a vendor with an Owner email; that seat stays reserved for that mailbox until the person signs in. Ownership moves to your SSO user when either:

• WorkOS reports the vendor-owner role for them and the reserved Owner has never signed in (or there is none). A signed-in Owner is never displaced this way; they transfer ownership themselves.
• VendorLogic staff reassign ownership with Change owner on the SSO tab of the organization (/platform/organizations/[id]?tab=sso) (POST /platform/organizations/:id/ownership, needs staff.ownership.reassign), allowed while the reserved Owner has left or never signed in. The new Owner must already be an active member.

The first person to sign in through SSO is never made Owner automatically. Once there is an Owner or an Administrator, they can promote or demote the rest of the team in the Team tab of Settings (/settings?tab=team).

Both are recorded as org.ownership_transferred.

Step by step with authentik#

Prerequisite: your SSO connection in WorkOS is active (domain verified, OIDC connection set up through the link staff sent you).

1. Create one group per role in authentik. Admin interface, Directory > Groups > Create, for example vl-owner, vl-admin, vl-credit, vl-sales (https://docs.goauthentik.io/docs/users-sources/groups/manage_groups). Open each group and add its users.
2. Send the groups in the token. authentik's default profile scope includes the user's group membership (https://docs.goauthentik.io/add-secure-apps/providers/oauth2/). WorkOS needs a claim named groups in the ID token (https://workos.com/docs/integrations/oidc). Check in your OAuth2/OpenID provider (Applications > Providers) that the profile scope mapping is selected and that Include claims in id_token is on. If your authentik version does not emit groups, create a scope mapping under Customization > Property Mappings (https://docs.goauthentik.io/add-secure-apps/providers/property-mappings/) that returns {"groups": [group.name for group in user.ak_groups.all()]} and add it to the provider's Scopes.
3. Map the groups to roles in WorkOS. Role assignment must be enabled for your organization. WorkOS offers no API for it, so VendorLogic staff switch it on per organization in the WorkOS dashboard (organization, Roles tab); the status chips on the SSO tab of the organization and the "SSO not ready" view of /platform/organizations tell them when it is still off. Then, in the Admin Portal link staff gave you, open the SSO connection and, under role assignment, add an SSO group per row using the IdP group ID and pick the role (vendor-owner, vendor-admin, credit-manager, salesman). WorkOS identifies groups by the IdP group ID, so use the exact value your provider puts in the groups claim (https://workos.com/docs/sso/identity-provider-role-assignment). With authentik's mapping above that is the group name.
4. Sign in again. Each person signs out of VendorLogic and in through SSO. Their role updates on that sign-in.

Roles are single per person: someone in several mapped groups gets the highest-priority one. Google as the identity provider cannot send groups to WorkOS (same page), and if your company uses a directory, WorkOS recommends Directory Sync group role assignment instead; use one method only.

When it does not work#

• Still a User after signing in again: the groups claim is missing from the ID token, or the group ID in WorkOS does not match it, or role assignment is not enabled for your organization. Ask VendorLogic staff to check the organization's Roles tab in WorkOS.
• Staff can see who holds which role in /platform/users; roles are not edited by hand for SSO members, because the provider owns them.

Related#

• WorkOS Admin Portal link
• Memberships and ownership