Skip to main content

Cross-Tenant Access for Sibling Tenants

An administrator of a target tenant T can give one user of another source tenant S access to T with chosen groups of T — also when S is not a parent (ancestor) of T, for example a meshmakers employee who supports the customer tenant customer-a, a sibling under the same parent. T's administrator never sees S's user directory:

  • the user is found by the exact user name or the exact e-mail address — there is no list, no prefix or wildcard search;
  • this works only when S permits T — S keeps an allow-list of target tenants, empty by default;
  • every lookup, grant, first use and removal is written to the event log of both tenants.

Ancestor and sibling sources​

Source tenant is an ancestor of TSource tenant is a sibling (no ancestor)
Who decidesThe parent tenant (it created T)S, through its allow-list
Find the usersourceUsers / admin provisioning, or the exact lookup belowExact lookup only
Sign in to TLogin page of T offers "Login via S"; tenant switchTenant switch / token exchange from an S session only (no login provider is created in T)
GrantCreateExternalTenantUserMapping, admin provisioningCreateExternalTenantUserMapping
RevocationDelete the mappingDelete the mapping, or S removes T from its allow-list

Ancestry is taken from the tenant registry. The ancestor flows are described in Cross-Tenant Authentication.

End to end with octo-cli​

The example uses the source tenant meshmakers, the target tenant customer-a and the user alice.

1. S permits T (administrator of S)​

Only administrators of S — roles UserManagement and TenantManagement, with a token issued for S (sign in to S or switch into S first) — read and change the list. An administrator of another tenant, a parent administrator with a token of the parent included, gets 403.

octo-cli -c UseContext -n meshmakers
octo-cli -c GetCrossTenantGrantPermissions
octo-cli -c SetCrossTenantGrantPermissions -ttids "customer-a"

SetCrossTenantGrantPermissions replaces the whole list and logs which tenants were added and removed. Entries are trimmed, lower-cased and de-duplicated; at most 200 entries of up to 64 ASCII letters, digits, - or _; never S itself. An invalid list answers 400 and nothing changes. Entries are not checked for existence. --none permits nobody.

2. Find the user (administrator of T)​

octo-cli -c UseContext -n customer-a
octo-cli -c LookupSourceTenantUser -st "meshmakers" -id "alice@meshmakers.io"

The answer contains SourceTenantId, UserId, UserName and DisplayName — never the e-mail address. The typed identifier is not written to any log. Every negative case gives the same answer and exit code -3:

No user found that can be granted access (code SourceUserNotFound).

This covers: S does not exist, S does not permit T, no exact match, more than one match, a cross-tenant shadow user, a locked or blocked user. Lookups are limited per caller and target tenant (default 20 per 10 minutes); over the limit the command prints the wait time, e.g. Too many lookups: … (HTTP 429, code SourceUserLookupRateLimited). Retry after 240 s.

3. Grant with groups​

octo-cli -c CreateExternalTenantUserMapping -stid "meshmakers" -suid "<UserId>" -sun "alice" -g "Operators,Viewers"

-g takes group names or group IDs of T. The user gets exactly the roles of these groups (plus -rids, if given) at the first tenant switch. The command prints the mapping as stored: the user name comes from S's user record, GroupNames lists the groups. Refusals:

AnswerMeaning
403, code SourceTenantNotPermittedS is neither an ancestor of T nor permits T, or S has no such user — one answer for all of these
400, code UnknownGroup (with unknownGroupIds)a group is not a group of T; nothing is stored
409, code ExternalTenantUserMappingAlreadyExists (with existingMappingId)the user already has a mapping in T; change its roles instead
403 from the role checkthe groups grant roles the caller may not hand out

4. The user switches into T​

alice signs in to meshmakers and switches to customer-a (Refinery Studio tenant switch, or a token exchange). At the first switch the identity service creates the cross-tenant user xt_meshmakers_alice in T with the roles of the mapping.

5. List and remove​

octo-cli -c GetExternalTenantUserMappings -stid "meshmakers"
octo-cli -c DeleteExternalTenantUserMapping -id "<mapping-rtid>"

The list shows SourceTenantId, SourceUserName and GroupNames of each grant.

Revocation​

The next token exchange of the user into T is refused when

  • the mapping is deleted,
  • S removes T from its allow-list, or
  • the mapping has no effective role left (direct roles and the roles of all its groups together).

An access token already issued stays valid until it expires; exchanged tokens are short-lived and carry no refresh token. Lookups and new grants from T stop at once when S removes T.

Audit​

Both administrators see the events in their own event log (category = event name):

EventWritten to
Identity.CrossTenantLookup (hit / miss)T and S; a miss for a tenant that does not exist only in T
Identity.CrossTenantGrantCreated / …GrantChanged / …GrantRemovedT; S only when S is an ancestor of T or permits T
Identity.CrossTenantFirstExchangeT and S
Identity.CrossTenantExchangeRefused (sibling source)T and S
Identity.CrossTenantGrantPermissionsChangedS

The looked-up identifier of a miss, e-mail addresses, tokens and passwords are never written. Read them with GraphQL on the tenant, filter category LIKE "Identity.CrossTenant*".

MCP tools​

AI assistants use the same rules through the OctoMesh MCP server:

ToolRiskPurpose
lookup_source_tenant_userMediumExact lookup; errorCode: SourceUserNotFound for every miss, SourceUserLookupRateLimited with retryAfterSeconds
create_external_tenant_user_mappingHighGrant with groupIds; returns the stored mapping; refusals carry errorCode
delete_external_tenant_user_mappingHighRemove a grant (confirm=true)
get_cross_tenant_grant_permissionsLowS's allow-list
set_cross_tenant_grant_permissionsHighReplace S's allow-list (confirm=true; [] permits nobody)

High-risk tools pause for the user's approval in the AI assistant.

REST API​

All routes are tenant-scoped (/{tenant}/identity/api/v1/…); the SDK (IIdentityServicesClient) wraps them.

RouteIn tenantSDK
POST ExternalTenantUserMappings/sourceUserLookup — body { "sourceTenantId", "identifier" }TLookupSourceUser (returns null for SourceUserNotFound)
POST ExternalTenantUserMappings — body with optional groupIdsTGrantExternalTenantUser (returns the stored mapping)
GET / DELETE ExternalTenantUserMappings[/{rtId}]TGetExternalTenantUserMappings, DeleteExternalTenantUserMapping
GET / PUT CrossTenantGrantPermissions — body { "targetTenantIds": [] }SGetCrossTenantGrantPermissions, UpdateCrossTenantGrantPermissions

Errors are RFC 9457 problem documents; clients branch on the code extension (ServiceProblem.TryParse in the SDK). The lookup is a POST so that the identifier never appears in access logs.