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:

  1. at first everyone is forbidden
  2. if an allow rule that matches the user evaluates to true, she is allowed
  3. 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 rsp
  • k: the key within the OpenId Connect Id-Token or user information
  • info: the information in the Id Token or user information with the key k
  • o: the operation to perform
  • v: 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 false
  • forbid rule evaluates to true

The operation o can be one of the following list:

  • contains: the info can either be a list or a string
    • a list: the value v must be a member of the list info
    • a string: the value v must be part of the string info
  • is_member_of: the value v must be a comma separated list (with no spaces!) and info needs to be a member of that list
  • equals: v and info need to be equal
  • regexp: v is a regular expression and info needs to satisfy the expression
  • any: evaluates to v, so to make this pass set v 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

results matching ""

    No results matching ""