Author: Oscar Koeroo <okoeroo@nikhef.nl>
Title: HOW TO: install SCAS


Description:
------------
The Site Central Authorization Service (SCAS) is a Web Service that allows
client programs to query for an authorization decision based upon user
credentials to access a particular resource. The result of the query will either
be an allow or deny. When the service decided to send an allow message to its
requesting client it may include obligations. These obligations are undeniable
and MUST be processed. The returned obligations can tell the client on which
terms the credentials were allowed. In our case with the SCAS (and also with
GUMS/PRIMA/gPlazma use cases) this will be Unix account mapping obligations (and
other use case specific attributes).

When a SCAS is queried for a authorization decision it receives user credentials
among other pieces of information that tells the SCAS more about the query's
origin. The SCAS is mostly interested in the user credentials. The user
credentials are extracted from the query and processed in Local Centre
Authorization Service (LCAS) and Local Credential Mapping Service (LCMAPS).

On the return of the allow message from the SCAS back to the client, the LCMAPS
mapping result will be transported back to the client in the form of an
obligation that holds sufficient information to perform an LCMAPS mapping on the
client side. The type of obligations may be extended to support other type of
clients. But for now all LCMAPS based clients are supported (like the GT4
gatekeepers with LCMAPS and gLExec). This will be extended to
GUMS/PRIMA/gPlazma.


Prerequisite:
-------------
The SCAS service will perform the credential mapping based on the SCAS client
requests. The default result will be the Unix UID and Unix GIDs in their numeric
form. The numeric form of the UIDs and GIDs are numbers found on the system of
the SCAS service in the groups and passwd files. Therefor the UIDs and GIDs
between the SCAS clients and SCAS service must be fully consistent.


Install instructions: SCAS (service side):
------------------------------------------
Install the following RPMS from the Savannah patch:
https://savannah.cern.ch/patch/?1830
Leave out the LCAS configuration. This is not supported yet.

Install the saml2-xacml2-c-lib-0.0.14.2.rpm and scas-0.2.2-7.rpm (or newer).

Add a dedicated useraccount to the system. 
Example: call the user 'scas'. 
Make sure that the shell of this user is '/sbin/nologin'. On installation make
sure that the init.d script from the scas package contains the
correct choosen unprivileged account. Replace the 'scas' account with the one
you've choosen to be used as the unprivileged account for the SCAS daemon. 

Add the /usr/lib64 and /opt/globus/lib to the default path in
/etc/ld.so.conf{.d/} or make sure that the LD_LIBRARY_PATH is set to the
required paths.

Install the IGTF CAs. Make sure that the CRL files are up to date by installing
fetch-crl and running fetch-crl on a (more then) daily cron.

Install a host or service certificate (and key) for the SCAS service. Make these
files readable by the SCAS unprivileged account. Make sure that the hostkey.pem
file is not exposed for reading by other users then the choosen unprivileged
account (the example 'scas' account) and 'root'. If other services require
accessibility to the hostkey.pem, copy the file to a safe and private location
on the file system.

The scas daemon is by default installed at /usr/sbin/scas

Create a configuration file for the scas daemon in '/etc/scas.conf'
and make this file readable for the scas user only. Details about the scas.conf
file can be read in the man (5) scas.conf.

Example scas.conf file:
BOF ###############################################
scas_port = 8443
scas_capath = /etc/grid-security/certificates/
scas_hostcert = /etc/grid-security/hostcert.pem
scas_hostkey = /etc/grid-security/hostkey.pem
scas_log_file = /var/log/scas/scas.log
scas_debug_level = 3
lcas_db_file = /etc/lcas/lcas-scas.db
lcas_debug_level = 0
lcmaps_db_file = /etc/lcmaps/lcmaps-scas.db
lcmaps_debug_level = 3
EOF ###############################################

Create the /var/log/scas/scas.log and let this be writeable only to the
unprivileged 'scas' account. 

Make sure the directory for the /run/scas/scas.pid will be writeable only to the
unprivileged 'scas' account. 

For testing purposes its advised to set the scas_debug_level to 5. At this way
you can easily see all interactions with the service.

Create a directory at /etc/grid-security/gridmapdir/ of which this directory
must be owned by the 'scas' unprivileged user account and set to be readible,
writeable and accessible (0700).


Prepare the gridmapdir for LCMAPS, like on a CE. All the poolaccounts that are
required for the mapping on the client machines need to exist on the system. The
poolaccounts need to exist as empty files in this directory. If there isn't a
shared account setup present between the SCAS service and the other grid nodes,
it's recommended to set the shell for these accounts to /sbin/nologin. (note:
the shell value on the SCAS service machine is not transported and exposed to
the client nodes).

Create the following lcmaps-scas.db in the following location:
/etc/lcmaps/lcmaps-scas.db
Make sure that this file is readable to the unprivileged 'scas' useraccount.


Example lcmaps-scas.db file:
BOF ###############################################
# LCMAPS policy file/plugin definition
# Written by: Oscar Koeroo - okoeroo * at * nikhef * dot * nl
# The configuration file is specialized for non-root privileged processes/services, like:
### The WMProxy 
### SCAS service
### gLExec in logging only mode (when it supports multiple evaluation policies)


# default path for the modules
path = /usr/lib64/lcmaps 

# Plugin definitions:
good             = "lcmaps_dummy_good.mod"

localaccount     = "lcmaps_localaccount.mod"
                   "-gridmapfile /etc/grid-security/grid-mapfile"

poolaccount      = "lcmaps_poolaccount.mod"
                   " -override_inconsistency"
                   " -gridmapfile /etc/grid-security/grid-mapfile"
                   " -gridmapdir /etc/grid-security/gridmapdir"

vomslocalgroup   = "lcmaps_voms_localgroup.mod"
                   "-groupmapfile /etc/grid-security/groupmapfile"
                   "-mapmin 0"

vomspoolaccount  = "lcmaps_voms_poolaccount.mod"
                   "-gridmapfile /etc/grid-security/grid-mapfile"
                   "-gridmapdir /etc/grid-security/gridmapdir"
                   "-do_not_use_secondary_gids"

vomslocalaccount = "lcmaps_voms_localaccount.mod"
                   "-gridmapfile /etc/grid-security/grid-mapfile"
                   "-use_voms_gid"


# Policies:
# DN-local -> VO-static -> VO-pool -> DN-pool

static-account-mapping:
localaccount -> good

voms-mapping:
vomslocalgroup -> vomslocalaccount
vomslocalaccount -> good | vomspoolaccount

classic-poolaccount:
poolaccount -> good
EOF ###############################################


The grid-mapfile may contain both DNs and FQANs. They must match to either
localaccounts or poolaccounts (both VOMS and non-VOMS based).
"/dteam" .dteam
"/C=NL/CN=Oscar Koeroo" mylocalaccount

Note: These types of data may also be split into different files. Adjust the
plugin arguments accordingly.

The groupmapfile must have content only related to VOMS (FQAN) mappings, like:
"/dteam"    dteam


After this, you may start the service. Change to the unprivileged 'scas' user
and start the service with the following command:
/usr/sbin/scas -conf /etc/scas.conf

You may also use the init.d script that comes with the scas package. It must be
executed as root and will daemonize with the 'scas' unprivileged account by
default (can be altered in the script when required).

Tail the logfile /var/log/scas/scas.log
The LCMAPS mappings from within the SCAS service will be consolidated to the
scas.log. Initialize the LCMAPS specific log and debug levels to '5' in the
scas.conf file to enable more verbose logging to verify the installation.

Test the service by telneting to the machines on port 8443. You should see an
effect in the logfile when the scas_debug_log is set to a high enough level.
Also using: 
openssl s_client -CApath /etc/grid-security/certificates/ -cert <your personal cert or host cert> -key <your personal cert or host cert key file> -host <host name> -port 8443
should give some liveliness to the service. If that all works out you can hit
the next step, which is to install a SCAS client LCMAPS plugin. Mapping
interaction will only happen when you speak the SAML2-XACML2 protocol, so let's
continue with the setup of the SCAS client.



Install instructions: SCAS (client side):
------------------------------------------

Install glexec with or without (logging-only mode) the setuid execution bit on
root:glexec on a WN.

NOTE: For a CE, SE or other node type then a WN, please use a different
lcmaps*.db file then published here below.
The TLS/SSL handshake is done with the pilot job executors credentials from the
$X509_USER_PROXY variable. The real user jobs credentials are transported
through glexec and the LCMAPS framework. This is common to the WN. For a CE, SE
or other node type other then a WN, there are no two proxies to be evaluated in
one go. The host credentials of the node must be used for this interaction and
must be explicitly set in the lcmaps.db.


Install the following lcmaps.db at the location setup in the glexec.conf
(usually /etc/lcmaps/lcmaps-glexec.db)
1. In the scenario where glexec is installed *with* setuid bit enabled, let the
   lcmaps.db file be owned by root.root and the file permissions should be 0644
   or 0640.
2. In the scenario where glexec is installed *without* setuid bit enabled (= a
   regular executable), let the lcmaps.db file be owned by root.root and the
   file permissions should be 0644.



1. Scenario Use the following example file in the with setuid mode of glexec on
   the WN:
BOF ###############################################
# LCMAPS policy file/plugin definition
# Written by: Oscar Koeroo - okoeroo * at * nikhef * dot * nl
### Glexec with SCAS on the WN

# default path for the modules
path = /usr/lib64/lcmaps

# Plugin definitions:
good             = "lcmaps_dummy_good.mod"

posix_enf        = "lcmaps_posix_enf.mod"
                   " -maxuid 1"
                   " -maxpgid 1"
                   " -maxsgid 32"

scasclient = "lcmaps_scas_client.mod"
             " -capath /etc/grid-security/certificates"
             " -endpoint https://eir.nikhef.nl:8443"
             " -resourcetype wn"
             " -actiontype execute-now"

verifyproxy = "lcmaps_verify_proxy.mod"
              " -capath /etc/grid-security/certificates"
              " --allow-limited-proxies"

# Policies:
# SCAS-client

glexec_get_account:
verifyproxy -> scasclient
scasclient -> posix_enf
EOF ###############################################


2. Please use the following file in the with logging only mode of glexec on the WN:
BOF ###############################################
# LCMAPS policy file/plugin definition
# Written by: Oscar Koeroo - okoeroo * at * nikhef * dot * nl
# The configuration file is specialized for non-root privileged processes/services, like:
### gLExec in logging only mode (when it supports multiple evaluation policies)


# default path for the modules
path = /usr/lib64/lcmaps

# Plugin definitions:
good             = "lcmaps_dummy_good.mod"

scasclient = "lcmaps_scas_client.mod"
             " -capath /etc/grid-security/certificates"
             " -endpoint https://eir.nikhef.nl:8443"
             " -resourcetype wn"
             " -actiontype execute-now"

verifyproxy = "lcmaps_verify_proxy.mod"
              " -capath /etc/grid-security/certificates"
              " --allow-limited-proxies"

# Policies:
# SCAS-client

glexec_get_account:
verifyproxy -> scasclient
EOF ###############################################



3. Scenario Use the following example file in the with setuid mode of glexec on
   the CE (which can be set to SE or RB):
BOF ###############################################
# LCMAPS policy file/plugin definition
# Written by: Oscar Koeroo - okoeroo * at * nikhef * dot * nl
### Glexec with SCAS on the WN

# default path for the modules
path = /usr/lib64/lcmaps

# Plugin definitions:
good             = "lcmaps_dummy_good.mod"

posix_enf        = "lcmaps_posix_enf.mod"
                   " -maxuid 1"
                   " -maxpgid 1"
                   " -maxsgid 32"

scasclient = "lcmaps_scas_client.mod"
             " -capath /etc/grid-security/certificates"
             " -cert /home/scas/.globus/hostcert.pem"
             " -key  /home/scas/.globus/hostkey.pem"
             " -endpoint https://eir.nikhef.nl:8443"
             " -resourcetype ce"
             " -actiontype queue"

verifyproxy = "lcmaps_verify_proxy.mod"
              " -capath /etc/grid-security/certificates"
              " --allow-limited-proxies"

# Policies:
# SCAS-client

glexec_get_account:
verifyproxy -> scasclient
scasclient -> posix_enf
EOF ###############################################


4. Please use the following file in the with logging only mode of glexec on the
   CE (which can be set to SE or RB):
BOF ###############################################
# LCMAPS policy file/plugin definition
# Written by: Oscar Koeroo - okoeroo * at * nikhef * dot * nl
# The configuration file is specialized for non-root privileged processes/services, like:
### gLExec in logging only mode (when it supports multiple evaluation policies)


# default path for the modules
path = /usr/lib64/lcmaps

# Plugin definitions:
good             = "lcmaps_dummy_good.mod"

scasclient = "lcmaps_scas_client.mod"
             " -capath /etc/grid-security/certificates"
             " -cert /home/scas/.globus/hostcert.pem"
             " -key  /home/scas/.globus/hostkey.pem"
             " -endpoint https://eir.nikhef.nl:8443"
             " -resourcetype ce"
             " -actiontype queue"

verifyproxy = "lcmaps_verify_proxy.mod"
              " -capath /etc/grid-security/certificates"
              " --allow-limited-proxies"

# Policies:
# SCAS-client

glexec_get_account:
verifyproxy -> scasclient
EOF ###############################################


Adjust the -endpoint to the host and port number of your previously installed
SCAS service or use these default for testing purposes.

Install the following lcas.db at the location setup in the glexec.conf (usually
/etc/lcas/lcas-glexec.db)
In the scenario where glexec is installed *with* setuid bit enabled, let the
lcas.db file be owned by root.root and the file permissions should be 0644 or
0640.
In the scenario where glexec is installed *without* setuid bit enabled (= a
regular executable), let the lcas.db file be owned by root.root and the file
permissions should be 0644.

BOF ###############################################
# LCAS policy file/plugin definition
# Written by: Oscar Koeroo - okoeroo * at * nikhef * dot * nl
pluginname=lcas_userban.mod,pluginargs=ban_users.db
EOF ###############################################

Create and empty file at /etc/lcas/ban_users.db


Install the VOMS host and/or certificate certificates or .lst files (when your
VOMS-api version is greater then 1.7.0) /etc/grid-security/vomsdir/
Without the VOMS certificates, the VOMS credentials can't be used.



Test:
-----

Try running glexec with the following settings for a WN scenario test:

# for pilot job executor
export X509_USER_PROXY=/tmp/x509up_u`id -u`

# identity for pilot job (real user job) credential
export GLEXEC_CLIENT_CERT=/tmp/x509up_u`id -u`

# optional: proxy for the real user job to be set in the real user environment (more details in the glexec install notes) 
export GLEXEC_SOURCE_PROXY=/tmp/x509up_u`id -u`

# run it
/usr/sbin/glexec /usr/bin/id -a


