Skip to content

Principals and ACLs ​

Who you are to Situate, and how Situate and the operating systems it manages decide what you can do. This reference covers:

  • Principals: the identity Situate carries for a logged-in user.
  • Situate ACLs: access control on workflows, groups, assets, calendars and other Situate objects. Situate enforces these.
  • File ACLs: the permissions of files and directories on an asset, as Situate reports them. The operating system enforces these; Situate only describes them.

1. Principals ​

When you log in, Situate builds a principal: a signed record of who you are. Every request you make, and every workflow step run on your behalf, carries it.

1.1 What it contains ​

PartWhat it is
Login userThe account the server authenticated you as, through its native authentication service (Unix, PAM or Active Directory), with that account's native groups
Situate userYour Situate user, created on first login if it doesn't exist
Situate groupsEvery Situate group you belong to, including nested groups. The first is your default group, which becomes the group owner of things you create
PoliciesCapabilities granted by your roles (section 1.4)
IdentitiesStored OS accounts you can run as on assets. The principal holds only a reference to each password, kept in Situate's vault; the password itself never travels in it

You can see your own principal by right-clicking the domain and selecting Login Principal (see Viewing Your Login Principal). It shows your users, groups, policies and the names of your identities.

1.2 Principal names ​

Users and groups are written:

<name>@<authority>/<type>
  • type is u for a user and g for a group.
  • authority says where the name comes from:
AuthorityMeaning
sit-<domain>A Situate user or group, e.g. dave@sit-acme/u, developers@sit-acme/g
PAM-localUnix accounts validated through PAM on a host that isn't in a directory domain. The default for every such Linux host. Situate assumes the same accounts exist on every PAM-local host, kept in step by some means outside Situate
PAM-<name>The same, for a named set of hosts, e.g. PAM-acme. Use it when different sets of hosts have different accounts
AD-<AD domain>An Active Directory account or group. The name is the AD domain the machine was joined to, which is usually not the company's public domain: a company at acme.com might have AD-acme.local; a machine joined to ee.engineering.purdue.edu uses AD-ee.engineering.purdue.edu. For domain-joined hosts, Unix or Windows
WinNT-<workgroup>A Windows workgroup account
G-<group>Accounts shared by an ad-hoc group of hosts, e.g. situate@G-webrail/u. For hosts kept stand-alone (often for security) that share the same service accounts, usually synchronized by hand. A host can belong to several such groups
H-<agent id>An account local to one host, on Unix or Windows. The agent id is the GUID the agent writes to its agent.id file when installed (not the asset id, and not the host name). H-<hostname> is still accepted for backward compatibility but is deprecated
E-<endpoint id>Credentials for a Situate endpoint, such as a database or a REST service. The authority scopes those users to that endpoint
BUILTINPseudo-principals used only inside ACLs: owner, groupowner, everyone (and mask in file ACLs)

The same person has several names. Dave might be dave@sit-acme/u to Situate and dave@AD-acme.local/u as his login user (the server authenticates against Active Directory). He might also hold identities situate@G-webrail/u for the stand-alone webrail hosts and report_ro@E-<id>/u for a reporting database endpoint. An ACL entry that names any of them applies to him (section 3.2).

In a principal, an @ inside a name is written ;: the user jo@example.com appears as jo;example.com@sit-acme/u.

Agent id and asset id. Each agent, when installed, writes a GUID to its agent.id file: the agent id. An agent can belong to more than one Situate domain. When it's added to a domain, the domain manager creates an asset record whose key is the asset id; the record also stores the agent id. H- authorities use the agent id.

How an authority is validated. Each authentication service set up in Situate names an asset that belongs to it. To validate jeff@G-webrail, Situate goes to that asset (say xonaweb2) and checks the account there, for example with a password-entry lookup.

1.3 Which account runs on an asset ​

Work on an asset (a remote exec, a file transfer, browsing files) runs as an OS account on that asset, never as Situate. Two agent settings decide which accounts fit. On Unix they're in /etc/situate.conf; on Windows they're registry values under HKEY_LOCAL_MACHINE\SOFTWARE\Situate\SituateAgent:

SettingMeaningExample
AUTHThe authority the agent validates logins and passwords against. A successful login of dave is dave@<AUTH>AUTH=AD-acme.local
AUTHLOGINA comma-separated list of the authorities whose identities are valid on this agentAUTHLOGIN=G-webrail,G-secteam

The agent also accepts identities for its own H-<agent id> (and the deprecated H-<hostname>).

The agent goes through the identities in your principal in order and uses the first one whose authority it accepts. The operating system then decides what that account may do. Work against an endpoint uses the identity for that endpoint's E-<id> authority in the same way.

  • Only the first fitting identity is used. If you have both dave@AD-acme.local/u and svc_batch@AD-acme.local/u, every domain-joined asset runs you as whichever comes first; the other is never chosen. The same applies when one asset supports several of your authorities, e.g. both a G- group identity and a PAM-local one. To run as a different account, use a workflow with that run-as user (section 1.5).
  • Identities granted through roles can be placed ahead of your own.
  • If none of your identities fits the asset, the work fails with "no valid user for this host" (no native login). Add an identity for one of the asset's authorities.
  • The first time you log in, your login password is saved as an identity, so you can usually run as yourself.

1.4 Policies ​

PolicyMeaning
APACan approve a workflow whose user or asset is a variable, so it isn't known until the workflow runs. Normally only Administrators can approve these
NAPCan't approve workflows
UVRSees only the workflows they can execute
QACHas queue administration controls
WRUThe run-as user given to workflows this user creates
WAGThe group owners given to workflows this user creates
NUGThe default group for new users
CHRCan create a help report
TTrial run

Members of Administrators always have QAC and CHR.

1.5 Run-as and the effective user ​

A workflow can have a run-as user ("Execute As"). It then runs as that user: steps use that user's Situate groups for ACL checks and that user's identities on assets. At any point in a run, the user whose principal is in force is the effective user.

Older workflows mark run-as with the SUID flag on their ACL. They run as the first Situate owner in the ACL, or the user named in the flag.


2. The ACL string ​

Situate ACLs and file ACLs share one format:

<flavor>`<owners>`<group owners>`<flags>`<inheritance>`<entry>`<entry>...

Fields are separated by a backtick (`). Positions are fixed, so an empty field still has its backticks.

FieldContents
flavors for a Situate object. File ACLs: section 4.1
ownersComma-separated principal names
group ownersComma-separated principal names
flagsComma-separated flags
inheritanceEmpty on Situate objects. On file ACLs, section 4.5
entry<type>,<principal>,<right>,<right>,...

An entry's type is A (allow) or D (deny); file ACLs add M and scopes (section 4.3). An entry with no rights grants nothing.


3. Situate ACLs ​

3.1 Rights ​

RightApplies to
Read, Write, ExecuteEverything
Create, Update, DeleteAsset and endpoint groups

Rights are case-insensitive in Situate ACLs.

3.2 How a check is decided ​

  1. Administrators are always allowed. The exception is approvals: an approver must satisfy the ACL even as an administrator.
  2. Calendars have a manager role that is always allowed: CalendarManagers.
  3. Otherwise Situate reads the entries in order, skips any entry that doesn't list the right, and stops at the first one whose principal matches you. A allows; D denies.
  4. If no entry decides, access is denied.

An entry matches you when its principal is:

EntryMatches when
everyone@BUILTINAlways
owner@BUILTINYou are one of the owners in the header
groupowner@BUILTINYou are in one of the group owners in the header
Any other nameIt names your login user, your Situate user, any of your native or Situate groups, or any identity you can run as

Entries for accounts local to one asset (@H-…) never match.

Order matters. A deny only takes effect if it comes before the allow that would otherwise match.

Default ACLs aren't POSIX permissions, though they're built from Unix-style modes. Each mode digit becomes an entry for owner, group owner and everyone, and the first matching entry decides. With mode 0070, an owner who is also in the group owner still gets Read: the owner entry has no Read, so it's skipped, and the group entry matches.

3.3 Default ACLs ​

ObjectDefault
WorkflowYou own it; your default group is the group owner (or the groups in your WAG policy). Mode 0755, or 0775 if your default group isn't SituateUsers. With a WRU policy, it runs as that user
Workflow group, calendar, organization, dashboardMode 0755, or 0775 if your default group isn't SituateUsers
CMDB itemMode 0775
LockMode 0644 or 0664
Asset or endpoint groupOwner and group owner get Create, Update and Delete; everyone gets Update
User or service accountGroup owner is Administrators. The owner gets Read, Write and Execute; everyone gets Read; there's no group owner entry (mode 0704). The owner is whoever created the account in the UI or API, or, for the shadow account made at first login, the user's native login

Submitting or importing a workflow gives it a new default ACL. Keeping the original ACL ("preserve ACL") requires an administrator.

3.4 What the rights control ​

Workflows and workflow groups

ActionNeeds
Run a workflowExecute on its group, then Execute on the workflow
View a workflowRead on the workflow and its group
List workflowsRead on the workflow (and Execute with the UVR policy)
Submit into a groupWrite on the group
Copy into a groupRead on the workflow, Write on the destination group
Delete a workflowWrite on the workflow
Cancel a runExecute on the workflow
Enable or disable a triggerWrite on the workflow
Create a groupWrite and Execute on the parent group (Administrators only at the top level)
Change a groupWrite and Execute on the group
Delete a groupWrite on the group, and Write and Execute on its parent

Only a workflow's own group is checked. Locking down a parent group doesn't restrict the groups beneath it.

Asset and endpoint groups: Create on the parent to create (Administrators only at the top level), Update to change, Delete to delete.

Assets

  • Adding, changing or deleting assets requires the AssetManagers or Administrators group. The asset's own ACL isn't used for this.
  • An asset's ACL limits running work on it only through approvals, when asset approval is turned on: the approver needs Read and Execute on the asset.
  • Otherwise, what a workflow can do on an asset is decided by the operating system, through the account it runs as there (section 1.3).

Changing an ACL is allowed to its owners and to Administrators.


4. File ACLs ​

The ACLs Situate reports for files, directories and filesystem roots describe what the operating system on the asset allows. Situate doesn't enforce them. Browsing and reading files runs as your identity on the asset (section 1.3), and the operating system makes every decision.

4.1 Summary and complete ACLs ​

Where you see itWhat you get
A directory listing, for each entryA summary: lowercase flavor
The ACL of one file or directoryThe complete ACL: uppercase flavor, when it can be read; otherwise a summary
FlavorComplete?SourceContains
uSummaryUnix permission bitsowner, owning group and everyone; SUID, SGID, SVTX, EXTACL
UCompleteUnix: the POSIX ACL, or the permission bits when there's no extended ACLNamed users and groups, the mask, the default ACL
wSummaryWindows, in listingsAllow and deny entries that apply to the object. No scopes, no inherit-only entries
WCompleteWindowsEvery entry with its scope, inherit-only entries, PROTECTED, PARTIAL
NCompleteNFSv4 mount on LinuxLike W: deny entries, scopes, Windows-style rights

A listing on an NFSv4 mount returns u. A full read also falls back to u when you may not read the ACL, and on CIFS, macOS and Solaris filesystems.

4.2 Names in file ACLs ​

  • Names are percent-encoded: %, space, `, ,, |, @ and / appear as %25, %20, %60, %2C, %7C, %40, %2F. Decode them when showing a name. Domain%20Users@WIN-XS/g is "Domain Users" in the domain whose short name is XS.
  • Owners and groups are listed once per authentication service of the agent, because the agent can't tell which service (local files, sssd, LDAP) an account came from: root@AD-acme.local/u,root@H-<agent id>/u,….
  • A Unix user or group with no name on the host appears as its number.
AuthorityMeaning
BUILTINThe pseudo-principals owner, groupowner, everyone and mask. Windows Everyone, CREATOR OWNER and CREATOR GROUP appear as everyone, owner and groupowner
PAM-…, AD-…, G-…, …The asset's authorities (section 1.2)
H-<agent id>Accounts local to this host, on Unix and Windows. On Windows this includes the BUILTIN and NT AUTHORITY accounts: Administrators@H-<agent id>/g, SYSTEM@H-<agent id>/g
WIN-<domain>A Windows domain account in a file ACL: contractors@WIN-XS/g. The domain is the short (NetBIOS) name Windows reports for the account, so it differs from the AD- form
NFS-<domain>An NFSv4 principal from that NFS domain: alice@NFS-corp.example/u
SIDA Windows SID that couldn't be resolved: S-1-5-21-…-1107@SID/u. Usually a deleted account, or an unreachable domain. Its /u means nothing

On a Linux host joined to Active Directory through sssd, names such as domain users@corp.example are normal. They appear as domain%20users%40corp.example@PAM-local/g.

4.3 Entries ​

TypeMeaningPlatforms
AAllowAll
DDenyWindows, NFSv4
MPOSIX mask: a ceiling on named users, named groups and the owning group. Always M,mask@BUILTIN/g,<rights>Linux

A scope may follow the type after /. Letters appear in the order f c i n h.

LetterMeaning
(none)Applies to this object only
fInherited by new files
cInherited by new subdirectories
iInherit-only: does not apply to this object
nInherited one level only
hInherited from the parent directory
Windows "Applies to"Scope
This folder only(none)
This folder, subfolders and filesfc
This folder and subfoldersc
This folder and filesf
Subfolders and files onlyfci
Subfolders onlyci
Files onlyfi
"Only apply these permissions within this container"add n

4.4 Rights ​

FlavorsRights
u, URead, Write, Execute. On a directory: Read lists names, Write creates and removes entries (with Execute), Execute lets a path pass through
w, W, NWindows file rights, e.g. List Folder / Read Data, Create Files / Write Data, Traverse Folder / Execute, Read Attributes, Delete, Delete Child, Change Permissions, Synchronize, and the generic rights Generic Read, Generic Write, Generic Execute, Generic All

4.5 The inheritance field ​

Holds the inherit-only entries, separated by |: they shape new children and don't apply to the object itself.

  • Linux: the directory's default ACL. Files never have one.
  • Windows and NFSv4: the entries with i in their scope.

Everything in the main entry list applies to the object itself.

4.6 Flags ​

FlagFlavorsMeaning
SUIDu, USet-user-ID
SGIDu, USet-group-ID. On a directory, new files take its group
SVTXu, USticky. On a directory, only a file's owner (or root) may delete or rename it
EXTACLuThe file has a POSIX extended ACL, so this summary's groupowner rights are really the mask. Read the complete ACL. Only checked on local filesystems; a u from a network filesystem may be incomplete without saying so
PROTECTEDWDoesn't inherit from the parent directory
PARTIALWContained rare entry types that aren't shown

4.7 Reading a Unix ACL ​

The operating system checks one class for a user, in this order, and stops at the first that applies:

  1. Owner: the owner@BUILTIN entry decides. The mask doesn't apply.
  2. Named user: a <name>/u entry for the user decides, limited by the mask.
  3. Group class: if the user is in the owning group or any named group, access is granted when any of those entries grants it (after the mask). Otherwise it's denied, and everyone is not consulted.
  4. Everyone: everyone@BUILTIN. The mask doesn't apply.

Consequences that often explain a problem:

  • An owner without a right doesn't get it from the group or everyone entries.
  • A mask without Write removes write from every named user and group. This often follows a chmod g-w on a file with an extended ACL.
  • A user in a group with no rights is denied even if everyone has them.

To reach a file, a user needs Execute on every directory on the path, then the right on the file. A path problem is usually one directory without Execute.

New files and subdirectories start from the directory's default ACL, further reduced by the creating program's mode and umask.

Symbolic links report the link's own permissions, not the target's.

Example. getfacl /data/reports:

user::rwx
user:alice:rwx
group::r-x
group:ops:rw-
mask::r-x
other::---
default:user::rwx
default:group::r-x
default:group:ops:r-x
default:mask::r-x
default:other::---

As a complete ACL (one authority shown, line breaks added):

U`dave@PAM-local/u`dev@PAM-local/g``
A/fci,owner@BUILTIN/u,Read,Write,Execute|A/fci,groupowner@BUILTIN/g,Read,Execute|A/fci,ops@PAM-local/g,Read,Execute|M/fci,mask@BUILTIN/g,Read,Execute|A/fci,everyone@BUILTIN/u`
A,owner@BUILTIN/u,Read,Write,Execute`
A,alice@PAM-local/u,Read,Write,Execute`
A,groupowner@BUILTIN/g,Read,Execute`
A,ops@PAM-local/g,Read,Write`
M,mask@BUILTIN/g,Read,Execute`
A,everyone@BUILTIN/u
  • alice's Write is removed by the mask: she can't write.
  • ops is capped to Read, with no Execute: its members can't enter the directory.
  • Everyone else gets nothing.
  • New children get the default ACL, in which ops has Read,Execute.

As a listing summary, the same directory would be a u ACL with EXTACL, and its groupowner entry would show the mask (Read,Execute), not the dev group's rights.

4.8 Reading a Windows ACL ​

  • Order matters. Windows reads entries in order. Matching A entries grant their rights; a matching D entry denies its rights unless an earlier entry already granted them. Explicit entries normally come before inherited ones (h), and denies before allows, so an explicit deny beats an inherited allow and an explicit allow beats an inherited deny.
  • Inherited entries (h) come from a parent folder. Change them there, or protect this ACL.
  • PROTECTED means nothing is inherited.
  • Inherit-only entries shape new children, not this object.
  • Orphaned SIDs (@SID) belong to accounts that no longer exist. They affect no current user, but often show where access was meant to come from.
  • Traversal: by default Windows doesn't require rights on the folders along a path. A missing Traverse Folder / Execute on a parent usually doesn't block access below it.
  • Administrators may hold privileges that override the ACL (taking ownership, backup and restore).
  • An object with no DACL at all grants everyone full access; it's shown as A,everyone@BUILTIN/u,Generic All.
  • Drive roots and shares report no ACL.

Example on a Windows host in the XS.local domain (NetBIOS name XS) (line breaks added):

W`Administrators@H-<agent id>/g`Domain%20Users@WIN-XS/g``
A/fcih,owner@BUILTIN/u,Generic All`
A/fch,SYSTEM@H-<agent id>/g,Traverse Folder / Execute,List Folder / Read Data,...`
D/f,contractors@WIN-XS/g,Create Files / Write Data,Delete`
A/fch,Users@H-<agent id>/g,Traverse Folder / Execute,List Folder / Read Data,Read Attributes,...`
A,S-1-5-21-1004336348-1177238915-682003330-1107@SID/u,List Folder / Read Data
  • The owner of any new file or subfolder gets full control (an inherited CREATOR OWNER entry).
  • contractors may not write or delete in this folder, or in files created in it.
  • Local Users may list and read, inherited from the parent.
  • The last entry belongs to a deleted account.

4.9 NFSv4 ACLs ​

They read like Windows ACLs: ordered allow and deny entries, scopes, and the same rights names.

  • Principals carry their NFS domain. A domain that doesn't match the client's idmapping configuration shows up as users the server and client disagree about.
  • A Linux NFS server translates its POSIX ACLs to NFSv4. The result is correct but noisy: extra entries and generated denies. Read it for effect, not intent.

4.10 What a file ACL can't tell you ​

  • Whether a user is in a group. ACLs name groups, not their members. If access depends on membership, say so.
  • Everything else that decides access: read-only mounts, SELinux or AppArmor, share permissions on Windows shares, root and Windows administrative privileges. The error the user actually got (not found, denied) is more reliable than reasoning from the ACL.
  • Which account a task ran as. A task's run-as user may differ from the user looking at the file (section 1.5), and so may its access.
  • ACLs on CIFS, macOS and Solaris filesystems. These report permission bits only.

Older agents report only summaries, may show wrong rights in Windows ACLs (every allow reading "List Folder / Read Data"), and may end a Unix rights list with a stray comma.

Workload Automation and Orchestration