Master Portal Administrator Guide

Introduction

The Master Portal is a central component in the AARC Piloting work. The Master Portal caches long lived user proxies into its Credential Store, and returns short lived proxies on demand to a trusted portal (Science Gateway) for authenticated users. This page is dedicated for Master Portal operators and administrators who wish to configure their Master Portals.

Credential Store Configuration

The Master Portal cannot be operated without its Credential Store. Missing the Credential Store from your setup will render your Master Portal unable to cache and retrieve any proxy certificates. Without the Credential Store a Master Portal can still be used for user authentication (via OIDC), but it's GetProxy Endpoint will be unable to retrieve proxy certificates.

MyProxy Server

The Credential Store is nothing else than a simple MyProxy Server installation running in Credential Store mode. It being an unmodified MyProxy Server, you can tailor its configuration to your needs following the official MyProxy Server admin guide. In order to run it as a Credential Store backend for the Master Portal, you will need the following set of configurations:

accepted_credentials            <Master Portal Host DN>
authorized_retrievers           <Master Portal Host DN>
authorized_renewers             <Master Portal Host DN>
default_authorized_renewers     <Master Portal Host DN>
trusted_retrievers              <Master Portal Host DN>

cert_dir                        /etc/grid-security/certificates
max_proxy_lifetime              264

The Master Portal authenticates to the MyProxy Server via its host certificates. Make sure to configure the DN of the host certificate of the Master Portal (<Master Portal Host DN>) as the authorized party in the MyProxy Server configuration snippet above. If you are interested to see what each of those individual authrizations stand for please consult the man page of myproxy-server.config. The cert_dir has to point to the set of trust roots trusted by the MyProxy Server. The max_proxy_lifetime determines the maximum lifetime in hours that a returned proxy credential can have. Since the Master Portal is only allowed to release short lived proxy certificates, a lifetime of 264 hours (11 days) is imposed by default. The MyProxy Server will be able to release proxies with shorter lifetime on demand, but not with bigger lifetime than that of max_proxy_lifetime.

VOMS Support

The MyProxy Server returns returns non-vomsified proxies by default, but it has support for releasing VOMS-ified proxies as well. Asking for VOMS-ified proxies is also supported in the Master Portal via the GetProxy Endpoint. In order to enable VOMS support in the MyProxy Server, set allow_voms_attribute_requests

allow_voms_attribute_requests   True

Self-Authorized Rertieval

The MyProxy Server disallows self renewal of certificates by default, but this function can be enabled. By enabling this, users possessing a valid proxy certificate will be able to renew it (prolong its lifetime) by directly talking to the MyProxy Server, and without the intervention of any of the web components (such as the Master Portal). This setup is still experimental and it does not affect the delegation scenario involving the Master Portal, therefore it is safe to unset when not needed.

authorized_renewers             "/DC=NL/DC=Example/O=*"
allow_self_authorization        True

In the above configuration snippet the authorized_renewers should contain a "DN regex". This regex should be the common bit of the DNs of the proxy certificates stored in the MyProxy Server. This configuration will NOT allow users to renew other user's credentials, because there are per-credential policies in place that restricts the access of a single proxy certificate to it's own full "DN regex". These policies are added to each credential during their upload by the Master Portal.

Trust Root

Deploying the trust root of the Online CA (see Online CA of detailed achitecture) is an important step. Make sure to deploy this trust root in the directory pointed by the cert_dir above, otherwise the MyProxy Server will not accept the generated user proxies the Master Portal will try to upload in its store. Make sure that the trust root has its signing policy, crl, and subject hash links in order.

Extras

Purge Script

The MyProxy Server doesn't remove expired or revoked credentials. The Master Portal can detect if a proxy certificate stored in the MyProxy Server is expired and it can replace it with a new one, but it cannot detect revoked certificates. Because of this, it can happen that the MyProxy Server can contain expired or revoked certificates. In order to account for this (mostly because a revoked certificate poses a threat) we developed a script called myproxy-purge.sh. The myproxy-purge.sh script is periodically called by a cron job to check every proxy certificate stored in the MyProxy Server and remove the ones that have expired or have been revoked. By default this script is called every 6 hours. You can change this frequency by editing /etc/cron.d/myproxy_purge.

Master Portal Configuration

The Master Portal is made up internally of a OA4MP Server and Client, just as described here. Both OA4MP Server and Client are web applications packaged in .war files. In order to deploy these you will need a web container. The setup used for this includes Tomcat as the web container (following the suggestions given by OA4MP Server), with an Apache httpd server running in front of the web container, acting as a reverse https proxy. Details on the reverse proxy setup can be found here and here.

Apache

The Apache server holds configurations relating to the SSL setup of the Master Portal and to the proxy setup talking to Tomcat. In case you want to tweak either of these options, you should look into /etc/httpd/conf.d/ssl.conf. Make sure to configure the mod_proxy setting to allow for both MP Client and Server to pass through. For a list of valid endpoints on the Master Portal, you can consult this page. Your configuration should contain something like the following:

ProxyPass /mp-oa2-server/authorized !
ProxyPass /mp-oa2-server ajp://127.0.0.1:8009/mp-oa2-server

ProxyPass /mp-oa2-client/forwardgetcert !
ProxyPass /mp-oa2-client/startRequest !
ProxyPass /mp-oa2-client ajp://127.0.0.1:8009/mp-oa2-client

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

Tomcat

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

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

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

Since the Master Portal is made up of two separate components, a MP Server and Client , they run as two independent web applications inside the web container. In order to be able to forward requests internally between the two (without going through the browser) the crossContext flag has to be enabled in context.xml.

<Context crossContext="true">     
...
</Context>

MP Server Config

The MP Server is the web application called mp-oa2-server.war living in the web container. Next to the web application there are a set of additional resources used by the servers under /var/www/server structured in the following way:

• /var/www/server/conf holds server configuration files
• /var/www/server/loghold the server logs produced by the web application
• /var/www/server/storage is only used if using file system for storage backend; when using a database this directory is unused
• /var/www/server/tools holds external tools, such as client approval cli.

Configuration

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

      <myproxy host="credstore_host" port="credstore_port" password="credstore_pw">

                ...

                <defaultLifetime>43200</defaultLifetime>

                <validators>
                       <validator handler="org.masterportal.oauth2.server.validators.DNValidator">
                               <input name="input_claim">cert_subject_dn</input>
                       </validator>
                       <validator handler="org.masterportal.oauth2.server.validators.LifetimeValidator">
                               <input name="max_proxy_lifetime">950400</input>
                               <input name="tolerance">86400</input>
                       </validator>
                </validators>

      </myproxy>

The standard myproxy configuration only allows for setting the host and port, but not the password to use when talking to a MyProxy Server. The MP Server adds the password attribute to the myproxy configuration tag. The configured password will be used when GET-ing a proxy of the stored credential.

The MP Server introduces validators. Validators are executed during a /getproxy call in order to decide whether a stored credential is still valid, or not. The validators defined in the configuration file are executed in the order in which the appear in the file. Every validator gets as input the current transaction object, request object and the response of the MyProxy INFO command on the requested credentials. A validator can either pass or fail. In case ALL validators pass, the stored credential is deemed valid, and the /getproxy call resumes and a proxy is returned. In case ANY validator fails, the stored credential is treated as invalid in which case the Master Portal will renew it by asking for a new certificate from the Delegation Server. Once the certificate is renewed, the /getproxy call resumes and a proxy is returned. The MP Server comes with two validator implementations:

• DNValidator : A user's certificate DN is constructed from the attributes released by his IdP. The way in which DNs are constructed is outlines in the RCauth.eu policy file. In case the attributes released by a user's IdP change the DN constructed for the user also changes with it. Since the Master Portal is a caching service, it cache keep a user's proxy certificate for its full lifetime, but it will not account for attribute/DN changes by default. Using the DNValidator will make sure that the DN of the cached certificate matches that of the DN generated from the current user attributes (from the current session). This validator takes one input:
  1. input_claim : The Master Portal does not know how to construct a DN from user attributes (it doesn't have to know, since it's the Delegation Server's job), therefore the DN of the cached certificate will be compared with the DN released in the current set of claims (from the current session) by the Delegation Server. The cert_subject_dn claim has been designated for this purpose, but through this input, the name of the actual claim used for comparison can be configured.
• LifetimeValidator : Validates the requested proxy lifetime (from the /getproxy call) against the actual proxy lifetime remaining in the cached credential. This validator will check against invalid proxy lifetime requests that exceed server maximum, and against proxy lifetime requests that are larger than the time left in the cached proxy. The maximum proxy lifetime used by this validator is constructed by max_proxy_lifetime - tolerance from the following two inputs:
  1. max_proxy_lifetime :
  2. tolerance :

MP Client Config

• DB tables

• oa4mp server config

• oa4mp client config