.. _user_policies:

User Policies
-------------

.. index:: selfservice policies, user policies

In the Web UI users can manage their own tokens.
User can login to the Web UI with the username of their
useridresolver. I.e. if a user is found in an LDAP resolver pointing
to Active Directory the user needs to login with his domain
password.

User policies are used to define, which actions users are
allowed to perform.

.. index:: client policies

The user policies also respect the ``client`` input, where you
can enter a list of IP addresses and subnets (like 10.2.0.0/16).

Using the ``client`` parameter you can allow different actions in
if the user either logs in from the internal network
or remotely from the internet via the firewall.

Technically user policies control the use of the REST API
:ref:`rest_token` and are checked using :ref:`code_policy` and
:ref:`policy_decorators`.

.. note:: If no user policy is defined, the user has
   all actions available to him, to manage his tokens.

The following actions are available in the scope
*user*:

enroll
~~~~~~

type: bool

There are enrollment actions per token type, e.g. ``enrollHOTP``.
The user is only allowed to enroll such specified token types.

assign
~~~~~~

type: bool

The user is allowed to assign an existing token, that is
located in his realm and that does not belong to any other user,
by entering the serial number.

disable
~~~~~~~

type: bool

The user is allowed to disable his own tokens.
Disabled tokens can not be used to authenticate.

enable
~~~~~~

type: bool

The user is allowed to enable his own tokens.

delete
~~~~~~

type: bool

The user is allowed to delete his own tokens from the database.
Those tokens can not be recovered. Anyway, the audit log concerning
these tokens remains.

unassign
~~~~~~~~

type: bool

The user is allowed to drop his ownership of the token.
The token does not belong to any user anymore and can be
reassigned.

resync
~~~~~~

type: bool

The user is allowed to resynchronize the token if it has got out
of synchronization.

reset
~~~~~

type: bool

The user is allowed to reset the failcounter of the token.

setpin
~~~~~~

type: bool

The user is allowed to set the OTP PIN for his tokens.

setrandompin
~~~~~~~~~~~~

type: bool

If the ``setrandompin`` action is defined, the user
is allowed to call the endpoint, that sets a random PIN on his
specified token.

setdescription
~~~~~~~~~~~~~~

type: bool

The user is allowed to set the description of his tokens.

enrollpin
~~~~~~~~~

type: bool

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

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.

otp_pin_maxlength
~~~~~~~~~~~~~~~~~

.. index:: PIN policy, Token specific PIN policy

type: integer

range: 0 - 31

This is the maximum allowed PIN length the user 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.

otp_pin_minlength
~~~~~~~~~~~~~~~~~

type: integer

range: 0 - 31

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

otp_pin_contents
~~~~~~~~~~~~~~~~

type: string

contents: cns

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

This takes the same values like the admin policy :ref:`admin_policies_otp_pin_contents`.

otp_pin_set_random
~~~~~~~~~~~~~~~~~~

type: int

The length of a random PIN set by the user.

auditlog
~~~~~~~~
type: bool

This action allows the user to view and search the audit log
for actions with his own tokens.

To learn more about the audit log, see :ref:`audit`.

auditlog_age
~~~~~~~~~~~~

type: string

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

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

hide_audit_columns
~~~~~~~~~~~~~~~~~~

type: string

This species a blank separated list of audit columns, that should be removed
from the response (:ref:`rest_audit`) 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 :ref:`rest_audit`.

updateuser
~~~~~~~~~~

.. index:: Edit User

type: bool

If the ``updateuser`` action is defined, the user is allowed to change his
attributes in the user store.

.. note:: To be able to edit the attributes, the resolver must be defined as
   editable.

userlist
~~~~~~~~

type: bool

If the ``userlist`` action is defined, the user is
allowed to view his own user information.

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.


password_reset
~~~~~~~~~~~~~~

.. index:: reset password, password reset

type: bool

Introduced in version 2.10.

If the user is located in an editable user store, this policy can define, if
the user is allowed to perform a password reset. During the password reset an
email with a link to reset the password is sent to the user.


.. _user_policy_2step:
.. _hotp-2step:
.. _totp-2step:

hotp_2step and totp_2step
~~~~~~~~~~~~~~~~~~~~~~~~~

type: string

This allows or forces the user to enroll a smartphone based token in two steps.
In the second step the smartphone generates a part of the OTP secret, which the user
needs to enter. (see :ref:`2step_enrollment`).
Possible values are *allow* and *force*.
This works in conjunction with the enrollment parameters :ref:`2step_parameters`.

Such a policy can also be set for the administrator. See :ref:`admin_policy_2step`.

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

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 user to define an individual SMS gateway during token enrollment.

New in version 3.0.

.. _hotp-hashlib:
.. _totp-hashlib:

hotp_hashlib and totp_hashlib
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

type: string

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

.. _hotp-otplen:
.. _totp-otplen:

hotp_otplen and totp_otplen
~~~~~~~~~~~~~~~~~~~~~~~~~~~

type: int

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

.. _hotp-force-server-generate:
.. _totp-force-server-generate:

hotp_force_server_generate and totp_force_server_generate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

type: bool

Enforce the key generation on the server.
A corresponding input field for the key data will be disabled/hidden
in the web UI.
Default value is *false*.

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*.

indexedsecret_force_attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

type: string

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

For more details of this token type see :ref:`indexedsecret_token`.

New in version 3.3.

.. _user_trusted_attestation_CA:

certificate_trusted_Attestation_CA_path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

type: string

A user can enroll a certificate token.
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 :ref:`require_attestation`, if an attestation certificate
is required.

New in version 3.5.


.. _user_set_custom_user_attributes:

set_custom_user_attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~

type: string

This defines how a user is allowed to set his own attributes.
It uses the same setting as the admin policy :ref:`admin_set_custom_user_attributes`.

.. note:: Using a '*' in this setting allows the user to set any attribute or any value and thus the user
   can overwrite existing attributes from the user store. If policies, depending on user attributes
   are defined, then the user would be able to change the matching of the policies.
   Use with CAUTION!

New in version 3.6

.. _user_delete_custom_user_attributes:

delete_custom_user_attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

type: string

This defines how a user is allowed to delete his own attributes.
It uses the same setting as the admin policy :ref:`admin_delete_custom_user_attributes`.

.. note:: Using a '*' in this setting allows the user to delete any attribute and thus the user
   can change overwritten attributes and revert to the user store attributes.
   If policies, depending on user attributes
   are defined, then the user would be able to change the matching of the policies.
   Use with CAUTION!

New in version 3.6
