Configuring XRootD Authorization¶

XRootD offers several authentication options using security plugins to validate incoming credentials, such as bearer tokens, X.509 proxies, and VOMS proxies.

In the case of X.509 and VOMS proxies, after the incoming credential has been mapped to a username or groupname, the authorization database is used to provide fine-grained file access.

Note

On data nodes, files will be owned by Unix user xrootd (or other daemon user), not as the user authenticated to, under most circumstances. XRootD will verify the permissions and authorization based on the user that the security plugin authenticates you to, but, internally, the data node files will be owned by the xrootd user. If this behaviour is not desired, enable XRootD multi-user support.

Authorizing Bearer Tokens¶

XRootD supports authorization of bearer tokens such as macaroons, SciTokens, or WLCG tokens. Encoded in the bearer tokens themselves are information about the files that they should have read/write access to and in the case of SciTokens and WLCG tokens, you may configure XRootD to further restrict access.

Configuring SciTokens/WLCG Tokens¶

SciTokens and WLCG Tokens are asymmetrically signed bearer tokens: they are signed by a token issuer (e.g., CILogon, IAM) and can be verified with the token issuer's public key. To configure XRootD to accept tokens from a given token issuer use the following instructions:

Add a section for each token issuer to /etc/xrootd/scitokens.conf:
```
[Issuer <NAME>]
issuer = <URL>
base_path = <RELATIVE PATH>
```
Replacing <NAME> with a descriptive name, <URL> with the token issuer URL, and base_path to a path relative to rootdir that the client should be restricted to accessing.
(Optional) if you want to map the incoming token for a given issuer to a Unix username:
1. Install xrootd-multiuser
2. Add the following to the relevant issuer section in /etc/xrootd/scitokens.conf:
```
map_subject = True
```
(Optional) if you want to only accept tokens with the appropriate aud field, add the following to /etc/xrootd/scitokens.conf:
```
[Global]
audience = <COMMMA SEPARATED LIST OF AUDIENCES>
```

An example configuration that supports tokens issued by the OSG Connect and CMS:

[Global]
audience = https://testserver.example.com/, MySite

[Issuer OSG-Connect]

issuer = https://scitokens.org/osg-connect
base_path = /stash
map_subject = True

[Issuer CMS]

issuer = https://scitokens.org/cms
base_path = /user/cms

Configuring macaroons¶

Macaroons are symetrically signed bearer tokens so your XRootD host must have access to the same secret key that is used to sign incoming macaroons. When used in an XRootD cluster, all data nodes and the redirector need access to the same secret. To enable macaroon support:

Place the shared secret in /etc/xrootd/macaroon-secret

Ensure that it has the appropriate file ownership and permissions:

root@host # chown xrootd:xrootd /etc/xrootd/macaroon-secret
root@host # chmod 0600 /etc/xrootd/macaroon-secret

Authorizing X.509 proxies¶

Authenticating proxies¶

Authorizations for proxy-based security are declared in an XRootD authorization database file. XRootD authentication plugins are used to provide the mappings that are used in the database.

Starting with OSG 3.6, DN mappings are performed with XRootD's built-in GSI support, and FQAN mappings are with the XRootD-VOMS (XrdVoms) plugin.

To enable proxy authentication, edit /etc/xrootd/config.d/10-osg-xrdvoms.cfg and add or uncomment the line

set EnableVoms = 1

Note

Proxy authentication is already enabled in XRootD Standalone, so this step is not necessary there.

Requirements for XRootD-Multiuser with VOMS FQANs

Using XRootD-Multiuser with a VOMS FQAN requires XRootD 5.5.0 or newer.

Key length requirements

Servers on EL 8 or newer will reject proxies that are not at least 2048 bits long. Ensure your clients' proxies have at least 2048 bits long with voms-proxy-info; if necessary, have them add the argument -bits 2048 to their voms-proxy-init calls.

Mapping subject DNs¶

DN mappings take precedence over VOMS attributes

If you have mapped the subject Distinguished Name (DN) of an incoming proxy with VOMS attributes, XRootD will map it to a username.

X.509 proxies are mapped using the built-in XRootD GSI plug-in. To map an incoming proxy's subject DN to an XRootD username, add lines of the following format to /etc/grid-security/grid-mapfile:

"<SUBJECT DN>" <AUTHDB USERNAME>

Replacing <SUBJECT DN> with the X.509 proxy's DN to map and <AUTHDB USERNAME> with the username to reference in the authorization database. For example, the following mapping:

"/DC=org/DC=cilogon/C=US/O=University of Wisconsin-Madison/CN=Brian Lin A2266246" blin

Will result in the username blin, i.e. authorize access to clients presenting the above proxy with u blin ... in the authorization database.

Mapping VOMS attributes¶

Requirements for XRootD-Multiuser with VOMS FQANs

Using XRootD-Multiuser with a VOMS FQAN requires XRootD 5.5.0 or newer.

If the XRootD-VOMS plugin is enabled, an incoming VOMS proxy will authenticate the first VOMS FQAN and map it to an organization name (o), groupname (g), and role name (r) in the authorization database. For example, a proxy from the OSPool whose first VOMS FQAN is /osg/Role=NULL/Capability=NULL will be authenticated to the /osg groupname; note that the / is included in the groupname.

Instead of only using the first VOMS FQAN, you can configure XRootD to consider all VOMS FQANs in the proxy for authentication by setting the following in /etc/xrootd/config.d/10-osg-xrdvoms.cfg:

set vomsfqans = useall

Mapping VOMS attributes to users¶

In order for the XRootD-Multiuser plugin to work, a proxy must be mapped to a user (u) that is a valid Unix user.

Use a VOMS Mapfile, conventionally in /etc/grid-security/voms-mapfile that contains lines in the following form:

"<FQAN PATTERN>" <USERNAME>

replacing <FQAN PATTERN> with a glob matching FQANs, and <USERNAME> with the user that you want to map matching FQANs to.

For example,

"/osg/*" osg01

will map FQANs starting with /osg/ to the user osg01.

To enable using VOMS mapfiles in the first place, add the following line to your XRootD configuration:

voms.mapfile /etc/grid-security/voms-mapfile

replacing /etc/grid-security/voms-mapfile with the actual location of your mapfile, if it is different.

Note

A VOMS Mapfile only affects mapping the user (u) attribute understood in the authorization-database. The FQAN will always be used for the groupname (g), organization name (o), and role name (r), even if the mapfile is missing or does not contain a matching mapping.

See the VOMS Mapping documentation for details. VOMS Mapfiles previously used with LCMAPS should continue to work unmodified, but the plugin can only look at a single mapfile, so if you are using the mappings provided in /usr/share/osg/voms-mapfile-default (by the vo-client-lcmaps-voms package), you will have to copy them to /etc/grid-security/voms-mapfile.

Authorization database¶

XRootD allows configuring fine-grained file access permissions based on authenticated identities and paths. This is configured in the authorization file /etc/xrootd/Authfile, which should be writable only by the xrootd user, optionally readable by others.

Here is an example /etc/xrootd/Authfile :

# This means that all the users have read access to the datasets, _except_ under /private
u * <STORAGE PATH>/private -rl <STORAGE PATH> rl

# Or the following, without a restricted /private dir
# u * <STORAGE PATH> rl

# This means that all the users have full access to their private home dirs
u = <STORAGE PATH>/home/@=/ a

# This means that the privileged 'xrootd' user can do everything
# There must be at least one such user in order to create the
# private dirs for users willing to store their data in the facility
u xrootd <STORAGE PATH> a

# This means that OSPool clients presenting a VOMS proxy can do anything under the 'osg' directory
g /osg <STORAGE PATH>/osg a

Replacing <STORAGE PATH> with the path to the directory that will contain data served by XRootD, e.g. /data/xrootdfs. This path is relative to the rootdir.

Configure most to least specific paths

Specific paths need to be specified before generic paths. For example, this line will allow all users to read the contents /data/xrootdfs/private:

    u * /data/xrootdfs rl /data/xrootdfs/private -rl

Instead, specify the following to ensure that a given user will not be able to read the contents of /data/xrootdfs/private unless specified with another authorization rule:

    u * /data/xrootdfs/private -rl /data/xrootdfs rl

Formatting¶

More generally, each authorization rule of the authorization database has the following form:

idtype id path privs

Field	Description
idtype	Type of id. Use `u` for username, `g` for groupname, `o` for organization name, `r` for role name, etc.
id	ID name, e.g. username or groupname. Use `*` for all users or `=` for user-specific capabilities, like home directories
path	The path prefix to be used for matching purposes. `@=` expands to the current user name before a path prefix match is attempted
privs	Letter list of privileges: `a` - all ; `l` - lookup ; `d` - delete ; `n` - rename ; `i` - insert ; `r` - read ; `k` - lock (not used) ; `w` - write ; `-` - prefix to remove specified privileges

For more details or examples on how to use templated user options, see XRootD authorization database.

Verifying file ownership and permissions¶

Ensure the authorization datbase file is owned by xrootd (if you have created file as root), and that it is not writable by others.

root@host # chown xrootd:xrootd /etc/xrootd/Authfile
root@host # chmod 0640 /etc/xrootd/Authfile  # or 0644

Multiuser and the authorization database¶

The XRootD-Multiuser plugin can be used to perform file system operations as a different user than the XRootD daemon (whose user is xrootd). If it is enabled, then after authorization is done using the authorization database, XRootD will take the user (u) attribute of the incoming request, and perform file operations as the Unix user with the same name as that attribute.

Note

If there is no Unix user with a matching name, you will see an error like XRootD mapped request to username that does not exist: <username>; the operation will then fail with "EACCES" (access denied).

Applying Authorization Changes¶

After making changes to your authorization database, you must restart the relevant services.

Verifying XRootD Authorization¶

Bearer tokens¶

To test read access using macaroon, SciTokens, and WLCG token authorization, run the following command:

user@host $ curl -v \
                 -H 'Authorization: Bearer <TOKEN>' \
                 https://host.example.com//path/to/directory/hello_world

Replacing <TOKEN> with the contents of your encoded token, host.example.com with the target XRootD host, and /path/to/directory/hello_world with the path of the file to read.

To test write access, using macaroon, SciTokens, and WLCG token authorization, run the following command:

user@host $ curl -v \
                 -X PUT \
                 --upload-file <FILE TO UPLOAD> \
                 -H 'Authorization: Bearer <TOKEN>' \
                 https://host.example.com//path/to/directory/hello_world

Replacing <TOKEN> with the contents of your encoded token, <FILE TO UPLOAD> with the file to write to the XRootD host, host.example.com with the target XRootD host, and /path/to/directory/hello_world with the path of the file to write.

X.509 and VOMS proxies¶

To verify X.509 and VOMS proxy authorization, run the following commands from a machine with your user certificate/key pair, xrootd-client, and voms-clients-cpp installed:

Destroy any pre-existing proxies and attempt a copy to a directory (which we will refer to as <DESTINATION PATH>) on the <XROOTD HOST> to verify failure:

user@client $ voms-proxy-destroy
user@client $ xrdcp /bin/bash root://<XROOTD HOST>/<DESTINATION PATH>
180213 13:56:49 396570 cryptossl_X509CreateProxy: EEC certificate has expired
[0B/0B][100%][==================================================][0B/s]
Run: [FATAL] Auth failed

On the XRootD host, add your DN to /etc/grid-security/grid-mapfile
Add a line to the authorization database to ensure the mapped user can write to <DESTINATION PATH>
Restart the relevant XRootD services. See this section for details

Generate your proxy and verify that you can successfully transfer files:

user@client $ voms-proxy-init
user@client $ xrdcp  /bin/sh root://<XROOTD HOST>/<DESTINATION PATH>
[938.1kB/938.1kB][100%][==================================================][938.1kB/s]

If your transfer does not succeed, re-run xrdcp with --debug 2 for more information.

Updating to OSG 23¶

There are no manual steps necessary for authentication to work when upgrading from OSG 3.6 to OSG 23. If you are upgrading from an earlier release series, see the updating to OSG 3.6 section below.

Updating to OSG 3.6¶

There are some manual steps that need to be taken for authentication to work in OSG 3.6.

Ensure OSG XRootD packages are fully up-to-date¶

Some authentication configuration is provided by OSG packaging. Old versions of the packages may result in broken configuration. It is best if your packages match the versions in the appropriate release subdirectories of https://repo.opensciencegrid.org/osg/3.6/, but at the very least these should be true:

xrootd >= 5.4
xrootd-multiuser >= 2 (if using multiuser)
xrootd-scitokens >= 5.4 (if using SciTokens/WLCG Tokens)
xrootd-voms >= 5.4.2-1.1 (if using VOMS auth)
osg-xrootd >= 3.6
osg-xrootd-standalone >= 3.6 (if installed)
xcache >= 3 (if using xcache-derived software such as stash-cache, stash-origin, atlas-xcache, or cms-xcache)

SciToken auth¶

Updating from XRootD 4 (OSG 3.5 without 3.5-upcoming)¶

The config syntax for adding auth plugins has changed between XRootD 4 and XRootD 5. Replace

ofs.authlib libXrdAccSciTokens.so ...

with

ofs.authlib ++ libXrdAccSciTokens.so ...

Updating from XRootD 5 (OSG 3.5 with 3.5-upcoming)¶

No config changes are necessary.

Proxy auth: transitioning from XrdLcmaps to XrdVoms¶

In OSG 3.5 and previous, proxy authentication was handled by the XrdLcmaps plugin, provided in the xrootd-lcmaps RPM. This is no longer the case in OSG 3.6; instead it is handled by the XrdVoms plugin, provided in the xrootd-voms RPM.

To continue using proxy authentication, update your configuration and your authorization database (Authfile) as described below.

Updating XRootD configuration¶

Remove any old config in /etc/xrootd and /etc/xrootd/config.d that mentions LCMAPS or libXrdLcmaps.so, otherwise XRootD may fail to start.
If you do not have both an unauthenticated stash-cache and an authenticated stash-cache on the same server, uncomment set EnableVoms = 1 in /etc/xrootd/config.d/10-osg-xrdvoms.cfg.
If you have both an an authenticated stash-cache and an unauthenticated stash-cache on the same server, add the following block to /etc/xrootd/config.d/10-osg-xrdvoms.cfg:
```
if named stash-cache-auth
    set EnableVoms = 1
fi
```
If you are using XRootD Multiuser, create a VOMS Mapfile at /etc/grid-security/voms-mapfile, with the syntax described above, then add voms.mapfile /etc/grid-security/voms-mapfile to your XRootD config if it's not already present.

Note

In order to make yum update easier, xrootd-lcmaps has been replaced with an empty package, which can be removed after upgrading.

Updating your authorization database¶

Unlike the XrdLcmaps plugin, which mapped VOMS FQANs to users u, the XrdVoms plugin maps FQANs to groups g, roles r, and organizations o, as described in the mapping VOMS attributes section. You can still use a VOMS mapfile but if you want to use the mappings provided at /usr/share/osg/voms-mapfile-default by the vo-client-lcmaps-voms package, you must copy them to /etc/grid-security/voms-mapfile.

Replace mappings based on users with mappings based on the other attributes. For example, instead of

u uscmslocal /uscms rl

use

g /cms/uscms /uscms rl

If you need to make a mapping based on group and role, create and use a "compound ID" as described in the XRootD security documentation.

# create the ID named "cmsprod"
= cmsprod g /cms r Production

# use it
x cmsprod /cmsprod rl