Enrollment Policies
-------------------

Enrollment Policies are checked during the enrollment process of a token. This
applies for administrative enrollment or user self enrollment.

Token limits per Realm
~~~~~~~~~~~~~~~~~~~~~~

You may limit the number of tokens that are managed within a realm. This is
done by defining a policy consisting of

 * Policy name: This is the unique name of the policy.
 * Scope: You need to set this to **enrollment**.
 * Realm: Enter the name of the realm here.
 * Action: This field is comma separated. It should contain the keyword
   **tokencount = <tokennumber>**.

Using the action *tokencount* you may allocate specified numbers of tokens to
your different realms.

You may for example have a license with 1000 tokens, but one of your five
realms should only be able to manage a maximum of 80 tokens, since this realm
is managed by another department.

.. note:: Each realm, for which no *tokencount* is defined, may use as many
 tokens as possible.

Token limits per user
~~~~~~~~~~~~~~~~~~~~~

You may limit the number of tokens that can be assigned to a user. It is possible to limit the number of tokens per user in total and the numbers of tokens per user by type.

Total number of tokens per user:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * Policy name: This is the unique name of the policy.
 * Scope: You need to set this to **enrollment**.
 * Realm: Enter the name of the realm, that contains the users who should be
   restricted in the number of tokens owned.  
 * Action: This field is comma separated. It should contain the keyword
   **maxtoken = <tokennumber>**.
 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

.. note:: If there is no *maxtoken* defined for a realm, then you may enroll as
 many tokens as possible for a single user.

Number of tokens per user by type:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Starting with LinOTP 2.10 it is possible to limit the number of tokens per user by type. Any additionally configured **maxtoken** action as described above will limit the total number of tokens per user.

 * Policy name: This is the unique name of the policy.
 * Scope: You need to set this to **enrollment**.
 * Realm: Enter the name of the realm, that contains the users who should be
   restricted in the number of tokens owned.  
 * Action: This field is comma separated. It should contain the keyword
   **maxtoken<TokenTyp> = <tokennumber>**.
 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

**Example:**

Allow every user to have maximal 1 SMS, 2 HMAC token and 5 in total:

.. code::

 [maxtoken]
 action = "maxtokenSMS=1, maxtokenHMAC=2, maxtoken=5,"
 user = *
 realm = *
 time = * * * * * *;
 client = *
 scope = enrollment
 active = True
..

Random OTP PIN
~~~~~~~~~~~~~~
During enrollment a random OTP PIN may be set. This is done per realm by
defining the policy:

 * Policy name: This is the unique name of the policy.
 * Scope: You need to set this to **enrollment**.
 * Realm: Enter the name of the realm, that contains the users who should be
   restricted in the number of tokens owned.  
 * Action: This field is comma separated. It should contain the keyword
   **otp_pin_random = <length>**. This will create a random OTP PIN with the
   given length during token initialization.
 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

.. note:: If there is no otp_pin_random defined for a realm, than no PIN is set
 during enrollment. If a random OTP PIN is set, it is not possible to view this
 PIN. This means, that the user or the administrator has to reset the OTP PIN.

Encrypted OTP PIN
~~~~~~~~~~~~~~~~~
During setting an OTP PIN this policy defines, if the OTP PIN will be stored as
hashed value or as an encrypted value. The default behavior is to store the
OTP PIN as a hashed value.

 * Policy name: This is the unique name of the policy.
 * Scope: You need to set this to enrollment.
 * Realm: Enter the name of the realm, that contains the tokens, the policy
   should be valid for.
 * Action: This field is a comma separated list. It should contain the keyword
   otp_pin_encrypt = 1.

.. note:: The encrypted value can be decrypted again. This is used in case of
 getOtp function. Usually it is a good idea to leave this untouched.

Token issuer
~~~~~~~~~~~~~

It is possible to set a token issuer for OATH token which is displayed e.g. in
the Google Authenticator or other token apps.

You may define a policy which defines the token issuer.

 * Policy name: This is the unique name of the policy.
 * Scope: **enrollment**
 * Realm: Enter the name of the realm the policy should be valid for. Newly
   generated tokens in this realm will be labeled accordingly.
 * Action: This is a comma separated list.
   It should contain **tokenissuer=<string>**, where <string> may contain
   arbitrary characters/strings and placeholders:

   - <u> will be replaced with the name of the user
   - <r> will be replaced with the name of the realm
   - <s> will be replaced with the serial number of the token.
   - <d> will be replaced with the token description.

 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

.. Broken in 2.9: If no policy can be found, then the token issuer will be
 "LinOTP" by default.

**Example:** *issuer=my_company* will result in an issuer *my_company* and will
be displayed in the token applications accordingly.


Token labels
~~~~~~~~~~~~
It is possible to set a token label for the Google Authenticator and OATH
token. This policy defines the content of the token label - it may contain
arbitrary text and variables.

 * Policy name: This is the unique name of the policy.
 * Scope: **enrollment**
 * Realm: Enter the name of the realm, that contains the tokens, the policy
   should be valid for. The tokens of users in this realm will be labeled
   accordingly.
 * Action: This is a comma separated list. 
   It should contain **tokenlabel=<string>**, where <string> may contain
   arbitrary characters/strings and placeholders:

   - <u> will be replaced with the name of the user
   - <r> will be replaced with the name of the realm
   - <s> will be replaced with the serial number of the token.
   - <d> will be replaced with the token description.

 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

If no policy can be found or the token is not assigned to any user, then the
token will be labeled with the serial number.

**Example:** *tokenlabel=<u>@<r>* will result in a label like *username@realm1*.
*tokenlabel=ourtokens_<s>* will result in something like
*outtokens_oath1278489*.

.. _policy_autoassignment:

Auto Assignment
~~~~~~~~~~~~~~~
Enrolling tokens to users can be a time consuming process. With auto assignment
LinOTP provides an easy way to assign existing tokens to users which don't have
a token yet. One can configure auto assignment like this:

First you need to import the token seed file and set the token realm of these
tokens.

Then you need to configure an auto assignment policy.

After having done so, the enrollment workflow is as follows:

   1. Tokens are set to realmA but not assigned.
   2. The user, who is in realmA, grabs any of those realmA tokens.
   3. Now he authenticates against LinOTP using his user store password, which
      will be either the passwd-password, the LDAP-password or his
      SQL-password and an OTP value from the token he just grabbed.

.. note:: Please have a look at the
         :ref:`policy-autoassignment_without_password` if no password should 
         be required.
..

   4. LinOTP will check, - if the auto assignment policy
      is set for this realm,

      - if the user has not yet any token assigned,
      - if the user provided the right password,
      - and then look up the token for the given OTP value in the tokens of realmA that are not yet assigned.

   5. LinOTP then will assign the found token to the user and set the user
      store password as OTP PIN.
   6. The user is successfully authenticated and will have to use this very
      token for all future logins.

The auto assignment policy is defined like this:

 * Policy name: This is the unique name of the policy.
 * Scope: **enrollment**
 * Realm: Enter the name of the realm, that contains the tokens, the policy
   should be valid for. The tokens of users in this realm will be labeled
   accordingly.
 * Action: This is a comma separated list. It should contain:
           **autoassignment** (LinOTP version >=2.8)
           or
           **autoassignment=<int>**, where <int> is either 1 for *active* or
           0 for *deactivated*. (LinOTP version <=2.7.2.1)
 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

.. note:: Please be aware: If a token is auto assigned the password from the
 UserIdResolver is stored as PIN in the LinOTP database. This will happen even
 if policies are configured like *otp_pin_random* or *otppin=1* or *otppin=2*.
 You can avoid this behaviour with a policy  *ignore_autoassignment_pin* as
 described below. Otherwise we recommend for security reasons to request the
 users to set in individual PIN in the Selfservice Portal after the auto
 assignment.  The necessary policy *setOTPPIN* is described in
 :ref:`self_service_policies`

.. note:: Auto assignment only works for users without tokens.

Ignore Auto Assignment Pin
~~~~~~~~~~~~~~~~~~~~~~~~~~
When using the auto assignment feature the user is identified by his login name
and by the password (PIN), while the token is identified by the otp value. If
the identification of user and token was successful, by default the password of
the user will be used as PIN of the token. To prevent this behaviour the
ignore_autoassignment_pin policy can be set.

.. _policy-autoassignment_without_password:

Autoassigment without Password Check
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting with LinOTP 2.10 a new action is available for auto assignment:
**autoassignment_without_password**. In difference to the regular
auto assignment the user's password is not required for the token assignment.
So the user authenticates with name and OTP value only and the auto assignment
is performed. This is useful for environments where the user's password has
already been validated otherwise.

 * Policy name: This is the unique name of the policy.
 * Scope: **enrollment**
 * Realm: Enter the name of the realm, that contains the tokens, the policy
   should be valid for. The tokens of users in this realm will be labeled
   accordingly.
 * Action: This is a comma separated list. It should contain:
           **autoassignment_without_password**
 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

.. _policy-losttoken:

Lost token
~~~~~~~~~~
.. index::
   Lost token

When a user looses a token, the help desk can enroll a temporary token that
will replace the lost token.  The lost token will be disabled. The OTP PIN of
the lost token will be used for the new temporary token. The administrator or
the help desk employee do not know the token PIN - it is transfered by LinOTP
to the new token. The temporary token will be a long static password and will
only be valid for a restricted period of time. The length of the password and
the validity period can be configured using a enrollment policies:

 * Scope: **enrollment**
 * Action: **lostTokenPWLen=<length of password>** (default = 10)
 * Action: **lostTokenValid=<length of validity period>** (in days, hours, minutes, seconds, defaults to 10 days) 
 * Action: **lostTokenPWContents=<contents of the temporary password>**
 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.



**Explanation for lostTokenValid:**

The following time units can be used:

**d**: days (default)

**h**: hours (LinOTP 2.10+)

**m**: minutes (LinOTP 2.10+)

**s**: seconds (LinOTP 2.10+)

**Examples:**
 
.. code::

   lostTokenValid=12h
   lostTokenValid=5d
   lostTokenValid=1d12h
   lostTokenValid=5h30m30s
..

**Explanation of lostTokenPWContents**

The contents is described by these characters:

**C**: The password will contain upper characters.

**c**: The password will contain lower characters.

**n**: The password will contain digits/numbers.

**s**: The password will contain special characters.

**Example**: A temporary token with lostTokenPWLen=10, lostTokenValid=30 will
get a 10 characters static password created and will be valid for the next 30
days.

.. _policy-purge_rollout_token:

Purge rollout tokens
~~~~~~~~~~~~~~~~~~~~
.. index::
    Purge Rollout Token

Starting with LinOTP 2.10.3 a token can be marked as rollout token. In
consequence this token can only be used for the login to the self service
portal. This can be very useful for the initial token rollout in combination
with a MFA protected self service. The user gets the rollout token, logs into
the self service and enrolls the actual token.

This policy will delete the rollout token automatically after the user has
successfully authenticated with another token. So this is a clean up function
for unnecessary (because successfully used) rollout token. 

 * Policy name: This is the unique name of the policy.
 * Scope: **enrollment**
 * Realm: Enter the name of the realm, that contains the tokens, the policy
   should be valid for. The tokens of users in this realm will be labeled
   accordingly.
 * Action: This is a comma separated list. It should contain:
           **purge_rollout_token**
 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

.. _policy-u2f_app_id:

U2F App ID
~~~~~~~~~~~
.. index::
    U2F App ID

This policy defines which application IDs can be validated via FIDO U2F in LinOTP.

 * Policy name: This is the unique name of the policy.
 * Scope: **enrollment**
 * Realm: Enter the name of the realm, that contains the tokens, the policy
   should be valid for. The tokens of users in this realm will be labeled
   accordingly.
 * Action: This is a comma separated list. It should contain:
           **u2f_app_id=APPID**
 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

More details about U2F can be found here: https://www.linotp.org/doc/latest/part-management/managingtokens/fido_u2f.html 

.. _policy-u2f_valid_facet:

U2F Valid Facet
~~~~~~~~~~~~~~~
.. index::
    U2F Valid Facet

This policy defines which URLs can be validated via FIDO U2F in LinOTP.

 * Policy name: This is the unique name of the policy.
 * Scope: **enrollment**
 * Realm: Enter the name of the realm, that contains the tokens, the policy
   should be valid for. The tokens of users in this realm will be labeled
   accordingly.
 * Action: This is a comma separated list. It should contain:
           **u2f_valid_facets=URL1;URL2**
 * User: Here you can enter a list of usernames or resolvers. See
   :ref:`users_in_policies` for more details.

More details about U2F can be found here: https://www.linotp.org/doc/latest/part-management/managingtokens/fido_u2f.html