Development documentation

This describes Keydra as it is being built and is not a released version. What it documents can change before a release.

Permissions reference

Every permission Keydra defines and the scope a grant of it can be written at.

Permissions#

Every permission Keydra defines. The Scope column says where a grant of it can be written: a permission about Keydra itself can only be granted on the instance, and one about a server can be granted on a target, on a server group, or on the instance.

Permission Scope Description

Permission	Scope	Description
`connection:view`	Target	See that the target exists, and its status. Holding any permission on a target is what makes it visible at all, and this is the smallest one.
`connection:edit`	Target	Change where a profile points and the credentials it uses, including which tunnel it reaches through.
`connection:delete`	Target	Remove a profile. Nothing on the server itself changes.
`keys:read`	Target	Browse the keyspace and read key names, types and expiries.
`keys:write`	Target	Create, rename, duplicate keys and change their expiries.
`keys:delete`	Target	Delete keys, singly or in bulk.
`values:read`	Target	Read the contents of a key.
`values:write`	Target	Change the contents of a key.
`console:run`	Target	Run commands from the console. An operator’s: somebody trusted to change the data, deliberately not somebody trusted to change what the server is — which is why the deny-list refuses CONFIG, MODULE and EVAL.
`pubsub:subscribe`	Target	Open a subscription to channels or patterns on the target.
`pubsub:publish`	Target	Publish a message to a channel.
`commands:watch`	Target	Watch every command the server runs. The most revealing thing there is: somebody who may read one key at a time has no business reading all of them as they go past.
`monitoring:read`	Target	See the dashboard, the slow log, the clients and the largest keys.
`monitoring:manage`	Target	Start and stop sampling, clear the slow log and disconnect a client.
`analysis:read`	Target	Run and read the keyspace analysis.
`server:read`	Target	Read the server’s own settings and persistence state.
`server:configure`	Target	Change the server’s settings, ask it for a snapshot, and rewrite its log.
`acl:read`	Target	See the users the target itself knows about.
`acl:manage`	Target	Create, change and remove the target’s own ACL users.
`migration:run`	Target	Move keys to or from this target. Required on both ends of a migration.
`schedule:manage`	Target	Arrange work to happen to this target later. Required as well as the permission the work itself needs: a schedule is a way of doing something later, not a way of doing something you may not do.
`alert:manage`	Target	Write and change rules about this target. Beside monitoring:manage rather than inside it, because a rule outlives the person who wrote it — it keeps the target sampled when nobody is watching and sends messages outside.
`transfer:export`	Target	Export keys to a file, and take backups.
`transfer:import`	Target	Import keys from a file, and restore backups.
`script:run`	Instance	Run a migration script inside Keydra. On the instance rather than on a target, which is the whole point of it: a script runs in Keydra’s own process, which holds every target’s credentials and can reach every network Keydra can reach. Required as well as migration:run on the target.
`connection:create`	Instance	Add a target to this instance.
`groups:manage`	Instance	Create and change user groups and server groups, and their membership.
`users:manage`	Instance	Create, change, disable and remove accounts, and invite people.
`grants:manage`	Instance	Write and remove grants — who holds which role on which scope.
`idp:manage`	Instance	Configure identity providers and their claim and group mappings.
`backup:manage`	Instance	Configure where backups go. An administrator’s: a destination carries credentials to somewhere outside Keydra, and somebody who may back one server up is not thereby somebody who decides backups leave for a bucket of their choosing.
`tunnel:manage`	Instance	Describe the jump hosts. An administrator’s alone: a jump host carries a credential that reaches a whole network, and everything Keydra holds for everything behind it travels through it.
`alert-delivery:manage`	Instance	Decide where alerts are sent. An administrator’s, for the reason a backup destination is: it holds a credential to somewhere outside, and choosing where a server’s troubles are announced is not part of watching that server.
`crypto:rotate`	Instance	Move every stored credential onto a new key. The most consequential thing this application can be asked to do, and the only permission that is about the secrets rather than about what they unlock.
`audit:read`	Instance	Read the audit log.
`policy:manage`	Instance	Decide what this installation asks of everybody who signs in — today, whether a second factor is required. Its own permission because it restricts every person at once until they enrol, which is a different blast radius from making one account.
`instance:read`	Instance	Read how Keydra itself is doing: which instances are running, what each of them is holding, and what they all rest on. Not the same as being signed in — the roster names hosts and the dependency list is a map of the installation.
`instance:drain`	Instance	Take an instance out of service and put it back. Separate from instance:read because reading where the work is and deciding where it goes are not the same act: draining stops an instance taking new browsers and hands its chores to another.

connection:view

Target

See that the target exists, and its status. Holding any permission on a target is what makes it visible at all, and this is the smallest one.

connection:edit

Target

Change where a profile points and the credentials it uses, including which tunnel it reaches through.

connection:delete

Target

Remove a profile. Nothing on the server itself changes.

keys:read

Target

Browse the keyspace and read key names, types and expiries.

keys:write

Target

Create, rename, duplicate keys and change their expiries.

keys:delete

Target

Delete keys, singly or in bulk.

values:read

Target

Read the contents of a key.

values:write

Target

Change the contents of a key.

console:run

Target

Run commands from the console. An operator’s: somebody trusted to change the data, deliberately not somebody trusted to change what the server is — which is why the deny-list refuses CONFIG, MODULE and EVAL.

pubsub:subscribe

Target

Open a subscription to channels or patterns on the target.

pubsub:publish

Target

Publish a message to a channel.

commands:watch

Target

Watch every command the server runs. The most revealing thing there is: somebody who may read one key at a time has no business reading all of them as they go past.

monitoring:read

Target

See the dashboard, the slow log, the clients and the largest keys.

monitoring:manage

Target

Start and stop sampling, clear the slow log and disconnect a client.

analysis:read

Target

Run and read the keyspace analysis.

server:read

Target

Read the server’s own settings and persistence state.

server:configure

Target

Change the server’s settings, ask it for a snapshot, and rewrite its log.

acl:read

Target

See the users the target itself knows about.

acl:manage

Target

Create, change and remove the target’s own ACL users.

migration:run

Target

Move keys to or from this target. Required on both ends of a migration.

schedule:manage

Target

Arrange work to happen to this target later. Required as well as the permission the work itself needs: a schedule is a way of doing something later, not a way of doing something you may not do.

alert:manage

Target

Write and change rules about this target. Beside monitoring:manage rather than inside it, because a rule outlives the person who wrote it — it keeps the target sampled when nobody is watching and sends messages outside.

transfer:export

Target

Export keys to a file, and take backups.

transfer:import

Target

Import keys from a file, and restore backups.

script:run

Instance

Run a migration script inside Keydra. On the instance rather than on a target, which is the whole point of it: a script runs in Keydra’s own process, which holds every target’s credentials and can reach every network Keydra can reach. Required as well as migration:run on the target.

connection:create

Instance

Add a target to this instance.

groups:manage

Instance

Create and change user groups and server groups, and their membership.

users:manage

Instance

Create, change, disable and remove accounts, and invite people.

grants:manage

Instance

Write and remove grants — who holds which role on which scope.

idp:manage

Instance

Configure identity providers and their claim and group mappings.

backup:manage

Instance

Configure where backups go. An administrator’s: a destination carries credentials to somewhere outside Keydra, and somebody who may back one server up is not thereby somebody who decides backups leave for a bucket of their choosing.

tunnel:manage

Instance

Describe the jump hosts. An administrator’s alone: a jump host carries a credential that reaches a whole network, and everything Keydra holds for everything behind it travels through it.

alert-delivery:manage

Instance

Decide where alerts are sent. An administrator’s, for the reason a backup destination is: it holds a credential to somewhere outside, and choosing where a server’s troubles are announced is not part of watching that server.

crypto:rotate

Instance

Move every stored credential onto a new key. The most consequential thing this application can be asked to do, and the only permission that is about the secrets rather than about what they unlock.

audit:read

Instance

Read the audit log.

policy:manage

Instance

Decide what this installation asks of everybody who signs in — today, whether a second factor is required. Its own permission because it restricts every person at once until they enrol, which is a different blast radius from making one account.

instance:read

Instance

Read how Keydra itself is doing: which instances are running, what each of them is holding, and what they all rest on. Not the same as being signed in — the roster names hosts and the dependency list is a map of the installation.

instance:drain

Instance

Take an instance out of service and put it back. Separate from instance:read because reading where the work is and deciding where it goes are not the same act: draining stops an instance taking new browsers and hands its chores to another.

Which permissions each built-in role carries is described in The built-in roles. A custom role chooses from this list.

Edit this page