.. _users_in_policies:

Users in policies
~~~~~~~~~~~~~~~~~
The user field in the policies need a deeper explanation. Please mind the
extensions for scopes `admin`, `system` and `selfservice` for LinOTP >=2.8.1 as
described in user_field_extensions_

Within the scope `admin`, `license`, `audit`  and `system` the user field is
used to enter a list of administrator names.

In the scope `selfservice`, `authorization`, `enrollment` and `authentication`
the user field can be used to specify users and resolvers. Thus the user field
can be used to split policies within realms by users or resolvers.

.. note:: When using the user field you should always define a certain realm
 name in the realm field and not use the `*` for the realms.

Users are specified with the normal username like::

   user1, user2, user3

Resolvers are specified with the name of the resolvers followed by a colon, to
mark this as a resolver::

   resolvername1:, resolvername2:

.. note::

   It is also possible to mix users and resolvers like this::

       user1, resolvername1:, user2, user3

The policy logic works like this:

 1. If a policy in the scope is found for this very user, then this policy is
    applied and all other policies in this scope not containing the user
    are ignored.

 2. The resolver of the user is determined. If a policy in the scope for this
    resolver is found, this policy is applied and the other policies are
    ignored for this user.

 3. If within this scope no policy with the very username and no policy with
    a resolver the user is in is found, than the policies containing no
    user entries are applied for this user.

Imagine a realm `realm1` with two resolvers `resolv1` and `resolv2`. There are
four users, `user1a`, `user1b` and `user1c` in `resolv1` and `user2` in
`resolv2`.

The following policies are defined::

   [pol1] 
   scope = selfservice
   action = webprovisionGOOGLE
   realm = realm1
   user = ""

   [pol2] 
   scope = selfservice
   action = webprovisionGOOGLE, setOTPPIN
   realm = realm1
   user = user1a

   [pol3] 
   scope = selfservice
   action = webprovisionGOOGLE, setOTPPIN, disable
   realm = realm1
   user = user1b, resolv2:

**pol1** will be applied for `user1c` as this policy does not define any user
and as `user1c` or his resolver does not appear in any other policy.

**pol2** will be applied for `user1a` since this user is explicitly listed in
the policy.

**pol3** will be applied for `user1b` as the user is listed in the policy and
it will be applied for `user2` since the resolver of this user is listed in the
policy.

.. _user_field_extensions:

Extensions for user field in LinOTP =>2.8.1
``````````````````````````````````````````````````
Additionally to the traditional configuration LinOTP >=2.8.1 supports a more fine
grained syntax for the user field regarding the scopes `admin`, `system` and
`selfservice`. Now regular expression for user names can be used, there is a
support for domain name matching and LDAP attributes. All these new
configuration methods can be combined.

* Domain Name Matching: **@Domain** - Please mind that this is only a string matching on the
  login name of the user and not a check against the LDAP/AD server

.. code::

 ^john@example               - matches exactly the given login name
                               ("john@example")

 _(production|dev)@example   - matches all users whose name end of
                               "_production@example or _dev@example"

* UserIdResolver and user names: **UserIdResolver:** or **[USER.]UserIdResolver:**

Please mind that if you want to specify all users from a UserIdResolver the
traditional syntax **UserIdResolver:** is still valid and recommended. If
**.UserIdResolver:** is used an user name must be specified to match anybody.
The user name can be a regular expression.

.. code::

 ad2:            - matches all users from UserIdResolver "ad2"

 ^devel.*.ad1:   - matches all users starting with "devel" located at the
                   UserIdResolver "ad1"


* LDAP Attributes: **#ATTRIBUTE** or **#ATTRIBUTE[OPERATOR][CONTENT]**

There are also new operators available for comparing LDAP attributes:

``exist - #``
 this attribute is set (but does not need to have any content)

.. code:: 
 
 Example: 
 
 #mobile    - matches all users who have the attribute "mobile" even if the
              attribute is empty

``equal - ==``     
 user attribute is same as in policy defintion
 
.. code::

 Example: 
 
 #mobile==123456789  - matches all accounts which have the attribute mobile
                       with the exact content "123456789"

``not equal - !=``
 negative of equal

.. code::

 Example: 
 
 #restricted!=true  - matches all accounts where the content of the attribute
                      "restricted" is something else than "true"


``is_in - ~=``
 regex search of definition in user attribute

.. code::

 Example: 
 
 #mobile~=^49       - matches all accounts with the attribute "mobile" which
                      content must start with "49"


Some more complex examples
^^^^^^^^^^^^^^^^^^^^^^^^^^

Matching all users from a certain UserIdResolver and allow them to disable and
enable existing tokens:

.. code::

 Scope: selfservice
 Action: enable, disable
 User: ad_resolver1:

A policy which allows users to enroll SMS token only if they have the `mobile`
attribute set containing anything:

.. code::

 Scope: selfservice
 Action: enrollSMS
 User: #mobile~='.+'


Allow users with a certain domain to enroll HMAC token and resync their tokens
in the Selfservice Portal:

.. code::

 Scope: selfservice
 Action: resync, enrollHMAC
 User: @onedomain.net, @seconddomain.net

This will match all users who's name start with `pass` from the domain
`example.net` and a existing LDAP mobile attribute containing `49` right at the
beginning:

.. code::

 ^pas.*@example.net#mobil ~= ^49