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 T | Source tenant is a sibling (no ancestor) | |
|---|---|---|
| Who decides | The parent tenant (it created T) | S, through its allow-list |
| Find the user | sourceUsers / admin provisioning, or the exact lookup below | Exact lookup only |
| Sign in to T | Login page of T offers "Login via S"; tenant switch | Tenant switch / token exchange from an S session only (no login provider is created in T) |
| Grant | CreateExternalTenantUserMapping, admin provisioning | CreateExternalTenantUserMapping |
| Revocation | Delete the mapping | Delete 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:
| Answer | Meaning |
|---|---|
403, code SourceTenantNotPermitted | S 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 check | the 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):
| Event | Written to |
|---|---|
Identity.CrossTenantLookup (hit / miss) | T and S; a miss for a tenant that does not exist only in T |
Identity.CrossTenantGrantCreated / …GrantChanged / …GrantRemoved | T; S only when S is an ancestor of T or permits T |
Identity.CrossTenantFirstExchange | T and S |
Identity.CrossTenantExchangeRefused (sibling source) | T and S |
Identity.CrossTenantGrantPermissionsChanged | S |
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:
| Tool | Risk | Purpose |
|---|---|---|
lookup_source_tenant_user | Medium | Exact lookup; errorCode: SourceUserNotFound for every miss, SourceUserLookupRateLimited with retryAfterSeconds |
create_external_tenant_user_mapping | High | Grant with groupIds; returns the stored mapping; refusals carry errorCode |
delete_external_tenant_user_mapping | High | Remove a grant (confirm=true) |
get_cross_tenant_grant_permissions | Low | S's allow-list |
set_cross_tenant_grant_permissions | High | Replace 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.
| Route | In tenant | SDK |
|---|---|---|
POST ExternalTenantUserMappings/sourceUserLookup — body { "sourceTenantId", "identifier" } | T | LookupSourceUser (returns null for SourceUserNotFound) |
POST ExternalTenantUserMappings — body with optional groupIds | T | GrantExternalTenantUser (returns the stored mapping) |
GET / DELETE ExternalTenantUserMappings[/{rtId}] | T | GetExternalTenantUserMappings, DeleteExternalTenantUserMapping |
GET / PUT CrossTenantGrantPermissions — body { "targetTenantIds": [] } | S | GetCrossTenantGrantPermissions, 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.