LCMAPS is the Local Credential Mapping Service takes care of translating grid credentials to Unix credentials local to the site. Using the pool account (http://www.gridsite.org/gridmapdir/) mechanism, extended to dynamic groups when needed, takes case of ensuring that different individuals on the grid remain distinct unix accounts. Using goup mappings based on the user's VO attributes, isolation and scheduling priority decisions can be made. It can also verify the validity and authenticity of the incoming grid credentials, just like when you would have established a TLS connection over a network. This 'verify_proxy' plugin can also enforce life time constraints on the proxy.

Quick install guide

To the LCMAPS quick install...

High Level Description

The Local Credential Mapping System (LCMAPS) is a pluggable framework, implemented as a library, that can be used by applications to map incoming grid identities to local Unix-style identities, in particular a uid and a set of gids, based on a site-local policy. The native interface to the LCMAPS system needs as inputs the target user’s credential chain. The framework then either returns successfully after enforcing the appropriate credentials, or returns an error that must be interpreted as a failure on which the invoking application must exit.

The pre-web services Globus gatekeeper, into which LCMAPS was initially integrated, requires the Unix uid to be returned, as it will itself re-enforce mapping of this uid using the setuid(2) call. Therefore, the legacy-gatekeeper interface to LCMAPS returns the Unix uid, since re-enforcing the current Unix uid is allowed by the setuid(2) call.

Additional interfaces to LCMAPS were developed for incorporation in other frameworks. This includes interfaces that direct LCMAPS and the underlying VOMS libraries do not validate the incoming credential chain, for those deployment models where only the literal value of the attributes is needed, and no trust anchors are available to LCMAPS and the VOMS library to perform credential chain validation (i.e. for the GUMS module).

Acquisition and Enforcement

The LCMAPS framework. The evaluation manager invoked the business logic of each of the modules in the order defined in the LCMAPS policy.

The execution of the LCMAPS credential mapping framework consists or two parts or phases: acquisition – where the list of local credentials is derived from the incoming credential chain and the environment, and enforcement, where the acquired local credentials are enforced within the running process and in any operating-system-level account databases. The two phases are separated since the acquisition modules have a need to access protected data (passwords, PKI key pairs, databases or state directories on the file system) in order to translate grid credentials to a local user identity. Enforcement modules also may need to be invoked in a specific order, with the POSIX-in-process Unix uid and gid changes (setuid, initgroups) last – this allows other enforcement modules to read in private data they need (e.g. credential needed to update an LDAP server). The business logic diagram of the LCMAPS framework is depicted in the figure.

The LCMAPS system uses a configuration file that contains the module definitions and the policy definition in the form of a finite-state machine. This configuration file has to be accessible by a standard open(2) call, i.e., on a POSIX-style filesystem.

Acquisition plug-ins

The execution of the LCMAPS plug-ins is driven by a credential acquisition policy expressed as a series of state transitions that are driven by the success or failure of a module invocation. A basic set of modules is provided with the system, with additional modules contributed by third parties to integrate with mapping policy generators such as GP-Box.

localaccount: derive local Unix account based on the identity subject name only.
poolaccount: derive local Unix account from a pool of generic, non-preassigned account, based on the identity subject name and the current state of the pool. The association between a pool account and a grid identity subject name is made when a new identity mapping is attempted. The mapping created will be re-used whenever this same subject name is presented. To release this association, and external utility such as lcg-expire-gridmap from the gLite middleware must be used that dissociates the account and ensures no tasks or persistent state from the account remain present in the system. When used in combination with a group-mapping module and enforcement modules that can associate the assigned gid with the uid across all systems where the uid is to be used (e.g. on the worker nodes in a cluster environment), the account pool can use generic account that are not pre-assigned to a particular group or set of VOMS attributes. If no consistent enforcement can be done, the poolaccounts need to be pre-associated to the appropriate groups via system-local mechanisms (e.g. fixed group membership in the passwd and group account databases).
vomslocalaccount, vomslocalgroup: similar to localaccount, this module associates local Unix accounts to VOMS attributes. The first attribute in the ordered list in the attribute certificate that corresponds to a local uid mapping is used. All attributes are taken into account when assigning gids, with the first attribute corresponding to a local gid mapping being selected as the Unix primary gid.
vomspoolaccount: this module combines the functionality of VOMS parsing with that of the poolaccount module. Most installations of LCMAPS use this modules in their primary mapping policy.
vomspoolgroup: conceptually similar to the poolaccount module, this module can allocate one or more gids based on the incoming set to attributes. This may be useful in scenarios where only conventional Unix ownership semantics (not Posix ACLs) are used in storage systems connected to the grid, and where dynamic intra-VO access controls need to be provided. To ensure long-term ownership consistency, each combination of groups generated by the vomspoolgroup module must be complemented with a unique poolaccount. Due to the potential for a combinatoric explosion of poolaccounts and poolgroups, the use of vomspoolgroup for emulating fine-grained ACLs on top of conventional Unix file ownership semantics is not encouraged.
gums: to be used when using the old (legacy) GUMS/PRIMA framework. It calls for an executable and expects a numerical output on the standard output representing the target uid and gid separated by a space.
verify-proxy: this plug-in will verify the validity of the incoming credential chain, and will in particular also check if any of the proxies in the chain have a validity period that exceeds a site-specified maximum. The site maximum can be specified independently for the first delegation (i.e. the delegation signed by the end-entity certificate), and for any subsequent proxies.
scas-client: to be used to talk to a SCAS service, using the Joint SAML2XACML2 protocol and the Common Obligation and Attribute set.

Enforcement plug-ins

After all relevant local credentials are collected in the framework’s credential store, they are enforced by a set of modules that implement the actual credential mapping:

posix_enf: Change the uid, the primary gid and the supplementary gids of the currently running process, using the set(e)uid, set(e)gid, initgroups, and setgroups system calls. The uid, pgid and supplementary gids to use are taken from the credential store in the LCMAPS framework.
ldap_enf: Create or update Posix account information in a site’s local user database stored in a LDAP directory system using the posixAccount and posixGroup objects in the NIS schema. The use of a directory service is required in a cluster computing system, since the actual account mapping in re-done on the individual worker nodes that make up the cluster, outside the process space of the batch submission itself. The uid, pgid and supplementary gids to use are taken from the credential store in the LCMAPS framework; if the uid already exists in the directory, the pgid thereof is updated appropriately.
afs: In case access to an AFS filesystem is required to use a particular account mapping, e.g. in case the account’s home directory is located on an AFS filesystem, this module will acquire an AFS token on behalf of the user by connecting to a gssklog daemon daemon with access to the kerberos data.

Besides, a logging module is provided that can be configured as part of the enforcement chain. This module records basic mapping information in the JobRepository database.

User Guide

The policy expression and plugin capabilities of LCMAPS are different (and a lot richer) than those of LCAS. The policy in LCMAPS is expressed as a 'state machine', and has multiple entry points that can be invoked from the calling application or service. An automatic fall-through mechanism helps to find an applicable policy, and allows stacking of policies.

An example for a CE might be

# Only for performing VOMS mappings
# NOTE: NO WHITESPACE ALLOWED AT THE END OF THE LINE!!!
path = /opt/glite/lib/modules
# module definitions
posix_enf =    "lcmaps_posix_enf.mod -maxuid 1 -maxpgid 1 -maxsgid 32"
localaccount = "lcmaps_localaccount.mod -gridmapfile /etc/grid-security/grid-mapfile"
poolaccount =  "lcmaps_poolaccount.mod -override_inconsistency -gridmapfile /etc/grid-security/grid-mapfile"
               "-gridmapdir /share/gridmapdir"
vomslocalgroup =   "lcmaps_voms_localgroup.mod -groupmapfile /etc/grid-security/groupmapfile -mapmin 0"
vomslocalaccount = "lcmaps_voms_localaccount.mod -gridmapfile /etc/grid-security/grid-mapfile -use_voms_gid"
vomspoolaccount =  "lcmaps_voms_poolaccount.mod -gridmapfile /etc/grid-security/grid-mapfile "
                   "-gridmapdir /share/gridmapdir -do_not_use_secondary_gids"

# for gridftp related code
good = "lcmaps_dummy_good.mod"

# policies
withvoms:
vomslocalgroup -> vomslocalaccount
vomslocalaccount -> posix_enf | vomspoolaccount
vomspoolaccount -> posix_enf

standard:
localaccount -> posix_enf | poolaccount
poolaccount -> posix_enf

whereas a policy for a GridFTP server needs to stanza's (as the policy in invoked twice due to the structure of the FTP protocol):

# policies to support both GMF and VOMS
voms_acq:
vomsextract -> vomslocalgroup
vomslocalgroup -> vomspoolaccount
vomspoolaccount -> good | vomslocalaccount

standard_acq:
poolaccount -> good | localaccount
localaccount -> good

voms_enf:
vomsextract -> vomslocalgroup
vomslocalgroup -> vomspoolaccount
vomspoolaccount -> posix_enf | vomslocalaccount
vomslocalaccount -> posix_enf

standard_enf:
poolaccount -> posix_enf | localaccount
localaccount -> posix_enf

and the LCMAPS framework is instructed to read separate policies for acquisition and enforcement:

gridftpd_lcas_lcmaps_opts="
  ...
  -lcmaps_policies_acq voms_acq,standard_acq \
  -lcmaps_policies_enf voms_enf,standard_enf \
  ...

More complex configurations

In some cases, for example if you want to use multiple grid-mapfiles for different user groups, or for ther reasons where you want to re-use the same module more than once in the policy, you need to be mindful of the following restrictions:

LCMAPS uses the operating system's dynamic loader. On most operating systems, this will prevent loading of the same shared object more than once. Worse, the operating system is very clever and uses the 'inode' and file system on which is resides to determine whether or not the module is 'the same'.
A loaded module cannot be run more than once per policy
The name of the module is used as-is in the policy

So, if you want to re-run the same module you must:

make a physical copy (no symbolic link) to the shared object, down to the ".0.0.0" &c level if needed
name it with a new (comprehensible) name, and keep it in the same module load path
use the new module with the new name in the policy

Other complex examples will be added here in the future.

verify-proxy and restricting proxy and VOMS lifetime

You can add a maximum lifetimes policy to the verify-proxy plug-in configuration to restrict the lifetimes of the proxies at each delegation step (referred to as levels) and the lifetime of the VOMS attributes.

Restricting by proxy lifetime

It will match the maximum lifetime of the proxy certificate with the option --max-proxy-level-ttl. You must specify explicitly for which delegation (for which level in the certificate chain) the maximum lifetime is to be enforced. Level 0 (=zero) is the first delegation in the chain, the first proxy certificate in the certificate chain. Level 1 is the proxy delegation following the previous delegation, and so on. The maximum amount of delegation for which a maximum lifetime is selectable is 10 (e.g. 0 to 9).

A special option is to specify the maximum lifetime for the final proxy delegation also referred to as the Leaf proxy. The amount of delegation in the chain is irrelevant for this option. The lifetime of the last and final delegation of the certificate chain will be compared with this level. This might exceed the expressible amount of 10 explicit maximum lifetime delegation levels.

Restricting by VOMS lifetime

It will match the maximum lifetime of the VOMS attributes with the option --max-voms-ttl. This option takes a period of time as input. All VOMS attributes must have a lifetime less or equal to the declared maximum lifetime.

Options

Expressing the maximum lifetime in days, hours and minutes:

TIMEPERIOD = ((((([0-9])[0-9][dD]-)[0-9])[0-9]:)[0-9])[0-9]
example matches:
12d-13:37
2d-13:37
13:37
3:37
37
7

Options:

--max-voms-ttl TIMEPERIOD
--max-proxy-level-ttl[=@][0-9lL] TIMEPERIOD

Example:

verifyproxy = "lcmaps_verify_proxy.mod"
              " -certdir /etc/grid-security/certificates"
              " --max-voms-ttl 2d:00:00"
              " --max-proxy-level-ttl=0 14d:00:00"
              " --max-proxy-level-ttl=L 12:00"

Installation

The LCMAPS packages are part of the standard gLite distribution and can be obtained from the gLite repository pages or from etics. On a typical CE system, you will have the following packages (versions are lower limits):

glite-security-lcmaps-plugins-scas-client-0.2.8-1.slc4
glite-security-lcmaps-plugins-voms-1.3.7-5.slc4
glite-security-lcmaps-plugins-verify-proxy-1.3.2-1.slc4
glite-security-lcas-lcmaps-gt4-interface-0.0.14-2.slc4
glite-security-lcmaps-plugins-basic-1.3.8-2.slc4
glite-security-lcmaps-without-gsi-1.4.2-1.slc4
glite-security-lcmaps-1.4.3-4.slc4

Configuration

The LCMAPS framework uses the lcmaps.db to initialize and run the plug-ins. The lcmaps.db file is formated with the Policy Description Language (PDL). Details about the file format and how it will be interpreted and used can be found in the document PDL implementation.

Developer Guide

Additional information and the interfaces to use LCMAPS from your own application or service, please refer to the API documentation. The preferred interface today is the PEM-string one. The GSSAPI gss_cred_t interface is a legacy interface.

LCMAPS

Contents