Acls-v10.xml
From ControlTier
The acls.xml file lives in the $CTL_BASE/etc directory. It is used to specify the commands that are authorized for particular user roles.
The acls.xml consists of one <acls> element containing one or more <acl> elements. The DTD is available in the $CTL_BASE/etc/acls.dtd file.
Contents |
ACL Lookup
By default no role is authorized to execute any command. This means that only matching entries in the acls.xml allow authorization.
When a user attempts to execute a command (via the CTL command-line) or a Job (via Jobcenter), then the specific context of the command is compared to the entries in the acls.xml for roles that the user has.
- For each role that the user has, lookup #acl entries in the file for that role.
- For each acl entry, if it matches the context of the command, then the command or Job is authorized to execute.
- If no #acl entries exist for any roles, or no matching entries for the context are found, then the context is not authorized.
Keep in mind when specifying the ACL entries that they specify which contexts are authorized for that specific role.
Context
Each execution in CTL or Jobcenter has a context consisting of several pieces of information:
| Name | Description |
|---|---|
| depot | Name of the project |
| script | A boolean value indicating whether the execution is an ad-hoc script or not |
| type | Name of the Object's Type |
| object | Name of the Object |
| command | Name of the command |
| module | Name of the Type for which the command is actually defined |
The context parts type, name, command, and module are only used when a DefinedCommand is executed. Otherwise the script context part is set to true to indicate that an ad-hoc command is being executed.
In addition to these context components from the execution context, the Time and Day can be used to allow different ACL entries to match at different times.
object vs. static context
Commands are also executed in either 'object' or 'static' context.
In 'object' context, then the type and object are specific values. In 'static' context then both type and object are null.
- Note: for ControlTier 3.4.9 and earlier, the following requirements for 'static' context apply:
When authorization for 'static' context occurs, the type and object values in the ACL entry must be equal to * (asterisk) to match.
This means that an ACL entry without * both type and object will not match when a 'static' command is executed. You must specifically add an ACL entry to match this 'static' context. You can then filter which static context commands are matched using the #command element.
Matching
An ACL entry is considered to match the context if every component in the #Context as well as the Time and Day section successfully match the appropriate value in the #acl entry.
The Time and Day (see the #timeandday section) are matched using the following values:
- Day of week
- Numeral indicating the day of the week, from 0-6 for Sunday-Saturday.
- Hour of day
- Number indicating the hour of the day, from 0-23.
- Minute of hour
- Number indicating the hour of the hour, from 0-59.
Regular Expressions
Most of the attributes specified in the acls.xml use a Regular Expression to match the specific execution context against the ACL entry in the file. (See [RegularExpressions]).
The default value is usually "*" which will match any value.
It may be useful for you to understand this idiom of regular expressions:
Negative Match
To specify a regular expression that matches every string that does not contain another string, use the Negative Lookahead Assertion:
-
(?!…) - Matches only when the following string portion does not match the value in the
…section.
Examples:
| regular expression | meaning |
|---|---|
^ | Matches beginning of string |
$ | Matches end of string |
^.*$ | Matches any string |
^.*Suffix$ | Matches any string that ends with "Suffix" |
^(?!.*Suffix$).*$ | Matches any string that does not end with "Suffix" |
^.*Text.*$ | Matches any string that contains "Text" |
^(?!.*Text.*$).*$ | Matches any string that does not contain "Text" |
Elements in the acls.xml file
All elements specified below are required for each #acl entry. See the #Default Contents.
acl
Attributes:
| Name | Value |
|---|---|
| description | User-specified description of the ACL entry |
Contains Elements:
accessto
This element specifies which Command name and Module name that a role is allowed to access, and/or whether the role is allowed to execute ad-hoc scripts.
Contains Elements:
command
Specifies the command and Module name for the acl entry.
Attributes:
| name | value |
|---|---|
| module | Regular expression matching a module name (module context component) |
| name | Regular expression matching a command name (command context component) |
script
Specifies whether ad-hoc commands are allowed or not.
Attributes:
| name | value |
|---|---|
| allowed | "true" or "false" (script context component)
|
by
Specifies which User Role the ACL entry applies to. This element contains the single #role element.
role
Specifies the name of the User Role.
Attributes:
| name | value |
|---|---|
| name | Name of the role. |
using
Contains one element, context
context
Specifies the depot, type, and object context components.
 |
In ControlTier 3.4.9 and earlier, the type and object can be regular expressions to match an 'object' context command, or they must both be * to match a 'static' context command. (See #object vs. static context) |
Attributes:
| name | value |
|---|---|
| depot | Name of the project (depot context component) |
| type | Name of the Object's Type (type context component) |
| name | Name of the Object (object context component) |
when
Contains one element, #timeandday.
timeandday
Specifies which times during the day and on which days of the week that the ACL entry applies.
Attributes:
| name | value |
|---|---|
| day | Either "*" which matches all days, or a comma-separated list of day numbers (0-6 for Sunday-Saturday).
|
| hour | Either "*" which matches all hours, or a comma-separated list of hours of the day (0-23).
|
| minute | Either "*" which matches all minutes, or a comma-separated list of minutes of the hour (0-59).
|
Default Contents
The default acls.xml contains the following:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE acls SYSTEM "file:///[CTL_BASE]/ctl/etc/acls.dtd">
<acls>
<acl description="admin, access to any command using any context at anytime">
<accessto>
<command module="*" name="*"/>
<script allowed="true"/>
</accessto>
<by>
<role name="admin"/>
</by>
<using>
<context depot="*" type="*" name="*"/>
</using>
<when>
<timeandday day="*" hour="*" minute="*"/>
</when>
</acl>
</acls>
This specifies that users with the "admin" role are authorized to execute any command, and does not allow any commands to be executed for users without the "admin" role.
| ||||||||||||||
