Skip to main content

Users and Roles

Users​

A user in OctoMesh represents an identity that can authenticate and access platform resources. Users are scoped to a tenant — the same person may have separate user accounts in different tenants.

User Properties​

PropertyDescription
UserIdUnique identifier (auto-generated)
NameUsername for login
EmailEmail address; a user cannot get or change to an address another user of the tenant already has (see Creating Users)
FirstName / LastNameOptional display name
ExternalLoginsLinked external identity provider accounts
ResetPasswordOnLoginForces password change on next login

User Types​

Local users authenticate with a username and password stored in the tenant's database.

External users authenticate via an identity provider (Google, Azure AD, LDAP, etc.). On first login through an external provider, OctoMesh creates a local user record linked to the external identity.

Cross-tenant users authenticate through a parent tenant. Their username is prefixed with xt_{parentTenantId}_ to distinguish them from local users. See Cross-Tenant Authentication.

Creating Users​

Users can be created in three ways:

  1. Via CLI — an administrator creates the user, with a password piped in from a secret store (or set in OCTO_CLI_NEW_PASSWORD; without either the user gets no password):

    Get-Secret -Name JohnDoePassword -AsPlainText | octo-cli -c CreateUser -un "john.doe" -e "john@example.com" --password-stdin
  2. Self-registration — a user signs in via an external identity provider for the first time. The provider must have AllowSelfRegistration enabled (default: true).

  3. Admin provisioning — a system administrator pre-provisions a cross-tenant user mapping before the user's first login. See Cross-Tenant Authentication.

A local user is created only by the Identity Service: through its REST API POST {tenantId}/v1/users (used by octo-cli and Refinery Studio) or the method User.CreateUser. Both run the same steps: the password policy (checked before the user is stored), the normalized user name and e-mail, a new security stamp, and the welcome mail (with a password: the e-mail confirmation; without one: the invitation to set a password). The generic paths refuse to create a user: a GraphQL create (generic, typed or a runtime-query row), an MCP create, a pipeline insert, a user-started ImportRt and the seed data of a blueprint answer GENERIC_CREATE_REPLACED_BY_METHOD naming System.Identity/User.CreateUser-1, before anything is written. An existing user (its id is stored in the tenant) can still be updated through these paths, within the rules of Fields Only the Identity Service Writes.

One e-mail address per user when creating. Both ways refuse a new user whose e-mail address another user of the tenant already has; upper and lower case do not matter. The REST API answers 409 Conflict as application/problem+json with code: USER_ALREADY_EXISTS and field: email (the address itself is not repeated), the method answers the declared error USER_ALREADY_EXISTS with the parameter field = email. Refinery Studio shows the readable title of the answer. A user without an e-mail address is not checked. Only creating is checked: tenants that already contain several users with the same address keep working - these users can still sign in and be edited.

One user name per user. A user name another user of the tenant already has (upper and lower case do not matter) is refused the same way: the REST API answers 409 Conflict as application/problem+json with code: USER_ALREADY_EXISTS and field: userName (the name itself is not repeated), the method answers USER_ALREADY_EXISTS with field = userName. This also applies when an existing user is renamed (PUT {tenantId}/v1/users/{userName} with a different name); nothing of the update is stored. Before release 3.5.0 the REST API answered 400 for a duplicate user name.

Changing the e-mail address follows the same rule. Updating a user (PUT {tenantId}/v1/users/{userName}, and therefore octo-cli -c UpdateUser and the user page of Refinery Studio) refuses a new address another user of the tenant already has, upper and lower case ignored, with the same 409 Conflict answer (code: USER_ALREADY_EXISTS, field: email); nothing of the update is stored. Only a change is checked: a user who already shares an address with another user (a tenant from before this rule) can still be edited as long as the address stays the same - also when only its upper and lower case change. Removing the address is not checked.

Sign-in with an external provider and cross-tenant users are not affected. The first sign-in through an external identity provider creates a separate user account with a provider-prefixed user name (for example Google_jane@example.com), even when a local user of the tenant already has the same e-mail address. OctoMesh never links the external sign-in to the local user by e-mail address, because anyone who controls an external account with that address would then get the local user's roles; the new account starts without roles. In the same way, a cross-tenant (xt_) user always carries the e-mail address of the user in the home tenant, also when a local user of the tenant has it.

Merging Duplicate Users​

When the same person ends up with two accounts (for example a local user and the user an external sign-in created), a user administrator merges the duplicate into the account that is kept, with REST POST {tenantId}/v1/users/{userName}/merge and the body { "sourceUserName": "<duplicate>" } ({userName} is the user that is kept), or with the method User.Merge. Both run the same steps: the external logins of the duplicate move to the kept user, every refresh token, authorization and browser session of the duplicate in this tenant is revoked, and the duplicate is deleted. Roles, group memberships, claims and cross-tenant mappings of the duplicate are not transferred; give the kept user the roles it needs separately. Merging away the last user who holds UserManagement is refused (see Rules for Changing the Roles of a User).

Password Management​

# Reset a user's password: octo-cli asks for the new password twice, without echoing it
octo-cli -c ResetPassword -un "john.doe"

# In a script: pipe the password in, or set OCTO_CLI_NEW_PASSWORD (-y because a piped input cannot confirm)
Get-Secret -Name JohnDoePassword -AsPlainText | octo-cli -c ResetPassword -un "john.doe" --password-stdin -y

octo-cli does not take the password on the command line any more, where it would end up in the shell history and the process list: the former -p still works in this release but writes a deprecation warning; the date of its removal will be announced.

octo-cli CreateUser / ResetPassword and the MCP tools create_user / reset_user_password call the methods User.CreateUser and User.ResetPassword through GraphQL; the password travels only in the request body and appears in no output or log. They need identity services 3.5.57 (CreateUser) / 3.5.52 (ResetPassword) or newer with Methods:Identity:EnablePasswordMethods switched on; against an older service they stop with a message naming that version and do not fall back to REST. Refusals such as PASSWORD_POLICY_VIOLATION come from the server; the CLI and MCP print the codes of the failed rules in brackets, e.g. [PasswordTooShort, PasswordRequiresUpper].

Other clients use the REST endpoint: the new password travels in the request body of POST {tenantId}/v1/users/ResetPassword ({ "userName": "…", "password": "…" }), never in the request URL: URLs end up in request logs, traces and proxy access logs. The Identity Service refuses a password passed as a URL query parameter with 400 and a hint to update the client; octo-cli, the SDK and Refinery Studio of the same release send the body. The endpoint runs the method User.ResetPassword (see REST Endpoints for Creating Users and Resetting Passwords): an administrator reset also lifts an active lockout, so a locked-out user can sign in with the new password at once. The log line "Password changed" of the reset names the path MethodResetPassword and the administrator who reset the password (by user name), or client <id> for a service client.

The password change and the first password in the account settings of the Identity Service run the methods User.ChangePassword and User.SetPassword in the same process (no password on the message bus, whatever Methods:Identity:EnablePasswordMethods says). A wrong current password counts as a failed sign-in towards the lockout, and a locked-out user cannot change the password; the account page stays signed in after the change.

Every password change ends the sessions of the user in the tenant: the password change in the account settings, setting a first password, the administrator reset, the reset with an e-mailed token and the methods User.ChangePassword and User.ResetPassword. The refresh tokens and remembered consents of the user are revoked before the new password is stored and once more after it, so they stop working even if the Identity Service stops in the middle of the change; the user signs in again with the new password. A refused change (wrong current password, invalid reset token, password that violates the policy) ends no session. Issued access tokens stay valid until they expire.

The ResetPasswordOnLogin flag can be set to force users to change their password at next login.

Two-Factor Authentication Without an Authenticator Key​

Users can protect their account with a second factor (authenticator app). The authenticator key and the recovery codes are secret credential material: they are never exported by ExportRt, and a repository restore in another environment brings them only as unreadable values (see Moving Users to Another Tenant). The flag TwoFactorEnabled is stored separately from them. A user with two-factor authentication switched on can therefore end up without an authenticator: in a tenant copied under System.Identity 2.27.0 with ExportRt/ImportRt, after a restore from another environment, after an import of edited user data, or when an administrator deletes the key.

Such a user never signs in with the password alone. If the password is correct, the sign-in is refused with the message "Your second factor must be set up again. Please contact your administrator." and no session is created. The rule fails closed. Only an authenticator key counts as a usable second factor.

Recovery:

  1. A user administrator (role UserManagement) switches the second factor of the user off with POST {tenantId}/v1/users/{userName}/disableTwoFactor or the method User.DisableTwoFactor. This removes the authenticator key and the recovery codes, sets TwoFactorEnabled to false, rotates the security stamp and ends the sessions of the user in the tenant. Setting the attribute through a generic GraphQL mutation or an import is refused (see Fields Only the Identity Service Writes).
  2. The user signs in with the password. A user without a usable password (for example after a restore from another environment) first sets a new one through the password reset (Forgot password), or an administrator resets it.
  3. The user enrols the authenticator again in the account settings and stores the new recovery codes.

Roles​

Roles define permissions in OctoMesh. Services check role claims in the user's access token to authorize operations.

Default Roles​

Every new tenant is provisioned with these built-in roles:

RolePurpose
TenantManagementCreate, configure, and delete tenants
UserManagementManage users, roles, groups, and identity providers
CommunicationManagementConfigure communication adapters and deployment sites
DevelopmentAccess development features (e.g., GraphQL playground)
AdminPanelManagementAccess management/admin features in Refinery Studio (system configuration, repository administration). Retained name from the retired Admin Panel.
BotManagementConfigure and manage scheduled jobs
DashboardManagementCreate and edit dashboards
DashboardViewerView dashboards (read-only)
ReportingManagementCreate and manage reports
ReportingViewerView reports (read-only)
DataModelManagementChange the data model of the tenant: import Construction Kit models, install, update and uninstall blueprints
StreamDataAdminManage Stream Data archives (create, activate, rollups, computed columns); also allows reading stream data
StreamDataWriterWrite stream data; also allows reading stream data
StreamDataReaderRead stream data (time series) through the asset repository API, see Stream-Data Roles
SecretManagementCreate, rotate and delete the secrets of the tenant's clients and API resources (mirror secrets included) and run the secret sweeps of the tenant; carried by TenantOwners, so every member holds it, clients included
FileManagementManage files in the platform file system
FileViewerRead files in the platform file system

Role Assignment​

Roles can be assigned to users in two ways:

  1. Direct assignment — an administrator explicitly assigns a role to a user:

    octo-cli -c AddUserToRole -un "john.doe" -r "DashboardViewer"
  2. Group membership — the user inherits all roles from the groups they belong to. See Groups.

Effective Roles​

A user's effective roles are the union of:

  • Directly assigned roles
  • Roles inherited from all group memberships (including nested groups, up to 10 levels deep)

The Identity Service resolves effective roles at token issuance time and includes them as role claims in the JWT access token.

Rules for Changing the Roles of a User​

A user with the role UserManagement can change the direct roles of other users, but not without limits. The same rules apply to the REST API (PUT /users/{user}/roles, PUT and DELETE /users/{user}/roles/{role}), to the user type methods User.SetRoles, User.AddRole and User.RemoveRole (see Identity Methods), and therefore to octo-cli, Refinery Studio and the MCP server, which use them:

  1. No self-grant. An administrator cannot add a role to their own user. Removing one of their own roles is not a self-grant (the last-administrator rule below still applies). A role change that does not alter the list of direct roles (Studio saves the unchanged list of the own profile) is not a change and succeeds. The rule also covers app roles that a blueprint seeds (four-eyes principle): a user administrator can grant them to others, never to themselves.
  2. Grant only what you hold. A built-in role (a role that ships with the platform, for example SecretManagement or TenantManagement) can only be granted by a caller who holds that role himself. Custom roles that your tenant defined can be granted by every user administrator. Removing a role is never checked against the roles of the caller. When a role is set with a list (SetRoles), only the difference to the current direct roles is judged: a built-in role the target already has can stay or be removed, even if the caller does not hold it. Exception for app roles: a caller who holds UserManagement (for example a member of TenantOwners) may also grant app roles it does not hold. App roles are the built-in roles that a blueprint other than System.Identity.Bootstrap seeds, for example EnergyCommunityManagement. Platform roles, the roles System.Identity.Bootstrap seeds (TenantManagement, UserManagement, SecretManagement, DataModelManagement, the StreamData* roles, …), must still be held. Callers without UserManagement keep the strict rule. Every allowed grant of an app role the caller does not hold is logged with caller, target and roles. The exception applies to every path of this page: direct user and client roles, group roles, group membership, group nesting and mappings; it never lifts the self-grant rule.
  3. The last user administrator stays. A change is refused when afterwards no user of the tenant holds UserManagement any more. A user holds it when it is assigned directly, through a group (including nested groups) or, for cross-tenant (xt_) users, through an external tenant user mapping and its groups. Clients that hold UserManagement do not count. The rule covers removing the role (RemoveRole, SetRoles), deleting the user, and merging the user into another one (the source of a merge is deleted). A tenant that already has no user administrator is not blocked further.

Who is "self". A user session is "self" for its own user. A client-credentials caller (a token without a user) is judged with the roles of its own client and is "self" for that client, never for a user; see Rules for the Roles of Clients. The application a user signed in with (the client_id of a user session) is not the user and is never "self". Under impersonation only the target counts as self: a token that impersonates a user or a service account is "self" for that target, not for the administrator who impersonates.

RefusalRESTMethod (METHOD_FORBIDDEN, parameter reason)
Self-grant403, application/problem+json, code = self-grantself-grant
Built-in role not held403, code = role-not-held, roleNames lists the refused rolesrole-not-held, parameter roleNames (comma separated)
Last user administrator409, code = last-administratorlast-administrator

The title of the REST answer is a readable sentence; Refinery Studio shows it unchanged. Nothing is written when a call is refused. Every refusal is recorded in the event log entry Identity.Method (with the outcome and the reason); a REST call additionally writes the event Identity.RoleChangeRefused (caller, target user, reason and role names; never a token or a password).

Further rules of the REST endpoint PUT /users/{user}/roles: every role id is checked before anything is written; an unknown id answers 404 and leaves the roles unchanged (an earlier version removed all direct roles first). Only the difference is written.

Limits
  • The rules above apply to the direct roles of users; groups, mappings and role definitions follow the same rules. For the direct roles of clients the rules "no self-grant" and "grant only what you hold" apply (no last-administrator rule).
  • The check of the last user administrator is not a lock: two administrators who remove each other's role at the same moment can both pass it. Another administrator, for example of a parent tenant, then has to restore the role.
  • The first administrator of a new tenant, the roles seeded by blueprints, the one-time role grants of the platform, the provisioning of cross-tenant administrators and the groups assigned at sign-in by e-mail domain rules are not changes through the API and are not restricted by these rules.

REST Endpoints for Roles and Merging​

The REST endpoints of this section are deprecated (identity wave 1): every response carries a Link header to the replacing method and, from the first deployment of an environment after the date was set, the Deprecation header (deprecated since 2026-11-08). The sunset date is to be announced; until then there is no Sunset header. Switch to the methods before the sunset; see Deprecated REST Endpoints and Sunset Dates.

The REST endpoints that change the direct roles of a user or merge two users are facades over the methods of the user type. They have no rules of their own; the rules live once, in the method:

REST endpointMethod
PUT {tenantId}/v1/users/{userName}/rolesUser.SetRoles
PUT {tenantId}/v1/users/{userName}/roles/{roleName}User.AddRole
DELETE {tenantId}/v1/users/{userName}/roles/{roleName}User.RemoveRole
POST {tenantId}/v1/users/{userName}/mergeUser.Merge

Routes, request and response bodies and status codes stay the same. The endpoint resolves the user (and the roles), calls the method in the same process of the Identity Service (no message goes over the message bus) and turns the result into the usual REST answer. These methods carry no password or secret, so the endpoints work whatever Methods:Identity:EnablePasswordMethods says (see Identity Methods).

What REST callers notice:

  • Audit. Every REST call writes one event log entry Identity.Method - on success and on refusal. A refusal by the rules above still writes Identity.RoleChangeRefused as well.
  • Merge needs write access to the source user (data permissions). If the caller cannot read the source user, the answer is 404 "Source user … not found"; if the caller can read but not change it, 403 problem details with code = METHOD_FORBIDDEN.
  • Merge failures. A login that cannot be moved or a source user that cannot be deleted still answers 400, but each entry of failedDetails carries only the error code (no description). An unexpected failure answers 500 with the message "Merging the users failed." and never the text of an exception.
  • Unexpected failures of the role endpoints answer 500 problem details with code = METHOD_HANDLER_FAILED.
  • IdentityApiAuthorization:RoleEnforcement=Warn (not the default): a caller without UserManagement is now refused with 403 instead of being let through with a warning.
  • sourceUserName of a merge is trimmed.
A role held through a group counts as held over REST

Until the REST endpoints are retired, they keep their contract for a role the user holds only through a group: PUT …/roles/{roleName} answers 400 ("already has role"), and DELETE …/roles/{roleName} answers 200 and changes nothing. The methods look only at the direct roles: called directly (for example through GraphQL), User.AddRole adds the role as a direct role, and User.RemoveRole answers ROLE_NOT_ASSIGNED.

REST Endpoints for Creating Users and Resetting Passwords​

The REST endpoints of this section are deprecated (identity wave "Identity (password)", configuration key RestDeprecation:Waves:IdentityUsersPassword): every response carries a Link header to the replacing method and, from the first deployment of an environment after the date was set at rollout, the Deprecation header. The sunset date is to be announced; until then there is no Sunset header. Switch to the methods before the sunset; see Deprecated REST Endpoints and Sunset Dates. When you switch the reset: the method User.ResetPassword sends no password-reset e-mail yet (it follows with a later release); the REST endpoint does.

Creating a user and the administrator password reset are facades over the methods of the user type as well:

REST endpointMethod
POST {tenantId}/v1/usersUser.CreateUser
POST {tenantId}/v1/users/ResetPasswordUser.ResetPassword

Routes, request and response bodies and status codes stay the same; the password still travels only in the request body (a password in the URL is refused with 400, see Password Management). The endpoint calls the method in the same process of the Identity Service, so the password never reaches the message bus. These two methods carry a password, but the REST endpoints work whatever Methods:Identity:EnablePasswordMethods says: the switch only decides whether the Identity Service offers the methods on the message bus. With the default (false) REST, octo-cli and Refinery Studio keep creating users and resetting passwords, while a call through GraphQL answers METHOD_HANDLER_NOT_AVAILABLE (see Identity Methods).

What REST callers notice:

  • An administrator reset lifts the lockout. LockoutEnd is cleared and the failed-sign-in counter is set to 0, as the method does. Before, the user stayed locked out until the lockout time had passed. The user still gets the password-reset e-mail after a successful reset.
  • Audit. Every REST call writes one event log entry Identity.Method, on success and on refusal: for a create with the user name and whether a password was given (withPassword), for a reset with lockoutLifted. The password is never part of it.
  • Log line of a reset. The "Password changed" log line names the path MethodResetPassword (before: AdminResetPassword) and the acting user by the user name of the token; a service client stays client <id>.
  • Trimmed input. Create trims the user name and the e-mail address and stores a blank e-mail address as no address.
  • Unexpected failures answer 500 with the message "Creation of user failed." or "Reset of password failed." and never the text of an exception.
  • resetPasswordOnLogin when creating. The method has no parameter for this flag; the endpoint sets it on the new user right after the method stored it. If that second write fails, the answer is 500 "The user was created, but ResetPasswordOnLogin could not be set." instead of 200: the user exists, but without the flag; set it with PUT {tenantId}/v1/users/{userName}.
  • IdentityApiAuthorization:RoleEnforcement=Warn (not the default): a caller without UserManagement is now refused with 403 instead of being let through with a warning.

Rules for Groups, Mappings and Role Definitions​

A user administrator cannot get around the rules above through groups, external tenant user mappings or role definitions. The same guard judges these changes, with the same status codes and code values (self-grant, role-not-held, last-administrator), for the REST endpoints under /groups, /externalTenantUserMappings and /roles and therefore for octo-cli, Refinery Studio and the MCP server:

  1. No self-grant. A change is refused when it gives roles to the caller: adding the caller's own user to a group that carries roles, adding roles to a group the caller belongs to (directly or through a parent group), adding a child group that carries roles below a group the caller belongs to, and changing the roles of the external tenant user mapping that serves the caller (a cross-tenant xt_ user). A client-credentials caller is refused the same way for its own client: adding its own client to a group that carries roles, adding roles to a group its client belongs to (directly or through a parent group) and nesting a group that carries roles below such a group. Removing is never a self-grant; removing a user or a child group from a group is still subject to the last-administrator check (rule 3). Adding yourself to a group without any role is not a grant.
  2. Grant only what you hold. Adding a role to a group, adding a user, a client or a child group to a group that carries a built-in role (also through nested groups), and creating or changing an external tenant user mapping with a built-in role is only possible when the caller holds every built-in role that is granted. Custom roles are free (apart from self-grant), and a caller holding UserManagement may grant app roles it does not hold (exception above); in a group that carries both, only its platform roles must be held and roleNames lists only those. Adding someone who already is a member changes nothing and is not judged.
  3. The last user administrator stays. A change is refused (409) when afterwards no user holds UserManagement, judged over direct roles, groups, nested groups, mappings and cross-tenant users. This covers removing a user or a child group from a group, replacing the roles of a group, deleting a group, and changing or deleting a mapping. Clients do not count.
  4. Built-in roles keep their name. A built-in role (for example UserManagement or SecretManagement) can neither be renamed nor deleted: PUT /roles/{name} with another name and DELETE /roles/{name} answer 409 with code = built-in-role. Custom roles can be renamed and deleted as before; saving a built-in role with its own name is not a rename.
RefusalAnswer
Self-grant403, application/problem+json, code = self-grant
Built-in role not held403, code = role-not-held, roleNames
Last user administrator409, code = last-administrator
Rename or delete of a built-in role409, code = built-in-role, roleNames

Nothing is written when a call is refused, and every refusal is recorded as the event Identity.RoleChangeRefused. Existing memberships, group roles and mappings are not changed. The direct roles of clients follow the rule "grant only what you hold". Not covered by these rules: the role assignment of the first administrator of a new tenant, blueprint seeds, the creator grant of a scratch tenant, cross-tenant admin provisioning and the groups assigned at sign-in, which do not run through these endpoints.

The First Administrator of a New Tenant​

When a tenant is set up and its first administrator is created (setup page of the identity service or the setup API), the administrator receives a set of direct roles and, in addition, becomes a member of the group TenantOwners. The group carries every built-in role, SecretManagement included, among them roles the direct set does not contain, such as DataModelManagement and the StreamData* roles.

Because of the rule "grant only what you hold", the membership is what lets the first administrator add other people to TenantOwners and hand out every built-in role. Without it the administrator could not give anybody a role the administrator does not hold. Creating the administrator is not changed otherwise: the direct roles stay, and SecretManagement is also granted directly.

  • A tenant whose bootstrap data has no TenantOwners group keeps only the direct roles; the setup logs a warning and does not fail.
  • The first administrator of an existing tenant is not changed and keeps the roles it has. The TenantOwners group of an existing tenant does gain SecretManagement when the identity service starts, so its current members hold it too; a user who holds all roles of TenantOwners (for example a member of the group, such as a provisioned administrator of the parent tenant) can add further members.
  • The setup is one of the flows that are not restricted by the role rules, see the limits above.

Roles for Clients​

Roles are not limited to users. An OAuth client (machine-to-machine identity) can also be assigned roles — directly or via group membership — and its client_credentials access token then carries the resolved role claims in the same shape as a user token. This lets a service call role-protected endpoints. See Client Roles and Group Membership.

Rules for the Roles of Clients​

Whoever can manage clients (TenantManagement or UserManagement) could otherwise give a client a role they do not hold, for example UserManagement, and then act as that client. Granting roles to a client therefore follows the rule "grant only what you hold":

  • PUT /clients/{id}/roles/{roleName} (octo-cli AddClientToRole) and PUT /clients/{id}/roles (octo-cli UpdateClientRoles) refuse a built-in role the caller does not hold: 403, application/problem+json, code = role-not-held, roleNames lists the refused roles. A caller holding UserManagement may grant app roles it does not hold; platform roles must still be held (exception for app roles).
  • Custom roles are free. Only the roles a call adds are judged: keeping a role the client already has and removing a role (DELETE /clients/{id}/roles/{roleName}) are always possible.
  • PUT /clients/{id}/roles checks every role id first; an unknown id answers 404 and changes nothing.
  • No self-grant for clients. A client-credentials caller is judged with the roles of its own client and is "self" for that client, as a user session is for its own user. Adding a role to its own client (AddClientToRole, UpdateClientRoles) answers 403 with code = self-grant, app roles included; so do the group changes that would give its own client a role (see the rules for groups). Granting roles to other clients and users and removing its own roles stay allowed. A consequence: the creator client of a scratch tenant (member of TenantOwners) cannot give itself an app role a blueprint seeds later; a user administrator or another client grants it.
  • There is no last-administrator rule for clients: clients never count as user administrators.
  • Adding a client to a group follows the rules for groups, through REST and through the method Group.AddMember. There is no type method that changes the direct roles of a client.
  • Every refusal is recorded as the event Identity.RoleChangeRefused. Clients that the platform services create and update among themselves (service accounts of adapters, client mirroring) do not go through these endpoints and keep their roles.

Stream-Data Roles​

Reading stream data (time series in the archives) through the asset repository API requires one of the tenant roles StreamDataReader, StreamDataWriter or StreamDataAdmin. The check covers every stream-data read query of the GraphQL API: the transient queries simple, aggregation, groupingAggregation and downsampling, and the persisted streamDataQuery with its rows and aggregations. Archive metadata (for example rollupsFor, coverageFor, recomputeJobsFor) is not checked.

The role is the first of two checks. When the tenant has data permissions that protect the CK type of the archive, the caller also needs a full Read grant on that type; an owned-only grant is not enough, because stream rows carry no creator. Without it the read is refused (Access denied: missing data permission 'Read' …), whatever the role mode. Tenants without data policies only need the role.

The check is staged per environment with the asset repository setting StreamDataReadAuthorization:RoleEnforcement (environment variable OCTO_STREAMDATAREADAUTHORIZATION__ROLEENFORCEMENT):

ModeBehaviour
OffNo role check (behaviour before the check existed).
Warn (default)The read goes ahead; the asset repository logs a warning with tenant, query kind, subject and client id (once per caller, tenant and query kind within StreamDataReadAuthorization:WarnLogInterval, default one hour).
EnforceThe read is refused with the GraphQL error code StreamDataReadRoleRequired; nothing is read.

Who is affected. Only callers that read stream data through the asset repository API with their own token: users who read time series in Refinery Studio, Grafana, Excel or a solution frontend, and app clients or service accounts that call the GraphQL API with a client-credentials token. Pipelines that the mesh adapter runs read archives inside the adapter and do not pass this check.

Who holds the role already.

  • Members of the group TenantOwners (all StreamData* roles), among them the first administrator of a tenant and the creator client of a scratch tenant.
  • Pipeline service accounts of the communication adapters: the Communication Controller adds StreamDataReader to the service accounts it manages, and the Identity Service grants it to older service accounts (client ids starting with octo-pipeline-sa-) at every tenant setup. No manual grant is needed for them once Communication Controller and Identity Service versions with this grant run and a reconcile (for example a workload deploy) or a tenant setup has happened since; until then a pipeline service account may lack the role, and its reads through the API fail under Enforce. Before switching to Enforce, confirm that the service accounts hold StreamDataReader and that the Warn log names none of them.

Everybody else who reads stream data needs the role before an environment switches to Enforce. Use the Warn log to find them, then grant the role directly or, better, through a group:

octo-cli -c AddUserToRole -un "jane.doe" -r "StreamDataReader"
octo-cli -c AddClientToRole -id "my-reporting-client" -r "StreamDataReader"

Managing Roles​

# List all roles
octo-cli -c GetRoles

# Create a custom role
octo-cli -c CreateRole -n "DataAnalyst"

# Assign role to user
octo-cli -c AddUserToRole -un "john.doe" -r "DataAnalyst"

# Remove role from user
octo-cli -c RemoveUserFromRole -un "john.doe" -r "DataAnalyst"

# Delete a role
octo-cli -c DeleteRole -n "DataAnalyst"

Data Permissions​

Roles also drive data permissions: policies that decide which Construction Kit types and entities a role may read or change (see Settings > Data in Refinery Studio). They are applied per request with the identity and roles of the caller and cover:

  • the GraphQL and REST APIs,
  • runtime-data exports (ExportRtByQuery, ExportRtByDeepGraph): the export job runs with the identity and roles of the user who requested it, so the file contains only the rows, and in a deep graph export only the associations, that this user may read. A caller without identity is rejected with 401. The result belongs to the initiating subject: another user of the same tenant who requests the download gets 403. A client-credentials token is evaluated as its client with the client's roles and is never treated as a system caller.

A repository dump is the exception: it is a whole-tenant backup, bypasses data permissions by design and is protected by the role TenantManagement instead. See Repository Backup & Restore.

Credential Material and Export​

The password hash, the security stamp and the two-factor tokens of a user (the authenticator key and the recovery codes) are Secret attributes of the System.Identity model (PasswordHash, SecurityStamp, UserTokens; since System.Identity 2.27.0). The Secret ownership has two effects (see Blueprint Ownership):

  • an export (ExportRtByQuery, ExportRtByDeepGraph, export as template) never contains them; all other user attributes (name, e-mail, phone number, TwoFactorEnabled, ...) are exported as before,
  • a blueprint re-apply keeps the stored values of an existing user.

Consequence for a tenant clone: since System.Identity 2.28.0 a tenant copy with ExportRt and ImportRt does not carry users at all. The export still writes System.Identity/User entities (without the credential material), but UserName and Email are MethodOnly (see below; more attributes since 3.0.0), so ImportRt refuses every file that contains a user: the whole import fails before anything is written, with message OCTO-CK139 naming each user and attribute. Leave the users out of the export, or remove them from the file, and bring them across in one of the ways described in Moving Users to Another Tenant. Earlier versions (up to 2.27.0) imported the users without password and two-factor material; that is no longer possible.

Moving Users to Another Tenant​

There is no export and import of users. Users reach another tenant in one of these ways; passwords and two-factor keys never travel through an export, a file or an API.

WayWhat arrives in the target tenantLimits
Copy the whole tenant with a repository dump and restore (Restoring from a Backup)All users with their roles, group memberships, external logins and their (encrypted) password hashes and two-factor keys, together with all other data of the tenantAll or nothing: the restore replaces the whole target database. Needs the role TenantManagement (a dump bypasses data permissions). In the same environment passwords and two-factor keys keep working. From another environment they arrive unreadable unless the source key is added to the target key ring: the users then reset their password and set up two-factor authentication again (see Restore Across Environments).
Create the users again through the Identity Service (octo-cli -c CreateUser, AddUserToRole, AddUserToGroup; Refinery Studio; REST POST {tenantId}/v1/users)The users you create, with the direct roles and group memberships you assignOne call per user and per role or group; there is no bulk or file import. Without -p the user gets the welcome mail without a password and sets one through the link; with -p an administrator chooses the initial password. Two-factor authentication is set up again by each user. List the source users with GetUsers (name, e-mail, external logins; no roles) and read their direct roles in Refinery Studio or with REST GET {tenantId}/v1/users/{userName}/directRoles. Role rules apply (a caller can only grant built-in roles it holds, see Rules for Changing the Roles of a User).
Give users of a parent tenant access with a cross-tenant user mapping (Cross-Tenant Authentication; CreateExternalTenantUserMapping, CreateAdminProvisioningMapping)No copy: the user keeps the account and password of the home tenant and gets roles in the target tenant through the mappingOnly for users of an ancestor tenant of the target (a child tenant).
External sign-in with self-registration (Identity Providers)A new user account on the first sign-in through Google, Microsoft, Entra ID and the other configured providersOnly for users who sign in through an external provider with AllowSelfRegistration; the new account has no roles until an administrator (or an e-mail domain group rule) grants them.

Instead of the REST API, a tool can create the users with the method User.CreateUser (the same rules; it answers USER_ALREADY_EXISTS for a name or e-mail address that exists in the target tenant). It is a method with a password parameter, so it is only available where the Identity Service runs with Methods:Identity:EnablePasswordMethods. A user-started ImportRt or a blueprint cannot create users.

Access Modifiers of the User Attributes​

Since System.Identity 2.28.0 (the first ckLanguage: 2 release of the model) the security-relevant attributes of a user carry access modifiers. They close the generic data path (GraphQL and ImportRt) to credential and lockout data:

AccessAttributes of UserEffect
HiddenPasswordHash, SecurityStamp, UserTokensNot in GraphQL output or input, never exported; an import refuses a value for them.
MethodOnlyUserName, Email (since 2.28.0); since 3.0.0 also NormalizedUserName, NormalizedEmail, EmailConfirmed, PhoneNumberConfirmed, TwoFactorEnabled, LockoutEnabled, LockoutEnd, AccessFailedCount, ResetPasswordOnLogin, Claims, UserLogins, PreferredChannelBindingIdReadable, but not writable through generic GraphQL or an import.

LockoutEnd and AccessFailedCount were ReadOnly (not writable through generic GraphQL, but importable) up to 2.30.0. The fields of the next section are the ones that moved to MethodOnly with 3.0.0, plus the relations, which the platform protects by itself; all other user attributes (first and last name, description, phone number) behave as before.

  • Reading: a GraphQL query for a user no longer returns the three Hidden attributes; all MethodOnly attributes are still readable.
  • Writing: a generic GraphQL mutation cannot set a MethodOnly attribute, and ImportRt, a blueprint seed or a migration step that carries a value for a Hidden or MethodOnly attribute is refused before anything is written (message OCTO-CK139, see CK language 2 message codes). A ReadOnly attribute of another model can still be set by an import.
  • How users are changed: through the Identity Service itself, that is its REST API (sign-in, password change and reset, two-factor setup, user administration) and the tools built on it (Refinery Studio, octo-cli). The service writes through its own repository, which the access modifiers do not restrict. The type methods of users, groups, clients and data permissions are declared since 2.29.0, see Identity Methods; no method changes UserName or Email yet.
  • Tenant data of older tenants: nothing is migrated; the stored values are unchanged, only the generic access to them closes.

Fields Only the Identity Service Writes​

The following user fields and relations are written only by the Identity Service (its REST API, the identity methods and the tools built on them). They stay readable through GraphQL, but the generic paths refuse to write them for every caller:

KindFields and relations
Attributes of User (access: MethodOnly in the model since System.Identity 3.0.0)NormalizedUserName, NormalizedEmail, EmailConfirmed, PhoneNumberConfirmed, TwoFactorEnabled, LockoutEnabled, ResetPasswordOnLogin, Claims, UserLogins (external logins), PreferredChannelBindingId, LockoutEnd, AccessFailedCount (and UserName, Email since 2.28.0)
Relations (in both directions; a platform rule, see below)role assignment (AssignedRole: user, group or client to role), group membership (GroupMember) and group nesting (ChildGroup), client impersonation (MayActAs), role grants of data permissions (GrantsPermission)
  • Refused paths: generic and typed GraphQL create and update (also the relations in the input, from either end), runtime-query rows, ImportRt and the pipeline nodes that write entities or relations (ApplyChanges@1/@2 and the others). For the attributes the generic access rules of access modifiers apply: GraphQL answers ATTRIBUTE_NOT_WRITABLE, the typed inputs do not offer the fields, an import (user-started or system import such as a blueprint seed) is refused as a whole before anything is written (message OCTO-CK139), a pipeline node refuses the whole batch with RT_ATTRIBUTE_WRITE_RESTRICTED. For the relations the platform rule applies: GraphQL answers ATTRIBUTE_NOT_WRITABLE with the extension reason: identity-owned; a user-started import is refused as a whole (message OCTO-CK140); a pipeline node refuses the whole batch with the cause IDENTITY_OWNED, for relations on create and delete. Nothing is changed.
  • Lockout fields: LockoutEnd and AccessFailedCount were ReadOnly until 2.30.0 and are MethodOnly since 3.0.0: for other models a ReadOnly value stays importable, a MethodOnly value does not, so a user-started ImportRt cannot reset a lockout.
  • Leaving a field out changes nothing either: a user-started ImportRt with Upsert that omits a MethodOnly or Hidden attribute (these ones, but also any other model's) keeps the stored value, also with the blanking policy that otherwise lets an import clear values (blueprint seeds keep their blanking rules).
  • Not affected: the Identity Service itself (REST API, methods, sign-in, external login, self-service, cross-tenant provisioning), a pipeline that implements a System.Identity method (its own method-handler run), blueprint seeds and blueprint updates of relations (the TenantOwners group of the bootstrap blueprint keeps its roles; a seed that sets one of the attributes above is refused, no blueprint seeds a user), tenant dump and restore. Refinery Studio and octo-cli use the REST API and work as before.
  • How to change them instead: roles with PUT /users/{user}/roles or User.SetRoles/AddRole/RemoveRole; group members with the group endpoints or Group.AddMember/RemoveMember; the second factor of a user with POST /users/{user}/disableTwoFactor or User.DisableTwoFactor (the user can also switch it off in the own account settings); ResetPasswordOnLogin with POST/PUT /users; the preferred notification channel in the own account settings. The normalized names follow the user name and e-mail; external logins are added at sign-in and moved by a merge.
  • Why the attributes are in the model and the relations are not: since System.Identity 3.0.0 the attributes carry access: MethodOnly (before, tightening them was a major version change of the model, so the platform enforced the same rule from a list; see the release notes). The relations stay a platform rule because the Construction Kit access model has no write restriction for associations: access exists only on attributes.

Access Tokens​

When a user authenticates, the Identity Service issues a JWT access token containing:

ClaimDescription
subUser ID
preferred_usernameUsername
tenant_idThe tenant the user logged into
allowed_tenantsList of tenants the user may access
roleList of effective roles (direct + group-inherited)
home_tenant_idFor cross-tenant users: their home (parent) tenant

Services compare the {tenantId} in the request path with the token's tenant_id claim, for user and client-credentials tokens alike; allowed_tenants only lists the tenants a user can switch to. See Tenant Authorization and Tenant Generations.

In Refinery Studio, users and roles are managed under Access > Users and Access > Roles: see the User Guide and Roles.