Delegation Server Administrator Guide

Introduction

The Delegation Server forms the basis for the RCauth.eu online CA. The Delegation Server issues certificates for authenticated users based on their released attributes. This page is intended 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. This page highlights the important parts of the configuration.

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 http(s) proxy, and authenticating users through mod_shib. Details on the reverse proxy setup can be found here and here.

Apache

The Apache server has configuration relating to the SSL setup of the Delegation Server and to the (reverse) proxy setup for Tomcat. Both are configured in /etc/httpd/conf.d/ssl.conf. Make sure mod_proxy is configure to allow all the relevant Delegation Server endpoints to pass through. Although it is better to explicitly proxy all the required endpoints, as a bare minimum, you can use something like the following:

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

Note! In particular the /authorized endpoint should NOT be forwarded: it is a private endpoint meant only to be called from within the server.

Also make sure to define proxy rules in order of decreasing restrictiveness, i.e. with the most restrictive rule first.

In mod_shib's configuration for Apache /etc/httpd/conf.d/shib.conf, you should make sure to protect at least the authorization endpoint of the Delegation Server to be only reachable to authenticated users. Additionally it is a good idea to protect also the /register (client self-registration) as well as the /admin-register (administrative client self-registration) endpoints, 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
  <RequireAll>
#    Require not user jdoe@example.org
    Require valid-user
  </RequireAll>
</Location>

<Location /oauth2/register>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  ShibUseHeaders On
  <RequireAll>
#    Require not user jdoe@example.org
    Require valid-user
  </RequireAll>
</Location>

<Location /oauth2/admin-register>
 AuthType shibboleth
 ShibRequestSetting requireSession 1
 ShibUseHeaders On
 <RequireAll>
#    Require not user jdoe@example.org
    Require valid-user
  </RequireAll>
</Location>

See the mod_shib documentation for details on the above options.

Note! Beware of the spoofing vulnerability 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 into its 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).
• Setting URIEncoding="UTF-8" ensures incoming GET requests will be processed as UTF-8, instead of ISO-8859-1.

<Connector port="8009" URIEncoding="UTF-8" address="127.0.0.1" tomcatAuthentication="false" protocol="AJP/1.3" redirectPort="8443"/>

The Delegation Server is communicating with the Online CA through a dedicated private channel, using a private TLS 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 TLS 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 /etc/tomcat/tomcat.conf configuration file to the location of the private trust anchor.

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

In order to allow the Delegation Server to send notifications upon new client registration requests, you have to add the following resource to the context.xml file:

<Resource name="mail/Session" type="javax.mail.Session" auth="Container"></Resource>

this requires additional configuration in the config file, see email notifications for details.

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 RCauth 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 CP/CPS) 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 user's real authenticating IdP. There is however an additional attribute, the Authenticating Authority, 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 Config

The Delegation Server is a web application called oauth2.war living in the web container. It uses a set of files 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 the client approval cli.
• /var/www/server/certificates like /etc/grid-security/certificates but instead 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 at /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 describe the additional configuration options that are specific to the Delegation Server implementation.

Trace Logging

For traceability reasons outlined in the RCAuth.eu CP/CPS document, special log entries are necessary in order to keep record of mappings between the user's SAML attributes and the generated certificate DN. In order not to pollute the already existing server log file, a separate logging capability has been added, trace logging, which logs to a separate file. The trace logging capabilities can be configured by adding the following section to the server configuration file:

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

The traceLogging tag supports the same configuration options as the OA4MP server's logging tag. When setting the debug flag to false a limited trace is logged after a user's visit, including the following information:

• the transaction (authorization grant)
• the subject RDN components and the SAML attributes they where created from (see DN Generator)
• the MyProxy username, i.e. the user- and IdP-dependent part of the full DN.

When setting the debug flag to true, also the raw SAML response - including user attributes - and a detailed trace of how attributes were used and transformed, are being logged.

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="eu.rcauth.delegserver.oauth2.DSDynamicClaimsSourceImpl">

          <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="name">displayName</claim>
               <claim name="family_name">sn</claim>
               <claim name="given_name">givenName</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="eduPersonUniqueId">euid</claim>
               <claim name="eduperson_assurance">assurance</claim>
               <claim name="eduperson_scoped_affiliation">affiliation</claim>
          </scope>

      </scopes>

The handler attribute of the scopes element defines which handler implementation to use. The DSDynamicClaimsSourceImpl is an extension of the BasicClaimsSourceImpl (Note: before the 4.0 release of OA4MP, the BasicClaimsSourceImpl was called the BasicScopeHandler, see here for corresponding documentation).

Every scope definition adds support for a particular scope. Within each scope definition, multiple claim definitions can appear. For a specific scope requested, the Delegation Server will return the set of defined claims (when available). A scope definition without any claims is also valid.

The names of the scopes and claims listed above reflects the current configuration of the RCauth Delegation Server. It partially follows OIDC/OA4MP Scopes and Claims. It is foreseen we will move to the REFEDS whitepaper naming for also for the other eduperson claims in the near future.
Note that the o SAML attribute is produced by the RCauth WAYF from the organisationDisplayName in the metadata.

A claim element is defined by its name attribute, and its inner value defines the source of that claim. Claims are built from user attributes (usually released by the user's 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

The Delegation Server creates user certificate for authenticated users. In order to provide a unique certificate for every authenticated user, the certificate subject DN is generated from a set of user attributes in a way that ensures uniqueness. See the RCAuth.eu CP/CPS document on details about how DNs are generated. In order to make DN generation configurable and flexible the Delegation Server offers a configuration block that can be used for this:

      <dnGenerator attributeName="X509_CERT_SUBJECT" type="rfc2253" baseDN="DC=rcauth-clients,DC=rcauth,DC=eu">

          <cnName>
               <source>displayName</source>
               <source>givenName+sn</source>
               <source>cn</source>
          </cnName>

          <cnUniqueId>
               <source>epuid</source>
               <source>eppn</source>
               <source>eptid</source>
          </cnUniqueId>

          <organisation>
               <source>schacHomeOrganization</source>
               <source filter="url">o</source>
          </organisation>

          <extensions>
               <source name="email">mail</source>
          </extensions>

      </dnGenerator>

The dnGenerator element defines sets of source attributes used as input for creating various DN components. The source attributes, just like for the Claim Mapping, are the user attributes released by the user's IdP (shibboleth attributes). The dnGenerator element contains three attributes, all referring to the new DN attribute being created:

• attributeName : The name of the DN attribute created by this generator. This is an internal attribute name which can be used to reference the generated DN within the Delegation Server. This attribute can be used internally as source attribute for claim mappings.
• type : Defines the formatting of the generated DN. Accepted values are rfc2253 and openssl. If the attribute is missing, the generated type defaults to rfc2253. Note that the type of the subsequent baseDN attribute has to match the type specified here.
• baseDN : The base DN to which the generated DN gets appended (or prepended for rfc2253 format). This is a static part of the DN that every certificate generated by this Delegation Server will have. Note that the format type of the baseDN should match the type attribute. In case of missing type attribute the baseDN should be provided in rfc2253 format.

The different source elements are defining which attributes should be used for generating the different parts of the DN:

• organisation : Contains an ordered list of source attributes for generating the 'O' RDN.
• cnName : Contains an ordered list of source attributes for generating the display name part of the 'CN' RDN.
• cnUniqueId : Contains an ordered list of source attributes for generating the unique identifier part of the 'CN' RDN.

Each of these lists of source attributes (organisation, cnName and cnUniqueId) has to be ordered from the MOST preferred attribute to the LEAST preferred attribute. The first source attribute from a list that will have a non-empty user attribute present (from the shibboleth attribute set) will be taken as the source value for that particular DN element.

Using these most preferred attributes, the dnGenerator generates partial subject DNs of the following format:

CN=cnName cnUniqueId [sequence_number],O=organisation

Here sequence_number can be added to ensure uniqueness, see CP/CPS for details. This part does not have any configuration option, and will be absent in most cases.

The generated partial subject DN will then get combined with the baseDN provided as attribute in the configuration.

Extensions

The Delegation Server also supports adding certificate extensions into the generated certificate. Since the MyProxy GET Command is not designed to transport any additional user extension requests, the USERNAME field is overloaded for this purpose. The MyProxy Server is then responsible to strip any additional extension requests using the certificate_issuer_program (see man myproxy_server.config).

Currently the only supported extension is the email address of the authenticated user, inserted in the certificate's subjectAltName. It can be configured by setting adding an extension with the appropriate name and source value. See the example above. The extension source values work the same way as other source values of the dnGenerator element.

Attribute Filters

Sometimes there is some special transformation that a source user attribute has to go through before it can be used for building the subject DN. To accommodate these special corner cases that only apply to a limited set of attributes (depending on the attribute itself) we developed Attribute Filters. Attribute Filters take a single user attribute as input, do some transformation on them, and then give them back to the processing pipeline. You can develop your own attribute filter by implementing the ShibAttributeFilter interface and configuring your implementation as such:

      <attributeFilters>
               <filter name="url">eu.rcauth.delegserver.oauth2.shib.filters.URLDomainNameFilter</filter>
      </attributeFilters>

The attributeFilters definition is not part of the dnGenerator element, simply add it to the service element. Every attribute filter defined here will have a name by which it can be referenced in the rest of the configuration file. In order to apply a filter on a specific source user attribute simply add the filter attribute with the appropriate name to the desired source.

See the example above, where the URLDomainNameFilter is used to process a URL by extracting its domain name component.

Database

Using the database backend will require you to prepare the database and its tables before using the web application. The original OA4MP Server comes with a set of defined schemas used by the application. The Delegation Server implementation uses an updated set of schemas which adds an additional table called trace_records and introduces changes in the clients and transactions tables.

The clients table will have one additional column holding a description about the registered client. This description text about the client is presented to the user during the consent giving.

Column Name	Column Type
description	TEXT CHARACTER SET 'utf8'

The transactions table will have four additional columns:

Column Name	Column Type
claims	TEXT CHARACTER SET 'utf8'
user_attributes	TEXT CHARACTER SET 'utf8'
trace_record	CHAR(44)
sequence_nr	SMALLINT UNSIGNED

The new table called trace_records holds a single entry for every authenticated user who ever requested a certificate. This table is kept for two reasons: to avoid issuing the same certificate DN to two separate users, and to keep a traceable record of usage. The table looks like the following:

Column Name	Column Type
cn_hash	CHAR(44)
sequence_nr	SMALLINT UNSIGNED,
attribute_hash	CHAR(44)
attribute_salt	CHAR(44)
attribute_names	TEXT
first_seen	TIMESTAMP DEFAULT CURRENT_TIMESTAMP
last_seen	TIMESTAMP DEFAULT CURRENT_TIMESTAMP

Note that no actual user attributes are kept in this table, only one way hashes!

CLI

The client approval cli, oa2-cli, can be found deployed under the /var/www/server/tools directory. OA4MP is built with self-registration support. Clients can access a special /register endpoint on the Delegation Server for self-registration. However, before a client is accepted by the Delegation Server, it has to be approved. The oa2-cli tool is used to approve pending self-registrations from clients. The clients in this context are the Master Portals. For more information about this cli, consult this page.
The cli can also be used to create the JSON web keys, see the README for the Ansible scripts for details.

The Delegation Server extends the regular OA4MP cli in order to accommodate the database changes introduced in the clients table. With the extended cli, you can add or modify the description field of registered clients (Master Portals).

Extras

CRL

The back-end CA creates new CRLs, which it copies over to the Delegation Server. In order to make these CRLs public and available the Delegation Server copies the new CRL and publishes it into its web root https://delegation-server/crl.pem.

A cron job (/etc/cron.d/crl_publish) is responsible for refreshing the CRL on the Delegation Server every minute.

Monitor script

A monitoring script, /usr/local/sbin/ca_checker.sh, is run hourly via a cronjob, /etc/cron.hourly/ca_checker.cron. It will do a basic connection test to the myproxy-server running on the back-end CA and store the resulting output. Each time the output changes from the previous time, the script will send an email to the defined contact email address (root@localhost by default). Note that this results in syslog messages such as

Dec 31 12:34:56 testmachine myproxy-server[1234]: Connection from 127.0.0.1
Dec 31 12:34:56 testmachine myproxy-server[1234]: Authenticated client <anonymous>
Dec 31 12:34:56 testmachine myproxy-server[1234]: Non-numeric characters in command string "CA TEST"
Dec 31 12:34:56 testmachine myproxy-server[1234]: Exiting: error parsing request

It is difficult to prevent this, but indicates the server is running normally.

Logs

General log messages produced by the Master Portal server and client go to their respective log files: General log messages produced by the Delegation Server go to the following log file:

/var/www/server/log/oauth2.log.0

while the trace logs (see above for details) go to:

/var/www/server/log/trace.log.0

By default logs are appended to the existing logs which are rotated when they reach the maximum logsize. See further above and at the logging documentation.

The cli tool logs can be found at:

 /var/www/server/log/oa2-cli.log

Exceptions and stack traces thrown by the Delegation Server application will end up in the logs of the web container (Tomcat):

# on CentOS6
less /var/log/tomcat/catalina.out

# on CentOS7
journalctl -l -u tomcat.service 

The MyProxy Server, i.e. the back-end CA logs in the syslog, however they are located on the back-end CA. Therefore inspecting these in real time is difficult for a production setup, but the back-end CA backs up its log directory daily to the Delegation Server, hence you can view its (day old) logs at

/var/lib/ca_backup/backup/log/