Commit 3977a5cd authored by Andrii Salnikov's avatar Andrii Salnikov

auth and mapping guide

parent c6eb3bdd
Pipeline #5525 passed with stages
in 4 minutes and 2 seconds
......@@ -106,168 +106,43 @@ For production deployment you will need to customize the configuration in accord
The ultimate information about available configuration options can be found in the :doc:`reference` which is also available locally as ``/usr/share/doc/nordugrid-arc-*/arc.conf.reference``.
The most common configuration steps are the explained below.
The most common configuration steps are explained below.
Configure Authorization Rules
-----------------------------
Configure authorization and mapping rules
-----------------------------------------
Authorization rules define who can access the computing element (execute jobs, query info, etc).
ARC CE authorization rules use the concept of *authgroups* configured by :ref:`[authgroup] <reference_authgroup>` blocks.
*Authorization rules* define who can access the computing element (execute jobs, query info, etc).
*Mapping rules* define which grid-users are mapped to which system accounts.
Both authorization and mapping rules in ARC6 rely on the concept of **authgroups**.
Each authgroup represents a set of users, whose identities are matched to configured rules.
Authorization as well as :ref:`mapping <mapping_section>` are then configured based on authgroup membership.
Once defined, authgroups can be applied to filter access to the CE per interface (:ref:`[arex/ws/jobs] <reference_arex_ws_jobs>`, :ref:`[gridftpd/jobs] <reference_gridftpd_jobs>`) and per queue. The ``allowaccess`` option in the corresponding interface block defines the allowed authgroups.
In the shipped configuration the empty ``[authgroup: zero]`` is defined and applied to A-REX WS interface, the effect of which is to deny any access by default.
Example configuration 1
```````````````````````
To authorize a single (or several) person by certificate subject name (SN):
1. Create an authorization group in ``arc.conf`` and specify SN directly with the ``subject`` keyword, or refer to a file that contains list of SNs
.. code-block:: ini
[authgroup: staticdn]
subject = /O=Grid/O=Big VO/CN=Main Boss
[authgroup: dnfromfile]
file = /etc/grid-security/local_users
2. Apply authgroup to target interface or queue:
.. code-block:: ini
[gridftpd/jobs]
allowaccess = staticdn dnfromfile
.. note::
To get instant help for ``arc.conf`` configuration options, use ``arcctl config describe``, e.g.
.. code-block:: console
[root ~]# arcctl config describe authgroup subject
## subject = certificate_subject - Rule to match specific subject of user's
## X.509 certificate. No masks, patterns and regular expressions are allowed.
## multivalued
## default: undefined
Example configuration 2
```````````````````````
To filter access based on VOMS certificate attributes, define one or more :ref:`[authgroup] <reference_authgroup>` blocks using the ``voms`` keyword.
To verify VO membership signatures, ARC CE needs the so-called list of certificates (LSC) files that can be installed by :ref:`arcctl <arcctl>`.
Example configuration for atlas VO [#]_:
1. Deploy LSC files:
.. code-block:: console
[root ~]# arcctl deploy voms-lsc atlas --egi-vo
2. Create authorization group in ``arc.conf``:
.. code-block:: ini
[authgroup: atlas]
voms = atlas * * *
3. Apply authgroup to target interface of queue:
.. code-block:: ini
[queue: atlas]
allowacces = atlas
For more information about possible authgroup options, including LCAS integration please read the [TODO: document] ARC CE System Administrator manual.
Once defined, authgroups can be applied to filter access to the CE per interface (:ref:`[arex/ws/jobs] <reference_arex_ws_jobs>`, :ref:`[gridftpd/jobs] <reference_gridftpd_jobs>`) or per-:ref:`queue <reference_queue>`.
.. [#] In this example and in what follows, a simplified configuration is shown. An actual configuration will in most cases include different authgroups for different VO groups and roles.
The ``allowaccess`` and/or ``denyaccess`` options in the corresponding block define which authgroups are allowed to
access the interface or submit to the queue.
.. _mapping_section:
The :ref:`reference_mapping` used to configure the rules that defines how the particular authgroup members are mapped to OS accounts.
Configure mapping
-----------------
A Grid user should be mapped to a local account to start processes and access files.
In the shipped *zero configuration* the ``[authgroup: zero]`` is defined and applied to A-REX WS interface, the effect of which is to deny any access unless user is listed in the ``testCA.allowed-subjects`` file. The mapping is configured with ``map_to_user`` rule that assign the same ``nobody`` account to everyone in ``zero`` authgroup.
Mapping rules define which Grid users are mapped to which accounts. Several mapping methods are available, depending on requirements.
In the shipped zero configuration, all users that are matched to authgroup ``zero`` are mapped to the same ``nobody`` account that will work with local job forking only:
The typical configuration looks like this:
.. code-block:: ini
[mapping]
map_to_user = zero nobody:nobody
There are several common options to map Grid users:
Accounts pool
`````````````
The most transparent, secure and flexible recommended method is to map authorized users to account pools (so-called ``map_to_pool`` method).
In this approach, every authorized (by being specified in ``[authgroup]``) user will be dynamically mapped to one of the available pooled accounts.
Available pool account names are stored one per line in the *pool* file inside the dedicated directory.
The mapping is temporary, and leased account names are stored in the other file placed in the same directory. They can be reassigned to other users after 10 days of inactivity.
*Example configuration for atlas:*
1. Create an account pool:
.. code-block:: console
[root ~]# mkdir -p /etc/grid-security/pool/atlas
[root ~]# for u in atlas{001..100}; do echo $u >> /etc/grid-security/pool/atlas/pool; done
2. Configure mapping in ``arc.conf`` [#]_:
.. code-block:: ini
[mapping]
map_to_pool = atlas /etc/grid-security/pool/atlas
.. [#] ``atlas`` is the name used in ``[authgroup: atlas]``
Legacy grid-mapfile based mapping
`````````````````````````````````
Legacy grid-mapfile based mapping is *not recommended* for the typical production loads.
In this approach, users are mapped to local accounts based on certificate DNs only. Mapping rules are stored line-by-line in the so-called grid-mapfile that describes which user is mapped to which account, for example::
"/O=Grid/O=NorduGrid/OU=uio.no/CN=Aleksandr Konstantinov" user1
"/O=Grid/O=NorduGrid/OU=hep.lu.se/CN=Oxana Smirnova" user2
In the simplest legacy case ARC can use the grid-mapfile for both authorization and mapping decisions.
*Example configuration for legacy grid-map case:*
.. code-block:: ini
[authgroup: legacy]
file = /etc/grid-security/grid-mapfile
[authgroup: atlas]
voms = atlas * * *
[mapping]
map_with_file = legacy /etc/grid-security/grid-mapfile
Grid-mapfiles in ``arc.conf`` can be also referred as ``[userlist]`` objects and be generated regularly, keeping them up-to-date (from e.g. VOMS database) with ``nordugridmap`` utility that can be used and configured with the ``[nordugridmap]`` block.
Using external LCMAPS rules
```````````````````````````
map_to_pool = atlas /etc/grid-security/pool/atlas
ARC can run an external plugin to map users that can be configured with the ``map_with_plugin`` option.
[gridftpd/jobs]
allowaccess = atlas
To support several production loads, ARC ships with the built-in LCMAPS plugin.
[queue: qatlas]
allowacces = atlas
LCMAPS itself is a third-party tool that should be installed and configured separately, which is beyound the scope of this guide. Consult ARC CE Sysadm Manual [TODO].
Please read the :ref:`auth_and_mapping` document to get familiar with all aspects of this important configuration step.
Provide LRMS-specific information
---------------------------------
......@@ -276,7 +151,6 @@ One more critical configuration step is to supply ARC CE with relevant informati
Specify you LRMS type
`````````````````````
In the ``arc.conf`` there is a dedicated :ref:`[lrms] <reference_lrms>` block that defines the type of your LRMS, as well as several options related to the LRMS behaviour.
For example, to instruct ARC to use SLURM, use the following configuration:
......@@ -298,8 +172,8 @@ In addition to specifying LRMS itself, it is necesssary to list all the queues t
More information about configuring particular LRMS to work with ARC can be found in :ref:`lrms` document.
Configure A-REX
---------------
Configure A-REX Subsystems
--------------------------
The ARC Resource-coupled EXecution service (A-REX) is a core service handling execution and entire life cycle of compute jobs.
......
......@@ -44,7 +44,7 @@ Authgroups should be defined on the top of ``arc.conf`` using the :ref:`referenc
Each authgroup is a named object, that will be referenced by its name during authorization and mapping rules configuration.
There are no special restrictions to the authgroup names except the absence of spaces, so you can even define ``*`` authgroup to blow the mind of other ``arc.conf`` readers.
Each config line in the :ref:`<reference_authgroup>` represent a matching rule that are processed sequentially.
Each config line in the :ref:`reference_authgroup` represent a matching rule that are processed sequentially.
When the matchig criteria of the rule has been satisfied by user identity - the processing stops within this authgroup.
......@@ -57,6 +57,7 @@ All authgroups are evaluated, even if a user already has a match with one of the
.. note::
Notice that:
* authgroup blocks should be defined before referencing!
* authgroup rules within blocks are order-dependent!
* all authgroup blocks are evaluated!
......@@ -112,6 +113,7 @@ In the shipped *zero configuration* the ``[authgroup: zero]`` is defined and app
The effect of this configuration is to allow access to CE only to the subjects stored in the ``testCA.allowed-subjects`` file. This file is empty by default and close down CE access until subjects are added by ``arcctl test-ca usercert``.
.. code-block:: ini
[authgroup:zero]
file = /etc/grid-security/testCA.allowed-subjects
......@@ -121,11 +123,19 @@ The effect of this configuration is to allow access to CE only to the subjects s
Example: subject-based authorization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To authorize users based on certificate subject the :ref:`reference_authgroup_subject` or :ref:`reference_authgroup_file` rules can be used.
The :ref:`reference_authgroup_file` option support both:
* plain list of subjects (each line contains only a subject name),
* grid-mapfile format, when subject name followed by mapped account ID.
In both cases subject name should be enquoted if it contains spaces.
.. code-block:: ini
[authgroup: ban]
subject = /O=Grid/O=Bad Users/CN=
[authgroup: banana]
subject = /O=Grid/O=Bad Users/CN=The Worst
[authgroup: boss]
subject = /O=Grid/O=Big VO/CN=Main Boss
......@@ -134,7 +144,173 @@ Example: subject-based authorization
file = /etc/grid-security/local_users
[gridftpd/jobs]
denyaccess = ban
denyaccess = banana
allowaccess = boss
allowaccess = dnfromfile
Example: VOMS-based authorization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To filter access based on VOMS certificate attributes, define one or more :ref:`[authgroup] <reference_authgroup>` blocks using the :ref:`reference_authgroup_voms` keyword.
To verify VO membership signatures, ARC CE needs the so-called list of certificates (LSC) files that can be installed by :ref:`arcctl <arcctl>`.
Example configuration for atlas and alice VO [#]_:
1. Deploy LSC files:
.. code-block:: console
[root ~]# arcctl deploy voms-lsc atlas --egi-vo
[root ~]# arcctl deploy voms-lsc alice --egi-vo
2. Create authorization group and apply access resctiction to interface and/or queue in ``arc.conf``:
.. code-block:: ini
[authgroup: atlas]
voms = atlas * * *
[authgroup: alice]
voms = atlas * * *
[authgroup: all]
authgroup = atlas
authgroup = alice
[gridftpd/jobs]
allowaccess = all
[arex/ws/jobs]
allowaccess = all
[queue: qalice]
allowacces = alice
[queue: qatlas]
allowacces = atlas
.. [#] In this example and in what follows, a simplified configuration is shown. An actual configuration will in most cases include different authgroups for different VO groups and roles.
.. TODO: Pointer to LCAS intergration when doc is ready
Configure mapping
-----------------
Any grid user should be mapped to a local account to *start processes* and *access files*.
Mapping rules configured in :ref:`reference_mapping` define which grid-users (*specified by authgroup*) are mapped to which system accounts (several mapping methods available).
Rules in the :ref:`reference_mapping` are processed *in a sequence* in line order of the configuration file (from top to bottom).
There are two kind of rules avaiable:
* mapping rules (started with ``map_``) that defines how the particular authgroup members are mapped,
* policy rules (started with ``policy_``) that modifies the mapping rules sequence processing.
**Default policy** for mapping rules processing is:
* processing *CONTINUES* to the next rule if identity of user *DO NOT* match authgroup specified in the rule (can be redefined with :ref:`reference_mapping_policy_on_nogroup` option)
* processing *STOPS* if identity of user matched the authgroup specified in the mapping rule.
Depend on whether this mapping rule returns *valid UNIX identity* the processing can be
redefined with :ref:`reference_mapping_policy_on_map` and :ref:`reference_mapping_policy_on_nomap` options.
Policy can be redefined at the any point of configuration sequence and affects all mapping rules defined *after* the polcy rule.
.. warning::
If mapping process STOPS and there is still no local UNIX identity identified, the user running A-REX will be used (typically ``root`` unless redefined by :ref:`reference_arex_user` option for specific deployment case).
When grid-identity is mapped to ``root`` account - request processing fails implicitely!
Example: mapping to the same account
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :ref:`reference_mapping_map_to_user` option allows to map all authgroup members to the same account specified as an argument.
For example in shipped *zero configuration* all users that are matched to authgroup ``zero`` are mapped to the same ``nobody`` account (and ``nobody`` group) that will work with local job forking:
.. code-block:: ini
[mapping]
map_to_user = zero nobody:nobody
Example: mapping to the accounts pool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The most secure and flexible way is to map authgroup members to account pools (so-called :ref:`reference_mapping_map_to_pool` method). It is recommended to use pools mapping when the resource is under the use of different communities.
In this approach, every member of specified :ref:`authgroup <reference_authgroup>` will be dynamically mapped to one of the available accounts in the configured pool.
Available pool account names are stored one per line in the ``pool`` file inside the dedicated directory.
Accounts from pool are assigned by means of leasing approach.
All leased accounts are stored in the other files placed in the same directory.
They can be reassigned to other users after 10 days of inactivity.
*Example configuration for atlas:*
1. Create necessary number of accounts to be used on ARC CE and Worked Nodes of the cluster.
2. Define ARC accounts pool:
.. code-block:: console
[root ~]# mkdir -p /etc/grid-security/pool/atlas
[root ~]# for u in atlas{001..100}; do echo $u >> /etc/grid-security/pool/atlas/pool; done
2. Configure mapping in ``arc.conf`` [#]_:
.. code-block:: ini
[mapping]
map_to_pool = atlas /etc/grid-security/pool/atlas
.. [#] ``atlas`` is the name used in ``[authgroup: atlas]``
Example: Legacy grid-mapfile based mapping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
Legacy grid-mapfile based mapping is **NOT recommended** for the typical production loads.
In the grid-mapfile approach users are mapped to local accounts based on certificate DNs only.
Mapping rules are stored line-by-line in the so-called grid-mapfile that describes which user is mapped
to which account, for example::
"/O=Grid/O=NorduGrid/OU=uio.no/CN=Aleksandr Konstantinov" user1
"/O=Grid/O=NorduGrid/OU=hep.lu.se/CN=Oxana Smirnova" user2
In the simplest legacy case ARC can use the grid-mapfile for both authorization and mapping decisions.
*Example configuration for legacy grid-mapfile case:*
.. code-block:: ini
[authgroup: legacy]
file = /etc/grid-security/grid-mapfile
[mapping]
map_with_file = legacy /etc/grid-security/grid-mapfile
Grid-mapfiles in ``arc.conf`` can be also referred as a :ref:`[userlist] <reference_userlist>` objects and be generated regularly, keeping them up-to-date (from e.g. VOMS database) with ``nordugridmap`` utility that can be used and configured with the :ref:`reference_nordugridmap`
.. note::
You can find more information about moving from grid-mapfiles in the `The life without gridmapfiles <https://indico.lucas.lu.se/event/1020/material/slides/11.odp>`_ presentation.
Example: mapping with external LCMAPS rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ARC can run an external plugin to map users that can be configured with the :ref:`reference_mapping_map_with_plugin` option.
To support several production loads, ARC ships with the built-in LCMAPS plugin included in A-REX package:
.. code-block:: ini
[authgroup:all]
all = yes
[mapping]
map_with_plugin = all 30 /usr/libexec/arc/arc-lcmaps %D %P liblcmaps.so /usr/lib64 /etc/lcmaps/lcmaps-arc-argus.db arc
LCMAPS itself is a third-party tool that should be installed and configured separately, which is beyound the scope of this guide.
.. TODO: port LCMAPS configuration guide from Sysadm Manual
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment