Difference between revisions of "Delegation Server Administrator Guide"

From PDP/Grid Wiki
Jump to navigationJump to search
(cli & extras & log)
 
(40 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= Introduction =
 
= Introduction =
  
The Delegation Server is a key component in the [[AARC_Pilot | AARC Piloting]] work. The Delegation Server issues certificates for authenticated users based on their released attributes. Our current Delegation Server implementation is called [[AARC_Pilot_-_RCAuth.eu | RCAuth.eu]]. This page is dedicated for Delegation Server operators and administrators who wish to fine tune their server.  
+
The Delegation Server forms the basis for the [[RCauth.eu_and_MasterPortal_overview | 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 [[AARC_Pilot_-_Building_from_Source#Building_the_Delegation_Server | guide]] on using Ansible deployment scripts. Most of the presented configuration from below are set by the Ansible scripts.
+
In case you want to '''deploy''' the Delegation Server, make sure to check out our [[RCauth_Delegation_Server_%26_MasterPortal_-_Ansible_scripts | guide]] on using Ansible deployment scripts.
 +
This page highlights the important parts of the configuration.
  
 
= Delegation Server Configuration =
 
= Delegation Server Configuration =
  
The Delegation Server is a web application packaged in a .war file, based on the [http://grid.ncsa.illinois.edu/myproxy/oauth/server/index.xhtml OA4MP Server]. In order to deploy it you will need a web container. The setup used for this includes [https://tomcat.apache.org/tomcat-7.0-doc/index.html Tomcat] as the web container (following the suggestions given by the [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/getting-started.xhtml OA4MP Server]), with an [https://httpd.apache.org/ Apache] httpd server running in front of the web container, acting as a reverse https proxy, and authenticating users through [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig mod_shib]. Details on the reverse proxy setup can be found [https://tomcat.apache.org/tomcat-7.0-doc/proxy-howto.html here] and [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/getting-started.xhtml here].  
+
The Delegation Server is a web application packaged in a .war file, based on the [http://grid.ncsa.illinois.edu/myproxy/oauth/server/index.xhtml OA4MP Server]. In order to deploy it you will need a web container. The setup used for this includes [https://tomcat.apache.org/tomcat-7.0-doc/index.html Tomcat] as the web container (following the suggestions given by the [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/getting-started.xhtml OA4MP Server]), with an [https://httpd.apache.org/ Apache] httpd server running in front of the web container, acting as a reverse http(s) proxy, and authenticating users through [https://wiki.shibboleth.net/confluence/display/SP3/Apache mod_shib]. Details on the reverse proxy setup can be found [https://tomcat.apache.org/tomcat-7.0-doc/proxy-howto.html here] and [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/getting-started.xhtml here].  
  
 
== Apache ==
 
== 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 [https://httpd.apache.org/docs/current/mod/mod_proxy.html mod_proxy] setting to allow the Delegation Server to pass through. Your configuration should contain something like the following:  
+
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 [https://httpd.apache.org/docs/current/mod/mod_proxy.html 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/authorized !
 
  ProxyPass /oauth2 ajp://127.0.0.1:8009/oauth2
 
  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 [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/authorized.xhtml 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!
+
'''Note!''' In particular the /authorized endpoint should '''NOT''' be forwarded: it is a [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/authorized.xhtml private endpoint] meant only to be called from within the server.
  
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.  
+
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>
 
  <Location /oauth2/authorize>
Line 25: Line 31:
 
   ShibRequestSetting exportAssertion true
 
   ShibRequestSetting exportAssertion true
 
   ShibUseHeaders On
 
   ShibUseHeaders On
   Require valid-user
+
  <RequireAll>
 +
#   Require not user jdoe@example.org
 +
    Require valid-user
 +
  </RequireAll>
 
  </Location>
 
  </Location>
 
   
 
   
Line 32: Line 41:
 
   ShibRequestSetting requireSession 1
 
   ShibRequestSetting requireSession 1
 
   ShibUseHeaders On
 
   ShibUseHeaders On
   Require valid-user
+
  <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>
 
  </Location>
  
Take a look at the [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig mod_shib] documentation to see what the above options all mean.
+
See the [https://wiki.shibboleth.net/confluence/display/SP3/Apache mod_shib] documentation for details on the above options.
  
'''Note!''' Beware of the [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSpoofChecking 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'''.
+
'''Note!''' Beware of the [https://wiki.shibboleth.net/confluence/display/SP3/SpoofChecking 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 ==
 
== Tomcat ==
Line 45: Line 67:
 
* 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 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 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" address="127.0.0.1" tomcatAuthentication="false" protocol="AJP/1.3"/>
+
  <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 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.
+
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"
 
  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 [[#Configuration | config file]], see [http://grid.ncsa.illinois.edu/myproxy/oauth/server/configuration/server-email.xhtml email notifications] for details.
  
 
== Shibboleth ==
 
== 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 [[AARC_Pilot_-_RCAuth.eu | 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 [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPGettingStarted 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 [https://www.rcauth.eu/policy/DutchGrid-RCauth-Pilot-ICA-G1-CPCPS.pdf policy]) is:
+
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_and_MasterPortal_overview | 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 [https://wiki.shibboleth.net/confluence/display/SP3/GettingStarted 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 [https://www.rcauth.eu/policy/DutchGrid-RCauth-Pilot-ICA-G1-CPCPS.pdf CP/CPS]) is:
  
 
{| class="wikitable"  
 
{| class="wikitable"  
Line 113: Line 142:
 
|}
 
|}
  
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''':
+
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="Chaining">
Line 120: Line 149:
 
  </AttributeExtractor>
 
  </AttributeExtractor>
  
== Delegation Server ==
+
== Delegation Server Config ==
  
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:
+
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/conf''' holds server configuration files
 
* '''/var/www/server/log''' holds the server logs produced by the web application
 
* '''/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/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 [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/cli.xhtml client approval cli].
+
* '''/var/www/server/tools''' holds external tools, such as the [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/cli.xhtml 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 | Tomcat]] configuration.
+
* '''/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 | Tomcat]] configuration.
  
 
=== 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 [http://grid.ncsa.illinois.edu/myproxy/oauth/server/index.xhtml OA4MP Server]. For more information about the standard OA4MP Server configuration, consult [http://grid.ncsa.illinois.edu/myproxy/oauth/server/configuration/config-index.xhtml 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.
+
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 [http://grid.ncsa.illinois.edu/myproxy/oauth/server/index.xhtml OA4MP Server]. For more information about the standard OA4MP Server configuration, consult [http://grid.ncsa.illinois.edu/myproxy/oauth/server/configuration/config-index.xhtml this] page. Here we will describe the additional configuration options that are specific to the Delegation Server implementation.
  
 
==== Trace Logging ====
 
==== Trace Logging ====
  
For traceability reasons outlined in the [https://www.rcauth.eu/policy/DutchGrid-RCauth-Pilot-ICA-G1-CPCPS.pdf 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 not 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:
+
For traceability reasons outlined in the [https://www.rcauth.eu/policy/DutchGrid-RCauth-Pilot-ICA-G1-CPCPS.pdf 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"
+
       <traceLogging logFileName="/var/www/server/log/trace.log"
 
                 logName="trace"
 
                 logName="trace"
                 logSize="1000000"
+
                 logSize="10000000"
 
                 logFileCount="10"
 
                 logFileCount="10"
 
                 debug="true"
 
                 debug="true"
 
       />
 
       />
  
The '''traceLogging''' tag supports the same configuration options as the OA4MP server's [http://grid.ncsa.illinois.edu/myproxy/oauth/common/configuration/logging.xhtml logging] tag.
+
The '''traceLogging''' tag supports the same configuration options as the OA4MP server's [http://grid.ncsa.illinois.edu/myproxy/oauth/common/configuration/logging.xhtml 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 | 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 ====
 
==== Claim Mapping ====
Line 151: Line 184:
 
The OA4MP implementation has a '''scopes''' [http://grid.ncsa.illinois.edu/myproxy/oauth/apidocs/edu/uiuc/ncsa/oa4mp/oauth2/client/OA2MPService.html#getRequestedScopes-- configuration] element by which it offers support for additional scopes (other than its predefined set in [http://grid.ncsa.illinois.edu/myproxy/oauth/apidocs/edu/uiuc/ncsa/security/oauth_2_0/OA2Scopes.html#basicScopes OA2Scopes.basicScopes]). The Delegation Server implementation extends this configuration element, allowing the definition of claim mapping for a within a specific scope:
 
The OA4MP implementation has a '''scopes''' [http://grid.ncsa.illinois.edu/myproxy/oauth/apidocs/edu/uiuc/ncsa/oa4mp/oauth2/client/OA2MPService.html#getRequestedScopes-- configuration] element by which it offers support for additional scopes (other than its predefined set in [http://grid.ncsa.illinois.edu/myproxy/oauth/apidocs/edu/uiuc/ncsa/security/oauth_2_0/OA2Scopes.html#basicScopes 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">
+
       <scopes handler="eu.rcauth.delegserver.oauth2.DSDynamicClaimsSourceImpl">
 
   
 
   
 
           <scope name="edu.uiuc.ncsa.myproxy.getcert">
 
           <scope name="edu.uiuc.ncsa.myproxy.getcert">
Line 165: Line 198:
 
   
 
   
 
           <scope name="profile">
 
           <scope name="profile">
 +
                <claim name="name">displayName</claim>
 +
                <claim name="family_name">sn</claim>
 
                 <claim name="given_name">givenName</claim>
 
                 <claim name="given_name">givenName</claim>
                <claim name="family_name">sn</claim>
 
 
           </scope>
 
           </scope>
 
   
 
   
Line 174: Line 208:
 
                 <claim name="eduPersonTargetedID">eptid</claim>
 
                 <claim name="eduPersonTargetedID">eptid</claim>
 
                 <claim name="eduPersonPrincipalName">eppn</claim>
 
                 <claim name="eduPersonPrincipalName">eppn</claim>
                 <claim name="oidc">oidc</claim>
+
                 <claim name="eduPersonUniqueId">euid</claim>
                 <claim name="affiliation">affiliation</claim>
+
                 <claim name="eduperson_assurance">assurance</claim>
                 <claim name="ou">ou</claim>
+
                 <claim name="eduperson_scoped_affiliation">affiliation</claim>
                <claim name="name">displayName</claim>
 
 
           </scope>
 
           </scope>
 
   
 
   
 
       </scopes>
 
       </scopes>
 
   
 
   
The '''handler''' attribute of the outer '''scopes''' element defines which handler implementation to use. More on custom scope handlers [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/custom-scope-handler.xhtml here].  
+
The '''handler''' attribute of the '''scopes''' element defines which handler implementation to use. The DSDynamicClaimsSourceImpl is an extension of the [http://grid.ncsa.illinois.edu/myproxy/oauth/apidocs/edu/uiuc/ncsa/myproxy/oa4mp/oauth2/claims/BasicClaimsSourceImpl.html BasicClaimsSourceImpl] (Note: before the 4.0 release of OA4MP, the BasicClaimsSourceImpl was called the BasicScopeHandler, see [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/custom-scope-handler.xhtml 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.
  
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 [https://docs.google.com/document/d/1cs3peO9FxA81KN-1RC6Z-auEFIwRbJpZ-SFuKbQzS50/pub#h.9om6a4erbsvr OIDC Scopes and Claims].  
+
The names of the scopes and claims listed above reflects the current configuration of the RCauth Delegation Server. It partially follows [http://goo.gl/VnMKXS#h.9om6a4erbsvr OIDC/OA4MP Scopes and Claims]. It is foreseen we will move to the [https://wiki.refeds.org/display/CON/Consultation%3A+SAML2+and+OIDC+Mappings REFEDS whitepaper] naming for also for the other eduperson claims in the near future.<br>
 +
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. 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 | 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 | DN Generator ]] section for more details on this attribute.
+
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 | 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 | DN Generator ]] section for more details on this attribute.
  
 
==== DN Generator ====
 
==== 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 [https://www.rcauth.eu/policy/DutchGrid-RCauth-Pilot-ICA-G1-CPCPS.pdf RCAuth.eu policy] 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:
+
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 [https://www.rcauth.eu/policy/DutchGrid-RCauth-Pilot-ICA-G1-CPCPS.pdf 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">
 
       <dnGenerator attributeName="X509_CERT_SUBJECT" type="rfc2253" baseDN="DC=rcauth-clients,DC=rcauth,DC=eu">
Line 217: Line 253:
 
       </dnGenerator>
 
       </dnGenerator>
  
The '''dnGenerator''' element contains sets of source attributes for various DN components. The source attributes, just like in case of the [[#Claim_Mapping | Claim Mapping]], are the user attributes released by the user's IdP ([[#Shibboleth |shibboleth attributes]]). The '''dnGenerator''' element contains three attributes, all referring to the new DN attribute being created:
+
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 | Claim Mapping]], are the user attributes released by the user's IdP ([[#Shibboleth |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_Mapping |claim mappings]].
 
* '''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_Mapping |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 ''rfc253''. Note that the type of the following  '''baseDN''' attribute has to match the '''type''' specified here.
+
* '''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. 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.
+
* '''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 '''dnGenerator''' generates partial subject DNs of the following format:
+
The different '''source''' elements are defining which attributes should be used for generating the different parts of the DN:
 
 
/O=organisation/CN=cnName cnUniqueId [sequence_number]
 
 
 
With the following generated elements:
 
  
 
* '''organisation''' : Contains an ordered list of source attributes for generating the 'O' RDN.  
 
* '''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.
 
* '''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.
 
* '''cnUniqueId''' : Contains an ordered list of source attributes for generating the unique identifier part of the 'CN' RDN.
* sequence_number : Given [https://www.rcauth.eu/policy/DutchGrid-RCauth-Pilot-ICA-G1-CPCPS.pdf enough suspicion] of clashing DNs for different users, an incremental sequence number gets appended to the generating DN. This does not have any configuration option, and will be absent in most cases.
 
  
Every list 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 |shibboleth attribute]] set) will be taken as the source value for that particular DN element.  
+
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 |shibboleth attribute]] set) will be taken as the source value for that particular DN element.  
  
The generated partial subject DN will get appended to the '''baseDN''' provided as an attribute in the configuration.
+
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 [https://www.rcauth.eu/policy/DutchGrid-RCauth-Pilot-ICA-G1-CPCPS.pdf 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 =====  
 
===== Extensions =====  
  
The Delegation Server also supports adding extension into the generated certificate.  Since the [http://grid.ncsa.illinois.edu/myproxy/protocol/ 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).  
+
The Delegation Server also supports adding certificate extensions into the generated certificate.  Since the [http://grid.ncsa.illinois.edu/myproxy/protocol/ 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).  
  
The only supported extension for now 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.  
+
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 =====
 
===== Attribute Filters =====
  
Sometimes there is some special transformation that a source user attribute has to go through before it being 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 [https://github.com/rcauth-eu/aarc-delegation-server/blob/master/delegation-server/src/main/java/org/delegserver/oauth2/shib/filters/ShibAttributeFilter.java ShibAttributeFilter] interface and configuring your implementation as such:
+
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 [https://github.com/rcauth-eu/aarc-delegation-server/blob/master/delegation-server/src/main/java/eu/rcauth/delegserver/oauth2/shib/filters/ShibAttributeFilter.java ShibAttributeFilter] interface and configuring your implementation as such:
  
 
       <attributeFilters>
 
       <attributeFilters>
                 <filter name="url">org.delegserver.oauth2.shib.filters.URLDomainNameFilter</filter>
+
                 <filter name="url">eu.rcauth.delegserver.oauth2.shib.filters.URLDomainNameFilter</filter>
 
       </attributeFilters>
 
       </attributeFilters>
  
The '''attributeFilters''' definition does not belong under '''dnGenerator''' element, simply add it to the [http://grid.ncsa.illinois.edu/myproxy/oauth/server/dtd/server-dtd-service-tag.xhtml 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 [[#DN_Generator |above]].
+
The '''attributeFilters''' definition is not part of the '''dnGenerator''' element, simply add it to the [http://grid.ncsa.illinois.edu/myproxy/oauth/server/dtd/server-dtd-service-tag.xhtml 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.  
  
In the example [[#DN_Generator |above]] the [https://github.com/rcauth-eu/aarc-delegation-server/blob/master/delegation-server/src/main/java/org/delegserver/oauth2/shib/filters/URLDomainNameFilter.java URLDomainNameFilter] is used to process a URL by extracting its domain name component.
+
See the example [[#DN_Generator |above]], where the [https://github.com/rcauth-eu/aarc-delegation-server/blob/master/delegation-server/src/main/java/eu/rcauth/delegserver/oauth2/shib/filters/URLDomainNameFilter.java URLDomainNameFilter] is used to process a URL by extracting its domain name component.
  
 
=== Database ===
 
=== 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 [http://svn.code.sf.net/p/cilogon/code/tags/latest/server/oauth2-mysql.sql schemas] used by the application. The Delegation Server implementation uses an [http://ndpfsvn.nikhef.nl/viewvc/pdpsoft/trunk/eu.rcauth.pilot-ica/DS/ansible/roles/delegserver/templates/oa4mp-server-mysql.sql.j2?view=co updated set of schemas] which adds an additional table called '''trace_records''' and introduces changes in the '''clients''' and '''transactions''' tables.
+
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 [https://github.com/rcauth-eu/OA4MP/blob/v4.2-RCauth-1/oa4mp-server-admin-oauth2/src/main/resources/oauth2-mysql.sql schemas] used by the application. The Delegation Server implementation uses an [https://github.com/rcauth-eu/aarc-ansible-delegation-server/blob/0.2-devel/roles/delegserver/templates/oa4mp-server-mysql.sql.j2 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.
 
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.
Line 272: Line 309:
 
|}
 
|}
  
The '''transactions''' table will have three additional columns:  
+
The '''transactions''' table will have four additional columns:  
  
 
{| class="wikitable" style="width: 55%;"
 
{| class="wikitable" style="width: 55%;"
Line 288: Line 325:
 
|-
 
|-
 
|| trace_record
 
|| trace_record
|| TEXT
+
|| CHAR(44)
 +
 
 +
|-
 +
|| sequence_nr
 +
|| SMALLINT UNSIGNED
  
 
|}
 
|}
Line 304: Line 345:
 
|-
 
|-
 
|| sequence_nr
 
|| sequence_nr
|| SAMLLINT UNSIGNED,
+
|| SMALLINT UNSIGNED,
  
 
|-
 
|-
Line 324: Line 365:
 
|-
 
|-
 
|| last_seen
 
|| last_seen
|| TIMESTAMP
+
|| TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  
 
|}
 
|}
Line 332: Line 373:
 
=== CLI ===
 
=== 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 [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/cli.xhtml this] page.
+
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 [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/cli.xhtml this] page.<br>
 +
The cli can also be used to create the JSON web keys, see the [https://github.com/rcauth-eu/aarc-ansible-master-portal/blob/0.2-devel/README README for the Ansible scripts] for details.  
  
 
The Delegation Server extends the regular OA4MP cli in order to accommodate the [[#Database | database]] changes introduced in the '''clients''' table. With the extended cli, you can add or modify the '''description''' field of registered '''clients''' (Master Portals).
 
The Delegation Server extends the regular OA4MP cli in order to accommodate the [[#Database | database]] changes introduced in the '''clients''' table. With the extended cli, you can add or modify the '''description''' field of registered '''clients''' (Master Portals).
Line 338: Line 380:
 
== Extras ==
 
== Extras ==
  
The [[AARC_Pilot_-_RCAuth.eu | Online CA]] creates new CRLs, which it syncs to the Delegation Server. In order to make these CRLs public and available the Delegation Server fetches the synced CRL and publishes it into the httpd web root. This way anybody can access the CRL via a web call to the Delegation Server (<nowiki>https://delegation-server/crl.pem</nowiki>). A cron job is responsible for refreshing the CRL on the Delegation Server every minute. In case you want to tweak this interval, edit the '''/etc/cron.d/crl_publish''' file.
+
=== CRL ===
 +
 
 +
The [[RCauth.eu_and_MasterPortal_overview | 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 <nowiki>https://delegation-server/crl.pem</nowiki>.
 +
 
 +
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 =
 
= Logs =
  
For general log messages produced by the Delegation Server you should take a look at the following two log file:
+
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
 
  /var/www/server/log/oauth2.log.0
  
For trace logs you should take a look at the file below. Read more about trace logging [[#Trace_Logging | here]].
+
while the trace logs (see [[#Trace_Logging | above]] for details) go to:
  
 
  /var/www/server/log/trace.log.0
 
  /var/www/server/log/trace.log.0
  
If an error occurs, it is generally a good idea to check the logs of the web container (Tomcat). Exceptions and stack traces thrown by the Delegation Server application will end up in this log. Here you should see (hopefully) some more details on why things have failed.
+
By default logs are appended to the existing logs which are rotated when they reach the maximum logsize.
 +
See further [[#Configuration | above]] and at the [http://grid.ncsa.illinois.edu/myproxy/oauth/common/configuration/logging.xhtml 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
 
  # on CentOS6
Line 358: Line 424:
 
  journalctl -l -u tomcat.service  
 
  journalctl -l -u tomcat.service  
  
For problems involving the MyProxy Server, you will have to investigate the logs on the Online CA. This is not a trivial task, since you will need physical access to the box in order to inspect the logs in real time. However, the Online CA backs up its log to the Delegation Server, and therefore you can view its outdated (a day old) logs from
+
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/
 
  /var/lib/ca_backup/backup/log/

Latest revision as of 08:50, 5 September 2019

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/