diff --git a/conf/core/authtoken.example.yaml b/conf/core/authtoken.example.yaml index 5b5eb1abbd65eb90c0c4ec93e6fda72a84da7982..453630a852642db19cfc824bf660b004e26af5b2 100644 --- a/conf/core/authtoken.example.yaml +++ b/conf/core/authtoken.example.yaml @@ -1,7 +1,7 @@ # OneTimeAuthenticationToken Config # -# One-Time Authentication (OTA) Tokens are a means to authenticate a client without a -# password. +# One-Time Authentication (OTA) Tokens are a means to authenticate a client +# without a password. # # This example config file illustrates several use cases of One-Time # Authentication Tokens. @@ -13,12 +13,12 @@ # # - expiresAfter:: An integer timespan in milliseconds after the OTA Token was # generated by the server when the token expires. So the token will not be -# valid after <date> + <expiresAfter>. +# valid after <creationDate> + <expiresAfter>. # - expiresAfterSeconds:: A convenient option which has the same meaning as -# expiresAfter but with seconds instead of milliseconds. +# expiresAfter but measured in seconds instead of milliseconds. # - roles:: A list of strings which are the user roles that the client has when # it authenticates with this token. This is a way to give a client a set of -# roles which it wouldn't have otherwise. Subsequently, the client also has +# roles which it wouldn't have otherwise. Consequently, the client also has # all permissions of its roles. # - permissions:: A list of string which are the permissions that the client has # when it authenticates with this token. This is another way to give a @@ -32,44 +32,47 @@ # number of times that a server accepts an OTA token as valid. The default # is, of course, 1. # - replayTimeout:: An integer timespan in milliseconds. Because replays are a -# possible attack vector, the time frame in which the same token might be is -# limitted by this value. The default value is configured by the server +# possible attack vector, the time span in which the same token may be used +# is limited by this value. The default value is configured by the server # property 'ONE_TIME_TOKEN_REPLAYS_TIMEOUT_MS' which has a default of 30000, # which is 30 seconds. # - replayTimeoutSeconds:: A convenient option which has the same meaning as -# replayTimeout but with seconds instead of milliseconds. -# - output:: Defines how the OTA token is outputted by the server. If this -# property is not present the OTA is not outputted in any way but only used -# internally (see purpose). The 'output' object has the following properties: -# - file:: An absolute or relative path in the servers file system. This +# replayTimeout but measured in seconds instead of milliseconds. +# - output:: Defines how the OTA token is output by the server. If this property +# is not present the OTA is not output in any way but only used internally +# (see purpose). The 'output' object has the following properties: +# - file:: An absolute or relative path in the server's file system. This # property means that the OTA is written to that file on server start. -# - schedule:: A cron-tab compliant string indicating when the OTA is -# renewed and the file is being overridden with the new OTA. +# - schedule:: A string formatted according to the Quartz[1] library +# indicating when the OTA is renewed and the file is being overridden +# with the new OTA. # - purpose:: A string which is used (only internally so far) to generate an OTA # for a special purpose, e.g. the execution of a server-side script with -# particular permissions. This way, an otherwise unprivileged client might -# execute a server-side script with all necessary permissions, if only the -# client has the "SCRIPTING:EXECUTE:<script-path>" permission and this -# config file has a configuration with -# "purpose: SCRIPTING:EXECUTE:<script-path>" (case-sensitive). +# particular permissions. This way, an otherwise unprivileged client may +# execute a server-side script with all necessary permissions, if the client +# has the "SCRIPTING:EXECUTE:<script-path>" permission and this config file +# has a configuration with "purpose: SCRIPTING:EXECUTE:<script-path>" +# (case-sensitive). +# +# [1] http://www.quartz-scheduler.org/api/2.3.0/org/quartz/CronExpression.html # # # Examples: # # 1. Every client with the SCRIPTING:EXECUTE:administration/diagnostics.py # permission can execute the administration/diagnostics.py script with the -# administration role. +# administration role (and not the client's roles). - purpose: SCRIPTING:EXECUTE:administration/diagnostics.py roles: - administration # 2. The server writes an OTA token with the administration role to -# "authtoken/admin_token.txt" and refreshes that token every 10 seconds. +# "authtoken/admin_token_crud.txt" and refreshes that token every 10 seconds. - roles: - administration output: - file: "authtoken/admin_token.txt" + file: "authtoken/admin_token_crud.txt" schedule: "0/10 * * ? * * *" - + # 3. The server writes an OTA token with the administration role to # "authtoken/admin_token_3_attempts.txt" which can be replayed 3 times in 10 # seconds. The OTA token is refreshed every 10 seconds. @@ -80,21 +83,12 @@ schedule: "0/10 * * ? * * *" maxReplays: 3 replayTimeout: 10000 - + # 4. The server writes an OTA token with the administration role to # "authtoken/admin_token_expired.txt" which expires immediately. Of course -# this is onyl useful for testing. +# this is only useful for testing. - roles: - administration output: file: "authtoken/admin_token_expired.txt" expiresAfterSeconds: 0 - - -# 5. The server writes an OTA token with the administration role to -# "authtoken/admin_token_crud.txt" and refreshes that token every 10 seconds. -- roles: - - administration - output: - file: "authtoken/admin_token_crud.txt" - schedule: "0/10 * * ? * * *"