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

The Delegation Server configuration file can be found under /var/www/server/conf/cfg.xml. The configuration file is XML formatted and follows the structure give by the OA4MP Server. For more information about the standard OA4MP Server configuration, consult this page. Here we will follow with describing additional configuration options that were made available in the Delegation Server implementation only. These do not belong to the standard OA4MP configurations.

Trace Logging

For traceability reasons outlined in the RCAuth.eu policy document, special log entries had to be introduced in order to keep record of mappings between SAML user attributes and their generated certificate. In order no to pollute the already existing server log file, we decided to add a separate logging capability, trace logging, which would log to a separate file. You can configure the trace logging capabilities by adding the following section to the server configuration file:

      <traceLogging  logFileName="/var/www/server/log/trace.log"
                logName="trace"
                logSize="1000000"
                logFileCount="10"
                debug="true"
      />

The traceLogging tag supports the same configuration options as the OA4MP server's logging tag.

Claim Mapping

The OA4MP implementation has a scopes configuration element by which it offers support for additional scopes (other than its predefined set in OA2Scopes.basicScopes). The Delegation Server implementation extends this configuration element, allowing the definition of claim mapping for a within a specific scope:

      <scopes handler="org.delegserver.oauth2.DSDynamicScopeHandler">

          <scope name="edu.uiuc.ncsa.myproxy.getcert">
               <claim name="cert_subject_dn">X509_CERT_SUBJECT</claim>
          </scope>

          <scope name="email">
               <claim name="email">mail</claim>
          </scope>

          <scope name="openid">
          </scope>

          <scope name="profile">
               <claim name="given_name">givenName</claim>
               <claim name="family_name">sn</claim>
          </scope>

          <scope name="org.cilogon.userinfo">
               <claim name="idp">Shib-Authenticating-Authority</claim>
               <claim name="idp_display_name">o</claim>
               <claim name="eduPersonTargetedID">eptid</claim>
               <claim name="eduPersonPrincipalName">eppn</claim>
               <claim name="oidc">oidc</claim>
               <claim name="affiliation">affiliation</claim>
               <claim name="ou">ou</claim>
               <claim name="name">displayName</claim>
          </scope>

      </scopes>

The handler attribute of the outer scopes element defines which handler implementation to use. More on custom scope handlers here.

Every inner scope definition adds support for a scope. Within each scope definition, multiple claim definition can appear. This means that for a specific scope requested, the Delegation Server will return a set of defined claims. A scope definition without any claims is also valid. The names of the scopes and claims defined in the Delegation Server are set according to the OIDC Scopes and Claims.

A claim element is defined by its name attribute, and its inner value defines the source of that claim. Claim are built from user attributes (usually released by the users' home IdP). You will see the correlation between claims defined here and the Mapped Name (id) column of the shibboleth attributes table. Note that the X509_CERT_SUBJECT is not defined in the shibboleth attribute mapping, since it's not a user attribute released by the IdP, rather a new attribute defined by the Delegation Server. See the DN Generator section for more details on this attribute.

DN Generator

+ attribute filter

Extras

• crl publish script