7.1. Admin policies

Admin policies are used to regulate the actions that administrators are allowed to do. Technically admin policies control the use of the REST API Token endpoints, System endpoints, Realm endpoints and Resolver endpoints.

Admin policies are implemented as decorators in Policy Module and Policy Decorators.

Starting with privacyIDEA 2.4 admin policies can also store a field “admin realm”. This is used, if you define realms to be superuser realms. See The Config File for information how to do this. Read So what’s the thing with all the admins? for more information on the admin realms.

This way it is easy to define administrative rights for big groups of administrative users like help desk users in the IT department.

../_images/admin_policies.png

The Admin scope provides an additional field ‘admin realm’.

All administrative actions also refer to the defined user realm. Meaning an administrator may have many rights in one user realm and only a few rights in another realm.

Creating a policy with scope:admin, admin-realm:helpdesk, user:frank, action:enable and realm:sales means that the administrator frank in the admin-realm helpdesk is allowed to enable tokens in the user-realm sales.

Note

As long as no admin policy is defined all administrators are allowed to do everything.

Note

Admin policies are also checked for all local administrators.

The following actions are available in the scope admin:

7.1.1. tokenlist

type: bool

This allows the administrator to list existing tokens in the specified user realm. Note, that the resolver in this policy is ignored.

If the policy with the action tokenlist is not bound to any user realm, this acts as a wild card and the admin is allowed to list all tokens.

If the action tokenlist is not active, but admin policies exist, then the admin is not allowed to list any tokens.

Note

As with all boolean policies, multiple tokenlist policies add up to create the resulting rights of the administrator. So if there are multiple matching policies for different realms, the admin will have list rights on all mentioned realms independent on the priority of the policies.

7.1.2. enroll

type: bool

There are enrollment actions per token type, e.g. enrollHOTP. Only those token types are selectable in the WebUI during enrollment which are allowed by their corresponding enroll policy action.

7.1.3. enable

type: bool

The enable action allows the administrator to activate disabled tokens.

7.1.4. disable

type: bool

Tokens can be enabled and disabled. Disabled tokens can not be used to authenticate. The disable action allows the administrator to disable tokens.

7.1.5. revoke

type: bool

Tokens can be revoked. Usually this means the token is disabled and locked. A locked token can not be modified anymore. It can only be deleted.

Certain token types like certificate may define special actions when revoking a token.

7.1.6. set

type: bool

Tokens can have additional token information, which can be viewed in the Functionality of the Tokens view.

If the set action is defined, the is administrator allowed to set those token properties like description, max_failcount or validity_period_start at the /token/set endpoints (see Token endpoints).

7.1.7. setdescription

type: bool

The admin is allowed to set the description of tokens via the endpoint /token/descriptipon.

Note

That an admin can also be allowed to the the description of a token by granting the before mentioned policy set.

7.1.8. setpin

type: bool

If the setpin action is defined, the administrator is allowed to set the OTP PIN of a token.

7.1.9. setrandompin

type: bool

If the setrandompin action is defined, the administrator is allowed to call the endpoint, that sets a random token PIN.

7.1.10. settokeninfo

type: bool

The administrator is allowed to manually set and delete token info.

7.1.11. enrollpin

type: bool

If the action enrollpin is defined, the administrator can set a token PIN during enrollment. If the action is not defined and the administrator tries to set a PIN during enrollment, this PIN is deleted from the request.

7.1.12. hide_tokeninfo

type: string

This specifies a blank-separated list of tokeninfo keys, which should be removed from the response and therefore will not be shown in the WebUI or JSON response.

For example a value tokenkind auto_renew will hide these two tokeninfo entries.

7.1.13. otp_pin_maxlength

type: integer

range: 0 - 31

This is the maximum allowed PIN length the admin is allowed to use when setting the OTP PIN.

Note

There can be token type specific policies like spass_otp_pin_maxlength, spass_otp_pin_minlength and spass_otp_pin_contents. If suche a token specific policy exists, it takes priority of the common PIN policy.

7.1.14. otp_pin_minlength

type: integer

range: 0 - 31

This is the minimum required PIN the admin must use when setting the OTP PIN.

7.1.15. otp_pin_contents

type: string

contents: cns

This defines what characters an OTP PIN should contain when the admin sets it.

c are letters matching [a-zA-Z].

n are digits matching [0-9].

s are special characters matching [[].:,;-_<>+*!/()=?$§%&#~^].

[allowedchars] is a specific list of allowed characters.

Example: The policy action otp_pin_contents=cn, otp_pin_minlength=8 would require the admin to choose OTP PINs that consist of letters and digits which have a minimum length of 8.

cn

test1234 and test12$$ would be valid OTP PINs. testABCD would not be a valid OTP PIN.

The logic of the otp_pin_contents can be enhanced and reversed using the characters + and -.

-cn (denial)

The PIN must not contain a character and must not contain a number. test1234 would not be a valid PIN, since it does contains numbers and characters. test/// would not be a valid PIN, since it contains characters.

-s (denial)

The PIN must not contain a special character. test1234 would be a valid PIN. test12$$ would not.

+cn (grouping)

combines the two required groups. I.e. the OTP PIN should contain characters from the sum of the two groups. test1234, test12$$, test and 1234 would all be valid OTP PINs. Note, how this is different to -s, since it allows special characters to be included.

[123456]

allows the digtits 1-6 to be used. 1122 would be a valid PIN. 1177 would not be a valid PIN.

7.1.16. otp_pin_set_random

type: integer

range: 1-31

The administrator can set a random pin for a token with the endpoint token/setrandompin. This policy is needed to define how long the PIN will be.

Note

The PIN will consist of digits and letters.

7.1.17. reset

type: bool

The administrator is allowed to reset the fail counter of a token.

7.1.18. resync

type: bool

If the resync action is defined, the administrator is allowed to resynchronize a token.

7.1.19. assign

type: bool

If the assign action is defined, the administrator is allowed to assign a token to a user. This is used for assigning an existing token to a user but also to enroll a new token to a user.

Without this action, the administrator can not create a connection (assignment) between a user and a token.

7.1.20. unassign

type: bool

If the unassign action is defined, the administrator is allowed to unassign tokens from a user. I.e. the administrator can remove the link between the token and the user. The token still continues to exist in the system.

7.1.21. importtokens

type: bool

If the importtokens action is defined, the administrator is allowed to import token seeds from a token file, thus creating many new token objects in the systems database.

The right to upload tokens can be limited to certain realms. Thus the administrator could only upload tokens into realm he is allowed to manage.

7.1.22. delete

type: bool

If the delete action is defined, the administrator is allowed to delete a token from the system.

Note

If a token is deleted, it can not be recovered.

Note

All audit entries of this token still exist in the audit log.

7.1.23. spass_otp_pin_contents

type: str

7.1.24. spass_otp_pin_minlength and spass_otp_pin_maxlength

type: int

These policy actions define the required minimal and allowed maximal pin length for Spass - Simple Pass Token.

7.1.25. userlist

type: bool

If the userlist action is defined, the administrator is allowed to view the user list in a realm. An administrator might not be allowed to list the users, if he should only work with tokens, but not see all users at once.

Note

If an administrator has any right in a realm, the administrator is also allowed to view the token list.

7.1.26. getchallenges

type: bool

If the getchallenges action is defined, the administrator is allowed to check the status of open challenge requests.

7.1.27. tokenrealms

type: bool

If the tokenrealms action is defined, the administrator is allowed to manage the realms of a token.

A token may be located in multiple realms. This can be interesting if you have a pool of spare tokens and several realms but want to make the spare tokens available to several realm administrators. (Administrators, who have only rights in one realm)

Then all administrators can see these tokens and assign the tokens. But as soon as the token is assigned to a user in one realm, the administrator of another realm can not manage the token anymore.

7.1.28. tokengroups

type: bool

If the tokengroups action is defined, the administrator is allowed to manage the tokengroups of a token.

Tokens can be grouped into tokengroups, so that such tokens can be more easily addressed in certain situations.

Administrators can also be allowed to define tokengroups and delete tokengroup definitions.

7.1.29. tokengroup_list

type: bool

This allows the administrator to list all defined tokengroups.

7.1.30. tokengroup_add

type: bool

If the policy tokengroup_add is defined, the administrator is allowed to define new tokengroups.

7.1.31. tokengroup_delete

type: bool

If the policy tokengroup_delete is defined, the administrator is allowed to delete existing tokengroup definitions.

7.1.32. serviceid_add

type: bool

This policy allows the administrator to add a new service ID to the list of defined services. These service IDs can then be used in attaching SSH keys or can be used with application specific passwords.

See Service IDs

7.1.33. serviceid_delete

type: bool

This policy allows the administrator to delete a service ID definition.

7.1.34. servivceid_list

type: bool

This policy allows the administrator to list all defined service IDs.

7.1.35. getserial

type: bool

If the getserial action is defined, the administrator is allowed to calculate the token serial number for a given OTP value.

7.1.36. getrandom

type: bool

The getrandom action allows the administrator to retrieve random keys from the endpoint getrandom. This is an endpoint in System endpoints.

getrandom can be used by the client, if the client has no reliable random number generator. Creating API keys for the Yubico Validation Protocol uses this endpoint.

7.1.37. getchallenges

type: bool

This policy allows the administrator to retrieve a list of active challenges of a challenge response tokens. The administrator can view these challenges in the web UI.

7.1.38. losttoken

type: bool

If the losttoken action is defined, the administrator is allowed to perform the lost token process.

To only perform the lost token process the actions copytokenuser and copytokenpin are not necessary!

7.1.39. adduser

type: bool

If the adduser action is defined, the administrator is allowed to add users to a user store.

Note

The user store still must be defined as editable, otherwise no users can be added, edited or deleted.

7.1.40. updateuser

type: bool

If the updateuser action is defined, the administrator is allowed to edit users in the user store.

7.1.41. deleteuser

type: bool

If the deleteuser action is defined, the administrator is allowed to delete an existing user from the user store.

7.1.42. copytokenuser

type: bool

If the copytokenuser action is defined, the administrator is allowed to copy the user assignment of one token to another.

This functionality is also used during the lost token process. But you only need to define this action, if the administrator should be able to perform this task manually.

7.1.43. copytokenpin

type: bool

If the copytokenpin action is defined, the administrator is allowed to copy the OTP PIN from one token to another without knowing the PIN.

This functionality is also used during the lost token process. But you only need to define this action, if the administrator should be able to perform this task manually.

7.1.44. smtpserver_write

type: bool

To be able to define new SMTP server configuration or delete existing ones, the administrator needs this rights smtpserver_write.

7.1.45. smtpserver_read

type: bool

Allow the administrator to read the SMTP server configuration.

7.1.46. smsgateway_write

type: bool

To be able to define new SMS Gateway configuration or delete existing ones, the administrator needs the right smsgateway_write.

7.1.47. smsgateway_read

type: bool

Allow the administrator to read the SMS Gateway configuration.

7.1.48. periodictask_write

type: bool

Allow the administrator to write or delete Periodic Tasks definitions.

7.1.49. periodictask_read

type: bool

Allow the administrator to read the Periodic Tasks definitions.

7.1.50. eventhandling_write

type: bool

Allow the administrator to configure Event Handler.

7.1.51. eventhandling_read

type: bool

Allow the administrator to read Event Handler.

Note

Currently the policies do not take into account resolvers, or realms. Having the right to read event handlers, will allow the administrator to see all event handler definitions.

7.1.52. radiusserver_write

type: bool

Allow the administrator to write or delete RADIUS server configuration definitions.

7.1.53. radiusserver_read

type: bool

Allow the administrator to read the RADIUS server configuration definitions.

7.1.54. privacyideaserver_write

type: bool

Allow the administrator to write or delete privacyIDEA server configuration definitions.

7.1.55. privacyideaserver_read

type: bool

Allow the administrator to read the privacyIDEA server configuration definitions.

7.1.56. policywrite, policyread, policydelete

type: bool

Allow the administrator to write, read or delete policies.

Note

Currently the policies do not take into account resolvers, or realms. Having the right to read policies, will allow the administrator to see all policies.

7.1.57. resolverwrite, resolverread, resolverdelete

type: bool

Allow the administrator to write, read or delete user resolvers and realms.

Note

Currently the policies do not take into account resolvers, or realms. Having the right to read resolvers, will allow the administrator to see all resolvers and realms.

7.1.58. mresolverwrite, mresolverread, mresolverdelete

type: bool

Allow the administrator to write, read or delete machine resolvers.

7.1.59. configwrite, configread, configdelete

type: bool

Allow the administrator to write, read or delete system configuration.

7.1.60. caconnectorwrite, caconnectorread, caconnectordelete

type: bool

Allow the administrator to write, read or delete CA connectors.

7.1.61. statistics_read

type: bool

This action allows the reading of the statistics at the Monitoring endpoints.

7.1.62. statistics_delete

type: bool

This action allows to delete statistics at the Monitoring endpoints.

7.1.63. auditlog

type: bool

The administrators are allowed to view the audit log. If the policy contains a user realm, than the administrator is only allowed to see entries which contain this very user realm. A list of user realms may be defined.

To learn more about the audit log, see Audit.

7.1.64. auditlog_download

type: bool

The administrator is allowed to download the audit log.

Note

The download is not restricted to filters, hidden columns and audit age. Thus, if you want to avoid, that an administrator can see older logs or columns, hidden by hide_audit_columns, you need to disallow downloading the data. Otherwise he may download the audit log and look at older entries manually.

7.1.65. auditlog_age

type: string

This limits the maximum age of displayed audit entries. Older entries are not remove from the audit table but the administrator is simply not allowed to view older entries.

Can be something like 10m (10 minutes), 10h (10 hours) or 10d (ten days).

7.1.66. hide_audit_columns

type: string

This species a blank separated list of audit columns, that should be removed from the response and also from the WebUI. For example a value sig_check log_level will hide these two columns.

The list of available columns can be checked by examining the response of the request to the Audit endpoint.

7.1.67. triggerchallenge

type: bool

If set the administrator is allowed to call the API /validate/triggerchallenge. This API can be used to send an OTP SMS to user without having specified the PIN of the SMS token.

The usual setup that one administrative account has only this single policy and is only used for triggering challenges.

New in version 2.17.

7.1.68. hotp_2step and totp_2step

type: string

This allows or forces the administrator to enroll a smartphone based token in two steps. In the second step the smartphone generates a part of the OTP secret, which the administrator needs to enter. (see Two Step Enrollment). Possible values are allow and force. This works in conjunction with the enrollment parameters 2step_clientsize, 2step_serversize, 2step_difficulty.

Such a policy can also be set for the user. See hotp_2step and totp_2step.

Note

This does not work in combination with the enrollment policy verify_enrollment, since the usage of 2step already ensures, that the user has successfully scanned the QR code.

7.1.69. hotp_hashlib and totp_hashlib

type: string

Force the admin to enroll HOTP/TOTP Tokens with the specified hashlib. The corresponding input selector will be disabled in the web UI. Possible values are sha1, sha256 and sha512, default is sha1.

New in 3.2

7.1.70. hotp_otplen and totp_otplen

type: int

Force the admin to enroll HOTP/TOTP Tokens with the specified otp length. The corresponding input selector will be disabled in the web UI. Possible values are 6 or 8, default is 6.

New in 3.2

7.1.71. totp_timestep

type: int

Enforce the timestep of the time-based OTP token. A corresponding input selection will be disabled/hidden in the web UI. Possible values are 30 or 60, default is 30.

New in 3.2

7.1.72. system_documentation

type: bool

The administrator is allowed to export a complete system documentation including resolvers and realm. The documentation is created as restructured text.

7.1.73. sms_gateways

type: string

Usually an SMS token sends the SMS via the SMS gateway that is defined system wide in the token settings. This policy takes a blank-separated list of configured SMS gateways. It allows the administrator to define an individual SMS gateway during token enrollment.

New in version 3.0.

7.1.74. indexedsecret_force_attribute

type: string

If an administrator enrolls an indexedsecret token then the value of the given user attribute is set as the secret. The admin does not know the secret and can not change the secret.

For more details of this token type see Indexed Secret Token.

New in version 3.3.

7.1.75. certificate_trusted_Attestation_CA_path

type: string

An administrator can enroll a certificate token for a user. If an attestation certificate is provided in addition, this policy holds the path to a directory, that contains trusted CA paths. Each PEM encoded file in this directory needs to contain the root CA certificate at the first position and the consecutive intermediate certificates.

An additional enrollment policy certificate_require_attestation, if an attestation certificate is required.

New in version 3.5.

7.1.76. set_custom_user_attributes

type: string

New in version 3.6

This policy defines which additional attributes an administrator is allowed to set. It can also define, to which value the admin is allowed to set such attribute. For allowing all values, the asterisk (“*”) is used.

Note

Commas are not allowed in policy actions value, so the setting has to be defined by separating colons (“:”) and spaces.

Each key is enclosed in colons and followed by a list of values separated by whitespaces, thus values are not allowed to contain whitespaces.

Example:

:department: sales finance :city: * :*: 1 2

:department: sales finance means that the administrator can set an additional attribute “department” with the allowed values of “sales” or “finance”.

:city: * means that the administrator can set an additional attribute “city” to any value.

:*: 1 2 means that the administrator can set any other additional attribute either to the value “1” or to the value “2”.

7.1.77. delete_custom_user_attributes

type: string

This takes a space separated list of attributes that the administrator is allowed to delete. You can use the asterisk “*” to indicate, that this policy allows the administrator to delete any additional attribute.

Example:

attr1 attr2 department

The administrator is allowed to delete the attributes “attr1”, “attr2” and the attributes “department” of the corresponding users.

Note

If this policy is not set, the admin is not allowed to delete any custom user attributes.

New in version 3.6

7.1.78. machinelist

type: bool

The administrator is allowed to list the machines.

7.1.79. manage_machine_tokens

type: bool

The administrator is allowed to attach and detach tokens to machines to enable the use with one of the available appliactions. See Machines.

7.1.80. fetch_authentication_items

type: bool

The administrator is allowed to fetch authentication items of tokens assigned to machines. It grants access to the /machine/authitem endpoints (see Machine endpoints).

7.1.81. clienttype

type: bool

This policy action allows the admin to view the list of clients which authenticate to privacyIDEA at the Client endpoints.

7.1.82. managesubscription

type: bool

The administrator is able to view and change the subscriptions. It grants access to the Subscriptions endpoints.

7.1.83. set_hsm_password

The administrator is able to set the password of the hardware security module. It grants access to the /system/hsm endpoint (see System endpoints).