Manage security
This page enables administrators to manage access control across different areas of the system, each represented by a hierarchical path identifier (e.g. /projects/bank/assets). Security policies are composed of authorisation rules that can be assigned to individual users or LDAP groups. These rules govern the scope and level of permissions granted, defining what actions users are allowed to perform within the system.
You will need to have admin privileges in order to access this page.
How MintPress authorisation works
MintPress provides a granular, top-down authorisation model for each of its resources. Security is controlled by applying rules to hierarchical paths, and permissions are inherited from parent paths unless explicitly overridden.
This model is built on two core concepts:
- Authorisation rules define what action (
read,update,execute,delete) is allowed or denied on a specific resource path. - Authorisation policies link the rules to users and groups, defining who the permissions apply to.
In this guide, resource refers to anything you can manage in MintPress. It is not the same as the resource concept used by the OpsChain DSL.
How permissions are evaluated
By default, no rules and policies are applied to any user, meaning that no user has any permissions to any resource in MintPress by default.
MintPress evaluates permissions based on the path to a resource and the rules applied to the user. The rule that takes precedence is the one that most closely matches the target resource path.
For example, to execute a change on the soa asset, MintPress will look for the most specific rule that applies to that path:
- If a rule exists for
/projects/bank/environments/dev/assets/soa, that rule will be used, regardless of the rules on its parent paths. - If no rule is found for the asset itself, MintPress will check its parent
/projects/bank/environments/dev, and so on up the hierarchy. - If no applicable
allowrule is found at any level, the action is denied.
When a change is refused on something you can see, MintPress says so with a 403 response, for example You do not have permission to delete the asset. When you cannot see the target at all, the response is 404, so its existence is not revealed. Viewing or listing something you cannot read always answers 404.
Rules on a resource path
A rule whose path ends in a resource - properties, settings, scheduled_activities, git_remotes, templates, workflows, changes, workflow_runs or actions (with or without an action name) - controls that resource rather than the node. A rule on /projects/bank/scheduled_activities applies to the scheduled activities of the bank project and of every environment and asset beneath it. A regular expression rule that includes a resource applies wherever the expression matches.
For a resource on a node, MintPress decides access in this order:
- If the closest node rule for the node denies
read, nothing on the node can be reached. - Otherwise, the closest resource rule for that resource decides what the user can do with it, replacing the node rule's actions.
- Only when no resource rule matches does the node rule apply.
Closeness is compared only between rules of the same kind, so a resource rule on a project takes precedence over a node rule on one of its assets. For example, with a rule granting update on /projects/bank/scheduled_activities and another granting only read on /projects/bank/environments/dev, a user can create and edit the scheduled activities of the dev environment. If the dev rule denied read instead, the user could reach nothing on dev.
Regular expression rules
A rule path can be a regular expression. When MintPress decides which rule is closest, only the path segments that contain no regular expression characters count. A segment such as [^/]+ or env.* does not make a rule more specific.
A group or alternation must not span a /. Write ^/projects/(a|b)/environments/dev rather than ^/projects/a/environments/dev|^/projects/b/environments/dev, or split the pattern into separate rules. A path that breaks this is rejected with must not contain a group or alternation that spans a "/" - split it into separate rules.
Unless you are a superuser, you can only create a rule for a path you can read. The path must also not have a top-level |, or count more literal segments than the fixed text it is guaranteed to start with. Otherwise it is rejected with You do not have permission to manage rules for path: <path>.
Authorisation rule actions
An authorisation rule affects what a user can do at a path. The supported actions are:
read- whether the user can view the target, for example viewing the properties of an environmentupdate- whether the user can create or update the target, for example creating a projectexecute- whether the user can execute the target, for example executing a change or a workflow, approving, continuing or rejecting a step, cancelling a change or workflow run, or sending data to a webhook channeldelete- whether the user can delete the target, for example deleting an environment, or cancelling a change or workflow run
When any of the update, execute or delete actions are enabled, the read action is automatically assigned to the same path.
Resource paths
The path for a resource is the path that it is accessed via the GUI or API. Examples of paths are:
/projects/bank- a project with the codebank/projects/bank/environments/dev- an environment with the codedevthat exists within the projectbank
Under projects, environments, or assets a number of other paths are supported, these include:
/actions/{{action}}, for example/actions/destroyis a path to enforce authorisation on changes and steps with the codedestroy. You can use just/actionsto block access to all actions./artifacts- access to the node's artifacts.readallows viewing, downloading and loading them, andupdateallows storing or uploading them./authorisation_policies- access to the authorisation policies for the given resource.readallows viewing them,updateallows managing them, anddeleteallows deleting them. See which policies are listed./git_remotes- access to the project's Git remotes.readallows viewing them,updateallows creating and editing them, anddeleteallows deleting them.executeallows a running change, agent or actions generation to push commits to them through agit_cloneresource. A rule grantingexecuteon the project, or any path above it, also grants pushing, so to stop runners pushing while leaving other execution alone, add a/git_remotesrule withexecutedisabled./jobs- access to the node's jobs on the system information jobs tab and throughGET /api/jobs.readallows viewing them./notification_channels/{{channel code}}- access to a notification channel created on the node.updateallows editing it anddeleteallows deleting it.updateon/notification_channels/{{channel code}}/event_subscribersallows subscribing to the channel, for example by creating a trigger that uses it. Subscribing to the channels MintPress provides for running a change or a workflow needsexecuteon that change or workflow instead. On a channel that calls a webhook,executeallows sending data to it: creating or changing a trigger that calls the webhook, or enabling one, needsexecuteon the channel's path, and the check is made against the rights of the trigger's creator. Channels created in the system configuration have the path/system_configuration/notification_channels/{{channel code}}./properties/scheduled_activities/settings/templates/workflows/{{workflow code}}, for example/workflows/my-workflowis a path to enforce authorisation on the workflow with the codemy-workflow. You can use just/workflowsto block access to all workflows. This will also block access to the workflow runs belonging to the workflows that match the path.
Top-level paths
Aside from resource-specific paths, you can also secure these top-level paths, which take effect for the entire application:
/admin- access to the admin endpoints and data cleanup endpoints. Some of the operations beneath it can be secured on their own - see administration sub-paths below./authorisation_policies- access to see and manage authorisation policies.readpermission allows a user to view the policies and their rules,updatepermission allows them to be changed, anddeletepermission allows policies and rules to be deleted. Removing a rule from a policy, or changing who a policy is assigned to, needs onlyupdate. This path must be granted explicitly - a rule on the root path does not cover it. A node's/authorisation_policiespath, such as/projects/bank/authorisation_policies, gives access to only some of the policies - see which policies are listed./events- access to view the audit history./log_lines- access to log lines in general. Can be appended with the action to filter log lines for a specific action name. For example/log_lines/update_passwordsis a path that will prevent access to logs for theupdate_passwordsaction./system_configuration- access to see and manage system configuration./workflows- access for workflows in general. Will also manage access to the workflow runs belonging to the workflows matching the path. Can be appended with the workflow code to filter the workflows that the user has access to.
Administration sub-paths
Some of the operations under /admin can be secured individually, so that access to see part of the instance's state does not have to carry the ability to act on it, or to read what it contains:
/admin/pods-readallows listing the pods running in the MintPress namespace./admin/pods/logs-readallows opening an individual pod's log. A pod's log is whatever the process wrote - on a change pod, the output of a change - where the listing is only names and states, so an instance can hand out the pod list without handing out its contents./admin/deployments-readallows listing the deployments making up the instance./admin/deployments/restart-updateallows performing a rolling restart of a deployment./admin/deployments/scale-updateallows changing the number of replicas a deployment runs./admin/deployments/resources-updateallows changing a deployment's memory and CPU requests and limits, and for the MintModel API its concurrency and transformer heap./admin/clusters/cordon-updateallows cordoning and uncordoning a site of a high availability topology.
As elsewhere, the closest matching rule wins, so these paths need no rule of their own to work. A rule granting read on /admin reaches the pod and deployment listings, and one granting update on /admin reaches restart, scale, resources and cordoning. Their purpose is to let you withhold one operation without withholding the rest: a rule denying update on /admin/deployments/scale outranks the broader /admin grant for scaling alone, and leaves restart and everything else under /admin untouched.
Restart, scale and resources are deliberately separate paths rather than one shared check, because an operator trusted to recycle a wedged deployment is not necessarily trusted to resize one.
/admin/deployments has no update operation of its own - nothing writes a deployment resource - so a rule granting or denying update there only ever stands in for the operations beneath it. To withhold just one, write the rule on /admin/deployments/restart or /admin/deployments/scale.
Secret access paths
Access to the values held in the secret vault is controlled separately from access to the properties and settings that reference them. Reading a node, its properties or its settings shows a secret's reference, but never resolves it - so widening a user's read access can never expose the contents of the vault.
Resolving a secret requires the execute action on a secrets path:
/secrets- the root of the secrets hierarchy.executehere resolves any secret anywhere in MintPress.{{node path}}/secrets- every secret belonging to that node, for example/projects/bank/environments/dev/secrets.{{node path}}/properties/secretsand{{node path}}/settings/secrets- only the secrets referenced by that node's properties or settings respectively. A{{node path}}/mintmodel/secretspath is also supported for the secrets referenced by a node's MintModel.
A rule must end at one of these paths to grant anything. execute on {{node path}}/settings, or on a rule with a blank path, grants no secret access at all.
These rules decide whether MintPress will resolve or store a secret for you. MintPress then reads or writes the secret vault with your own secret vault access, so the vault can still refuse the request. See secret vault credentials.
How secret access is inherited
Secrets paths are inherited down the node tree, so granting a team secret access on a project covers every environment and asset beneath it without needing a rule on each one. As elsewhere, the closest matching rule wins, and within a node the properties, settings and MintModel paths are more specific than the node path itself.
For example, when resolving a secret referenced by the settings of the dev environment in the bank project, MintPress uses the first of these paths a rule exists for:
/projects/bank/environments/dev/settings/secrets/projects/bank/environments/dev/secrets/projects/bank/settings/secrets/projects/bank/secrets/settings/secrets/secrets
This makes the usual least-privilege shape expressible - deny execute on /secrets globally, then grant it on the one project a team is responsible for. Equally, a deny on /projects/bank/settings/secrets overrides a grant on /projects/bank/secrets, leaving that project's property and MintModel secrets resolvable while its settings secrets are not.
Writing to the vault
Storing a value in the vault requires the update action on a secrets path. Which path grants it depends on what you are storing:
- Storing a text value or a file against a node, and uploading a file property with a secret path, is granted by
updateon the owning node's{{node path}}/secrets, or on any of its ancestors' secrets paths, up to/secrets. Someone responsible for one project can therefore be givenupdateon/projects/bank/secretsalone, which lets them store secrets throughout that project and nowhere else. - The AES encryption tool requires
updateon/secrets. It encrypts a value without storing it against a node, so there is no narrower path that can grant it.
Only the {{node path}}/secrets form grants writing. The properties, settings and mintmodel secrets paths grant nothing towards it, however they are set for resolving.
Writing is not decided by the closest matching rule, as resolving is - it is permitted if any path in that chain allows it. A deny on /projects/bank/secrets therefore does not stop someone granted update on /secrets from writing within that project. To narrow who can write, withhold the broader grant rather than denying it further down.
Authorisation policies
Authorisation rules must be applied to users in order to be effective. An authorisation policy can apply a set of rules to specific users via their username or LDAP group name.
- If an authorisation policy is assigned to a username, then that policy's rules will only apply to the user with the matching username.
- If an authorisation policy is assigned to a group name, then that policy's rules will apply to all users that are part of that LDAP group.
- If an authorisation policy is assigned to an empty username and group name, then that policy's rules will apply to all users.
- If an authorisation policy is assigned to a username and a group name, then that policy's rules will apply to that user only if they are a member of that group.
Authorisation policies can share authorisation rules and multiple policies can be assigned to a user or an LDAP group.
Who a policy can be assigned to
An assignment names a user MintPress already has, or one the LDAP directory holds — in which case MintPress creates the user as the assignment is made, so the policy applies to them straight away rather than from the first time they sign in. A username that is neither is refused, naming the username, rather than being stored against an account that may never exist.
A policy can be assigned to a local user as well as an LDAP one. Where both hold the same username, the policy is assigned to the LDAP user, as that is the account they authenticate as.
Deleting a user removes their policy assignments. Creating an account with the same username later does not restore them.
Special policies
MintPress provides two special policies that can be applied to any user, at any moment. These are system policies: their rules cannot be added, removed or changed, only their assignments. An attempt is refused with This authorisation policy is a system resource and cannot be modified.
Superuser policy
This policy provides full permissions to all resources within MintPress. This policy is the recommended approach when provisioning MintPress for the first time. We refer to users with this policy as superusers. This policy trumps all other policies, except the block user access policy.
To make an existing user a superuser, add them to the superuser policy from its Assignments tab.
The superuser policy cannot be assigned to everyone — an assignment with neither a user nor a group — because that would give every user full access. Assign it to specific users or groups instead.
When MintPress uses LDAP authentication and the OpsChain secret vault, LDAP superusers also become the secret vault's administrators. See administer the secret vault as a superuser.
It is recommended to keep the number of users with superuser access as minimal as possible.
Block user access policy
This policy blocks access to all resources within MintPress. This policy is the recommended approach when you want to fully block access to MintPress for certain users. This policy can be applied from its Assignments tab. This policy trumps all other policies, including the superuser policy.
The block user access policy cannot be assigned to everyone, because that would lock out every user, superusers included, and leave nobody able to remove the assignment. Assign it to specific users or groups instead.
When MintPress uses LDAP authentication and the OpsChain secret vault, blocked LDAP users are also blocked from the secret vault. See blocked users.
Manage security policies
When on this page, you will be taken to the MintPress policies tab by default.
Each row includes:
| Column | Description |
|---|---|
| Name | The name describing the purpose of the security policy. |
| Description | Provides a short summary or purpose of the security policy. |
| Created by | The user who created the security policy. |
| Created at | Timestamp for when the security policy was created. |
| Updated at | Timestamp for when the security policy was last updated. |
| System | Whether it is a system-generated policy or a user-generated one. |
Buttons & links
| Buttons & links | Function |
|---|---|
| Search bar | Filter the contents of the table based on these criteria. |
| Columns | Hide or display columns in the table. |
| Bulk actions | Delete the selected policies, after confirming. Needs the delete action on an /authorisation_policies path. |
| Create policy | Create a new security policy. |
| Refresh LDAP | Refresh the LDAP directory cache. Superuser only. |
Select a policy to open it on its Rules and Assignments tabs, described below.
Which policies are listed
The policies tab lists only the policies the user can read. Superusers see every policy, and users assigned the block user access policy see none. For everyone else, it depends on the read action of the rules they hold on /authorisation_policies paths:
- A rule granting
readon the top-level/authorisation_policiespath lists every policy. - A rule granting
readon a node's/authorisation_policiespath, for example/projects/bank/authorisation_policies, lists a policy only when every rule in it has a path starting with/projects/bank. A policy that also holds a rule for another project, or a top-level rule such as/events, is not listed, even though the user can read itsbankrules. A user holding several of these rules can see a policy whose rules are spread across them, as long as each rule starts with one of their paths. - A policy with no rules is listed for every user holding one of these rules.
- A user with none of these rules sees no policies.
The comparison is on the text of the rule's path, so a regular expression rule such as /projects/(bank|retail) does not start with /projects/bank. Rules on other paths, including the root path and /projects/bank itself, do not affect which policies are listed.
When a user holds several rules for the same /authorisation_policies path, a rule from a policy assigned to them by username takes precedence over one assigned to their group, which takes precedence over one assigned to everyone.
Changing or deleting a listed policy follows the same test, with the update or delete action in place of read: every rule in the policy must start with a path on which the user holds that action. A user with read on /authorisation_policies but delete only on /projects/bank/authorisation_policies sees every policy, but can delete only those whose rules all start with /projects/bank.
Creating a security policy
To create a new policy, follow these steps:
- Click on the Create policy button
- Fill in the policy name, and optionally a description
- Click the Create policy button. The new policy will appear on the policies list. You can now start adding rules and assigning permissions within that policy.
Managing policy rules
Once you've created a security policy, you can begin adding rules to it from its Rules tab. Available resource paths are listed on the right side of the screen. To add a path to the policy, hover over the desired path and click the Add to policy button. The selected path will then appear on the left side of the screen, where you can configure its Read, Update, Execute and Delete permissions.
You can add custom path rules by clicking on the Add custom path button.
Your edits are not saved until you click Apply changes. Discard changes reverts them.
Managing policy assignments
To activate a security policy, you must assign it to users and/or groups. Click on the Assignments tab to do so. This tab displays a list of users and groups currently associated with the policy.
Modifying policy assignments
To add a user or group to the policy, follow these steps:
- Click on the Add users/groups button.
- You will be given an option to select a user or a group.
- Fill in the username or group name.
- You can add more users or groups by clicking on the Add assignee button.
- Click on the Add button to include the assignments in the policy.
To remove a user or group from the policy, follow these steps:
- Select the assignments in the table.
- Click on the Bulk actions dropdown.
- Select the Remove selected assignees option.
- Click on the Remove button to confirm the removal of the assignments from the policy.
Users
This tab contains the users and the policies that are assigned to them. To change a user's policies, edit the policy's assignments.
Throughout the GUI, users are shown by their display name, with their username in a tooltip, and user pickers list each user's display name and email address. A user with no display name is shown by their username. Local users can set their own display name by choosing Display name from the user menu.
| Column | Description |
|---|---|
| Username | The name or identifier of the user. |
| Display name | The name the GUI shows for the user. A superuser can change a local user's with the pencil button beside it. An LDAP user's is read from the directory - see user names. |
| The user's email address. | |
| MintPress policies | Security policies currently assigned to the user. |
| Auth provider | The authentication source used to validate the user's identity. |
| Groups | List of LDAP groups that this user belongs to. |
| Disabled | For an LDAP user disabled in the directory, the date they were disabled, shown in red. Empty for an enabled user. |
| Created at | Timestamp for when the user was created. |
| Updated at | Timestamp for when the user was last updated. |
| Direct vault policies | The secret vault policies mapped to the user directly, rather than through one of their groups. Change them with Edit vault policies on the user's row. Shown to superusers when MintPress manages vault policies. |
Buttons & links
| Buttons & links | Function |
|---|---|
| Search bar | Filter users by their username. |
| Columns | Hide or display columns in the table. |
| Bulk actions | Add vault policy… or Remove vault policy… for the selected users. The dialog asks you to Select a vault policy and lists the users it will change. Only LDAP users are changed - local users in the selection are left out. Shown to superusers when MintPress manages vault policies. |
Groups
This tab contains the list of LDAP groups.
| Column | Description |
|---|---|
| CN | The Common Name (CN) of the LDAP group. |
| ID | The full LDAP Distinguished Name (DN) of the group. |
| Alternative CN | An optional alternative name or alias for the LDAP group. |
| MintPress policies | The authorisation policies assigned to the group. To change them, edit the policy's assignments. |
| Vault policies | The secret vault policies mapped to the group. Change them with Edit vault policies on the group's row. See give an LDAP group access to secrets. |
Buttons & links
| Buttons & links | Function |
|---|---|
| Search bar | Filter groups by their CN, ID and alternative CN. |
| Columns | Hide or display columns in the table. |
| Bulk actions | Add vault policy… or Remove vault policy… for the selected groups. The dialog asks you to Select a vault policy and lists the groups it will change. Shown to superusers when MintPress manages vault policies. |
Vault policies
This tab, shown to superusers, lists the policies of the OpsChain secret vault, which decide what an LDAP user signed in to the secret vault can do with its secrets. It is available only when MintPress uses LDAP authentication, the OpsChain secret vault is in use, and the Vault LDAP login setting is enabled; otherwise the tab says vault policies are not managed by MintPress. The policies MintPress maintains itself (those named opschain-*) and the default and root policies are not listed.
| Column | Description |
|---|---|
| Name | The name of the policy. |
| Rules | How many path rules the policy holds. |
| Mounts | The key/value stores the rules apply to. A rule outside them is shown as Non MintPress mount. |
| Assigned to | How many users and groups hold the policy, or Not assigned. |
| Version | The policy's current version. |
| Last modified | When the policy was last changed. |
Buttons & links
| Buttons & links | Function |
|---|---|
| New policy | Create a policy, giving its name and rules. |
| Duplicate | Create a policy starting from a copy of this one's rules. |
| Delete | Permanently delete the policy. Users and groups assigned it lose the access it grants. Select several policies to delete them together from Bulk actions. |
| Name | Open the policy's page. |
Editing a vault policy
A policy's page has three tabs:
- Rules - the policy's rules, written as JSON or HCL. While you type a path, the editor suggests the key/value stores the rules can use. A rule must stay within them; for a version 2 store, its secrets sit under
<store>/data/and their metadata under<store>/metadata/. When you save a changed policy, the Changes view first shows what you have changed; save again to apply it. - Assignments - the users and groups that hold the policy, listed by Assignee, with a Type of
userorgroup. Select Add users / groups to assign it to more LDAP users or groups, or remove assignments from Bulk actions. - History - earlier versions of the policy, with who saved each one and when. A version changed directly in the secret vault, rather than from MintPress, is labelled as changed outside MintPress.
Users and groups can also be given policies from the Edit vault policies button on their row of the Users and Groups tables. See give an LDAP group access to secrets for an example policy.