Services
Introduction
A service is a single entity for which a user can request credentials. The configuration of a service consists of one group of service settings.
To create credentials, WaTTS connects to the service, either locally or remotely using ssh. After the connection is established, a command is executed and the subsequent result is parsed and interpreted.
The executed commands are also called plugins; for further information on how the plugins work and how to implement them, see the documentation for developers.
The plugins are not part of WaTTS, so they can be changed independant of WaTTS and also maintained by the community.
Known plugins(use them at your own risk):
Feel free to add an issue to get your plugin listed above.
Settings
Each setting is prefixed with 'service.id
.' where id
must be replaced by the id
you want to give to the service.
Key | Description | Datatype | Mandatory (Default) |
---|---|---|---|
description | A description of the service for the user | string | yes |
display_prio | the priority of the service in the listing. the lower the number the higher in the list the service will be listed. If the priority is 'undefined', the service is listed below the ones that have a numeric priority. | integer or 'undefined' | no ('undefined') |
cmd | The command to execute after connecting, needs to be executable/readable by the user WaTTS is running as | string | yes |
cmd_env_use | DEPRECATED! The parameter will not be passed at the command line but put into an environment variable. The default is 'false'. | boolean | no (false) |
cmd_env_var | DEPRECATED! The name of the environment variable containing the parameter, only used if cmd_env_use is true |
string | no (WATTS_PARAMETER) |
credential_limit | The maximum number of retrievable credentials | integer or 'infinite' | no (infinite) |
parallel_runner | The number of parallel runs of the plugin for the service | integer or 'infinite' | no, (1) |
allow_same_state | Whether the plugin is allowed to return the same state more than once | boolean | no, (false) |
plugin_timeout | The time after which WaTTS won't wait for the result of the plugin execution anymore | duration or 'infinity' | no (infinity) |
pass_access_token | Whether the access token should be passed to the plugin. Enabling this is adding a security risk! | boolean | no (false) |
connection.type | Either local or ssh | 'local' or 'ssh' | yes |
connection.user | The user name to use when connecting e.g. with ssh | string | no ('') |
connection.password | The password to use when connecting e.g. with ssh | string | no ('') |
connection.host | The hostname to connect to e.g. with ssh | host | no ('') |
connection.port | The port number to connect to e.g. with ssh | port | no ('') |
connection.ssh_dir | The ssh_dir to use with ssh | port | no ('') |
connection.ssh_key_pass | The password of the private key to use with ssh | string | no ('') |
plugin.key |
A setting to send to the plugin, the name of the parameter will be key . Which values and which keys are supported depend on the plugin. If no parameter are set warning about using default values are issued in the logs |
any | no (default from plugin) |
authz.allow.p .k .o |
See the Authorization section | other | no ([]) |
authz.forbid.p .k .o |
See the Authorization section | other | no ([]) |
authz.hide | Hide the service if the user is not allowed | boolean | no (false) |
authz.tooltip | Message that is shown when hovering the row of the service that is not allowed, used to give users a hint on how they might get access to the service | boolean | no (false) |
email_on_error_to | Whom to send emails in case of plugin issues. Only if emails are enabled and mail on plugin errors are enabled (see server settings) | 'noone', 'admin', 'developer' or 'admin_devel' | no (admin_devel) |
Authorization
Authorization follows a few simple steps:
- at first everyone is forbidden
- if an
allow
rule that matches the user evaluates to true, she is allowed - if a
forbid
rule that matches the user evaluates to true, he is forbidden
So a for a user to access a service she:
- MUST match at least one
allow
rule - MUST NOT match any
forbid
rule
Each rule is exactly one line long. A rule always consists of five parts:
authz.allow.p.k.o = v
, where the values are:
p
: the Id of the provider, this can either be an OpenID Connect provider or an rspk
: the key within the OpenId Connect Id-Token or user informationinfo
: the information in the Id Token or user information with the keyk
o
: the operation to performv
: the value
The provider Id for an OpenID Connect provider is the same as was given during the configuration,
in the provider example above the id was iam
, so using that for p
allows making decisions
on users coming from iam
.
The provider Id for an RSP is the id of the RSP prefixed with an 'rsp-'. So the simple RSP in
the example above would have the id rsp-simple
. All connections from an RSP get logged in
by the information sent by the RSP, an additional login at configured OpenID Connect providers
can be performed.
There is a special provider id value, any
, which matches any provider, meaning any OpenID
Connect or RSP provider.
The key k
has to match a value of the id token or the user info. The value of the
Id Token offers Userinfo, i.e. having the key k
is the info
.
If the key is not present:
allow
rule evaluates to falseforbid
rule evaluates to true
The operation o
can be one of the following list:
contains
: theinfo
can either be a list or a string- a list: the value
v
must be a member of the listinfo
- a string: the value
v
must be part of the stringinfo
- a list: the value
is_member_of
: the valuev
must be a comma separated list (with no spaces!) andinfo
needs to be a member of that listequals
:v
andinfo
need to be equalregexp
:v
is a regular expression andinfo
needs to satisfy the expressionany
: evaluates tov
, so to make this pass setv
to 'true'
Examples
# 'p' is any, so matching all providers
# 'k' is sub, the subject of the id token, this is always present
# 'info' can be ignored due to
# 'o' being 'any'
# 'v' is true
# The following line is an example allowing anyone from any provider:
service.info.authz.allow.any.sub.any = true
# 'p' is iam, so matching only the provider with the id iam
# 'k' is sub, the subject of the id token, which for sure is always present
# 'info' can be ignored due to
# 'o' being 'any'
# 'v' is true
# The next line shows an example allowing anyone from the iam provider:
service.info.authz.allow.iam.sub.any = true
# The examples below will concentrate on the operations.
# 'k' is a group, i.e. the groups the user belongs to
# 'info' should be a list
# 'o' has value 'contains'
# 'v' is 'Developer'
# The following line allows anyone whose group list contains 'Developer' and is
# from the iam provider
service.info.authz.allow.iam.group.contains = Developer
# 'k' is sub
# 'info' is the subject within iam
# 'o' being 'is_member_of'
# 'v' is a comma separated list of subjects
# The following line allows sub1, sub2 and sub3 from the provider iam
service.info.authz.allow.iam.sub.is_member_of = sub1,sub3,sub2
Complete Example
service.info.description = Simple Info Service
service.info.credential_limit = 1
service.info.connection.type = local
service.info.cmd = /home/watts/.config/watts/info.py
service.info.parallel_runner = infinite
service.info.authz.allow.any.sub.any = true
# the following will be sent to the plugin
service.plugin.path = /tmp/data