Delegation Server Administrator Guide

Introduction

The Delegation Server is a key component in the AARC Piloting work. The Delegation Server issues certificates for authenticated users based on their released attributes. Our current Delegation Server implementation is called RCAuth.eu. This page is dedicated for Delegation Server operators and administrators who wish to fine tune their server.

In case you want to deploy the Delegation Server, make sure to check out our guide on using Ansible deployment scripts. Most of the presented configuration from below are set by the Ansible scripts.

Delegation Server Configuration

The Delegation Server is a web application packaged in a .war file, based on the OA4MP Server. In order to deploy it you will need a web container. The setup used for this includes Tomcat as the web container (following the suggestions given by the OA4MP Server), with an Apache httpd server running in front of the web container, acting as a reverse https proxy, and authenticating users through mod_shib. Details on the reverse proxy setup can be found here and here.

Apache

The Apache server holds configurations relating to the SSL setup of the Delegation Server and to the proxy setup talking to Tomcat. In case you want to tweak either of these options, you should look into /etc/httpd/conf.d/ssl.conf. Make sure to configure the mod_proxy setting to allow the Delegation Server to pass through. Your configuration should contain something like the following:

ProxyPass /oauth2/authorized !
ProxyPass /oauth2 ajp://127.0.0.1:8009/oauth2

Note! Take special care to disallow the /authorized endpoint to be forwarded, since it's a private endpoint meant only to be called from within the server. Make sure to define proxy rules in order of precedence from most restrictive to least restrictive!

Inside the apache configuration /etc/httpd/conf.d/shib.conf you should make sure to protect the authorization endpoint of the Delegation Server to be only reachable to authenticated users. It is also a good idea to protect the /register (client self-registration) endpoint, in order to avoid the Delegation Server getting flooded with self-registration requests.

<Location /oauth2/authorize>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  ShibRequestSetting exportAssertion true
  ShibUseHeaders On
  Require valid-user
</Location>

<Location /oauth2/register>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  ShibUseHeaders On
  Require valid-user
</Location>

Take a look at the mod_shib documentation to see what the above options all mean.

Note! Beware of the spoofing voulnerability which occurs when using ShibUseHeaders as a means of releasing attributes to the web application. Currently OA4MP Server expects attributes through the use of headers, but as soon as it moves away from it, ShibUseHeaders should be exchanged it's alternative: ShibUseEnvironment.

Tomcat

In the Tomcat server.xml configuration make sure to have the AJP connector opened on port 8009. There are a couple of restrictions you should enable on this connector:

• Setting address="127.0.0.1" will enforce local access only on the container. Without this a user could bypass the Apache server (and authentication) by directly accessing port 8009 from the browser. This should not be possible due to firewall restrictions in the first place, but even if the firewall fails, this configuration will still keep out any access not coming from localhost.
• Setting tomcatAuthentication="false" will tell Tomcat to trust the external authenticator (Apache).

<Connector port="8009" address="127.0.0.1" tomcatAuthentication="false" protocol="AJP/1.3"/>

The Delegation Server is communicating with the Online CA through a dedicated private channel, using a private ssl setup (with a private trust root). The communication is initiated from the Delegation Server web application, but using the SSL context setting of its Tomcat web container. In order to initiate the ssl connection, Tomcat has to trust the private trust root created for the communication. For this you will have to set the X509_CERT_DIR environmental variable in the tomcat.conf configuration file to the location of the private trust anchor.

X509_CERT_DIR="/var/www/server/certificates"

Shibboleth

You will need to install and configure Shibboleth as a Service Provider which will take care of redirecting unauthenticated users to the right authentication endpoint. In case of the RCAuth.eu scenario the Shibboleth SP will have to redirect users to the WAYF. Some general information on how to configure Shibboleth SP can be found here. After successful authentication, the Shibboleth SP is expected to map and release a set of user attributes received from the IdP to the Delegation Server web application. The list of attributes expected by the Delegation Server (also outlined in the RCAuth.eu policy) is:

Name	Friendly Name	Mapped Name (id)
urn:oid:1.3.6.1.4.1.5923.1.1.1.6	eduPersonPrincipalName	eppn
urn:oid:1.3.6.1.4.1.5923.1.1.1.13	eduPersonUniqueId	epuid
urn:oid:1.3.6.1.4.1.5923.1.1.1.10	eduPersonTargetedID	eptid
urn:oid:2.16.840.1.113730.3.1.241	displayName	displayName
urn:oid:2.5.4.42	givenName	givenName
urn:oid:2.5.4.4	sn	sn
urn:oid:2.5.4.3	cn	cn
urn:oid:2.5.4.10	o	o
urn:oid:0.9.2342.19200300.100.1.3	mail	mail
urn:oid:1.3.6.1.4.1.25178.1.2.9	schacHomeOrganization	schacHomeOrganization

Next to the attributes mapped above, there is an additional attribute called Shib-Authenticating-Authority. Since the Shibboleth SP is always talking to the same WAYF, the entity ID of the IdP that the Delegation Server is talking to is always going to be the WAYF, and not the users' real authenticating IdP. There is, however, the Authenticating Authority attribute which can also be mapped from the incoming SAML response. To do so, you will have to configure an attribute extractor in the shibboleth2.xml:

<AttributeExtractor type="Chaining">
      ...
      <AttributeExtractor type="Assertion" AuthenticatingAuthority="Shib-Authenticating-Authority"/>
</AttributeExtractor>

Delegation Server

The Delegation Server is the web application called oauth2.war living in the web container. Next to the web application there are a set of resources used by the server under /var/www/server structured in the following way:

• /var/www/server/conf holds server configuration files
• /var/www/server/log holds the server logs produced by the web application
• /var/www/server/storage is only used if using file system for storage backend; when using a database this directory is unused
• /var/www/server/tools holds external tools, such as client approval cli.
• /var/www/server/certificates is an alternative to /etc/grid-security/certificates holding only the private trust root used for connecting to the Online CA. See Tomcat configuration.

Configuration

• trace log conf
• claim mapping
• dnGenerator + attribute filter

Extras

• crl publish script