Multi-org SSO setup

This page covers how to configure SSO when your Port company has multiple organizations, such as separate environments for development and production. It addresses common questions about IdP application registration, team synchronization, and RBAC across organizations.

Architecture overview

In Port's multi-organization model, SSO, SCIM, and group filters are configured at the company level, not at the individual organization level. This means:

• A single SSO connection serves all organizations under your company.
• A single IdP application registration handles authentication for all Port organizations.
• Users authenticate once and can access any organization they have permission to view.

Company vs. account

In typical setups, one company equals one account. However, the data model is company-scoped, meaning SSO configuration belongs to the company entity.

Layer	Component	Description
Identity Provider	Single app registration	One SSO application in your IdP (Okta, Entra ID, Google, etc.) handles authentication for all Port organizations.
Port Company	SSO connection	The company-level SSO configuration routes authenticated users to their permitted organizations.
Organizations	Access control	Each organization independently controls who can access it via automatic user access or explicit invitations.

Single IdP app vs. multiple apps

You only need one IdP application registration for all Port organizations under your company.

Approach	Recommended	Why
Single IdP app	Yes	One configuration to maintain, all organizations authenticate through the same SSO flow.
Multiple IdP apps	No	Unnecessary complexity. Port's SSO is company-level, not org-level.

The single application handles authentication, and Port determines which organizations the user can access based on invitations or automatic user access settings.

Legacy SSO

Per-organization SSO connections still exist for migrated or non-multi-org customers. However, SCIM and group blocklists require company-level SSO.

Setting up SSO for multi-org

Prerequisites

• Your account must be on an Enterprise plan (or POC/INTERNAL).
• You must have account admin permissions.

Step 1: Configure SSO at the company level

Follow the standard SSO setup process to configure your identity provider. This single configuration applies to all organizations.

1. Go to Organization settings > SSO tab in any organization.
2. Complete the SSO setup flow with your identity provider.
3. Test the connection with a test user.

Step 2: Configure organization access

After SSO is configured, control which users can access each organization. Automatic user access is disabled by default - users are not added to organizations unless the toggle is enabled or they are explicitly invited.

Automatic user access

Enable automatic user access to allow all SSO users to access an organization:

1. Go to Organization settings > Access tab.
2. Enable Automatic user access.
3. Click Save.

Users who log in via SSO automatically receive the member role in this organization.
Note: Enabling automatic user access requires account admin permissions and an Enterprise plan (or POC/INTERNAL).

Development environments

Automatic user access is ideal for development or staging organizations where broad access is acceptable.

Explicit invitations

For organizations requiring controlled access (such as production), keep automatic user access disabled and invite users explicitly:

1. Go to the organization's Users & teams page.
2. Click Invite users.
3. Enter the user's email address and assign a role.
4. The user receives access immediately upon invitation.

Production environments

Explicit invitations are recommended for production organizations where you need to carefully control who has access.

Team synchronization across organizations

Teams from your identity provider sync to Port during user login. Understanding how team sync works across organizations helps you plan your RBAC strategy.

How team sync works

1. User logs in via SSO to a specific organization.
2. Port reads the user's group memberships from the IdP.
3. Groups are synced as teams in the organization the user authenticated into.
4. Switching to another organization (or SCIM events) triggers team sync for that organization.

Team sync is per-organization

On login, teams sync only for the organization you authenticate into. Teams in other organizations sync when you switch to them or when SCIM events occur.

Teams are organization-scoped

Teams synced from your IdP exist within each organization separately.
This means:

• The same IdP group syncs to each organization the user accesses.
• Team membership is evaluated independently per organization.
• A user can be in different team states in different organizations, because teams only sync when the user accesses that organization.

For example, if a user belongs to the platform-team group in your IdP:

Organization	Team synced	Result
Development	platform-team	User is added to the platform-team in Development org when they log in or switch to it.
Production	platform-team	User is added to the platform-team in Production org when they switch to it (if they have access).

Control which groups sync

Use group filters to control which IdP groups become Port teams:

1. Go to Organization settings > SSO tab.
2. Click Set Group Filters.
3. Define allow/block patterns using regular expressions.
4. Test your patterns against existing synced groups.

Configuring group filters requires account admin permissions, an Enterprise plan (or POC/INTERNAL), and company-level SSO.

Example patterns:

Pattern type	Example	Effect
Allow	^port-.*	Only sync groups starting with port-.
Block	^admin-.*	Exclude groups starting with admin-.
Allow + Block	Allow: .* Block: ^temp-.*	Sync all groups except those starting with temp-.

Note: If a group matches both the allow list and the block list, the blocklist wins and the group will not sync.

Company-level scope

Group filters apply at the company level, affecting all organizations. You cannot configure different group filters for different organizations.

RBAC in multi-org environments

When users belong to multiple organizations, each organization maintains its own independent RBAC configuration.

Roles are organization-specific

A user's role in one organization does not affect their role in another:

User	Development org role	Production org role
Alice	Admin	Member
Bob	Member	Admin
Carol	Admin	No access

Recommended RBAC patterns

Team-based permissions

Assign permissions to teams rather than individual users. This scales better and aligns with IdP group management.

1. Create teams that mirror your IdP groups.
2. Assign blueprint and action permissions to teams.
3. Let team sync handle user membership automatically.

Benefits:

• Permissions update automatically when IdP group memberships change.
• Consistent permissions across users with similar responsibilities.
• Easier to audit and maintain.

Role-based permissions

Use Port's built-in roles (Admin, Moderator, Member) combined with team ownership for simpler setups.

1. Assign users to appropriate roles when inviting them.
2. Use team ownership to control entity visibility.
3. Configure action permissions at the role level.

Benefits:

• Simpler to set up for smaller teams.
• Clear hierarchy of permissions.
• Works well when IdP group structure doesn't map cleanly to Port permissions.

Ownership patterns for multi-org

Consider different ownership strategies for different organizations:

Organization type	Recommended ownership	Rationale
Development	Team-based, flexible	Encourages collaboration and experimentation.
Staging	Team-based, mirroring production	Validates permissions before production deployment.
Production	Strict team ownership	Limits who can modify production entities.

SCIM in multi-org setups

If you use SCIM for user provisioning, SCIM operates at the company level.

User status

Users provisioned via SCIM are initially added with STAGED status. They become fully active after their first SSO login.

Organization access

SCIM-provisioned users appear in organizations based on the same rules as SSO users:

• Organizations with Automatic user access enabled: SCIM users appear automatically (after first login activates them).
• Organizations without automatic access: Users must be explicitly invited.

SCIM handles user lifecycle (create, update, delete), while organization access is controlled separately.

SCIM requirements

SCIM requires company-level SSO. It is not available with legacy per-organization SSO connections.

Common scenarios

Scenario 1: Dev org open, prod org restricted

Goal: All developers can access the development org, but only selected users can access production.

Setup:

1. Configure SSO once at the company level.
2. Development org: Enable automatic user access in Organization settings > Access tab.
3. Production org: Keep automatic user access disabled (the default), invite specific users.

Scenario 2: Sync different teams to different orgs

Goal: Only platform teams should see production entities.

Setup:

1. Use the same IdP app registration for both orgs.
2. Configure group filters to sync only relevant teams.
3. In the production org, assign entity ownership to platform teams.
4. Non-platform team members won't see production entities due to ownership rules.

Scenario 3: Separate environments with same team structure

Goal: Mirror your IdP group structure across dev and prod with identical team names.

Setup:

1. Enable the same group sync patterns for all organizations.
2. Teams sync with the same names to both orgs (when users access each org).
3. Assign different permissions to the same team in each org (dev teams get write access in dev, read-only in prod).

Troubleshooting

User can access dev but not prod

Cause: The production organization doesn't have automatic user access enabled, and the user hasn't been explicitly invited.

Resolution: Either enable automatic user access for production, or explicitly invite the user.

Teams not syncing to some organizations

Cause: The user hasn't accessed that organization since their IdP group membership changed.

Resolution: Team sync happens when you authenticate into or switch to an organization. Ask the user to switch to the organization using the organization switcher, or trigger a SCIM sync.

Different roles needed per organization

Cause: Port maintains separate role assignments per organization by design.

Resolution: This is expected behavior. Assign the appropriate role when inviting users to each organization.

SCIM user not appearing in organization

Cause: SCIM users are created with STAGED status and need to complete their first SSO login to become active.

Resolution: Ask the user to log in via SSO. After their first login, they will appear in organizations that have automatic user access enabled.

Related documentation

• Multiple organization membership - Creating and managing organizations.
• Manage your SSO connection - Self-serve SSO setup.
• SCIM - Automated user provisioning.
• Manage users and teams - Team and user management.