.. _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 and there is
support for domain name matching. 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"

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:


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