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.
In case you want to deploy a Master Portal, make sure to check out our guide for using the Ansible deployment scripts. Most of the presented configurations below are set by the ansible scripts.
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/log hold 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 Server 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. Note that this password should be the same as the password configured for myproxy in the MP Client configuration, otherwise the MP Server will be unable to retrieve proxies inserted by the MP Client.
The Master Portal expects a proxy lifetime value to be provided with a /getproxy request. This parameter, however, is optional. In case no proxy lifetime value is provided in the request, the Master Portal will default to the configured value in defaultLifetime. The defaultLifetime is set in seconds and it's recommended value is 12 hours.
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:
- 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:
- max_proxy_lifetime : This is a Master Portal server side maximum value in seconds imposed on the proxies being retrieved via /getproxy. Recommended value being 11 days.
- tolerance : This is a tolerance applied to the max_proxy_lifetime. It is a small timeframe in seconds (usually a day) which prevents the Delegation Server from being flooded with requests. Without the tolerance value, consecutive /getproxy requests that keep asking for same proxy with the maximum allowed lifetime (max_proxy_lifetime) would trigger consecutive credential renewals via the Delegation Server.
In case you are interested in programming your own validators you will have to implement the GetProxyRequestValidator interface, and rebuild the Master Portal from source.
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 Master Portal implementation uses an updated set of schemas which introduces two additional columns in the transactions table:
| Column Name | Column Type |
| claims | TEXT CHARACTER SET 'utf8' |
| mp_client_session_identifier | TEXT |
The claims column is used to store the set of released claims of the current transaction in JSON format. The mp_client_session_identifier column is used to store the session identifier used by the MP Client for the current transaction. See more about session keeping inside the Master Portal here.
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 server for self-registration. However, before a client is accepted by the Master Portal, 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 portals (Science Gateways). For more information about this cli, consult this page.
MP Client Config
The MP Client is the web application called mp-oa2-client.war living in the web container. Next to the web application there are a set of additional resources used by the client under /var/www/client structured in the following way:
/var/www/client/conf holds client configuration files /var/www/client/log holds the client logs produced by the web application /var/www/client/storage is only used if using file system for storage backend; when using a database this directory is unused
Configuration
The MP Client configuration file can be found under /var/www/client/conf/cfg.xml. The configuration file is XML formatted and follows the structure give by the OA4MP Client. For more information about the standard OA4MP Client configuration, consult this page. Here we will follow with describing additional configuration options that were made available in the MP Client implementation only. These do not belong to the standard OA4MP configurations.
<myproxy host="credstore_host" port="credstore_port" password="credstore_pw">
...
</myproxy>
Just like in case of the MP Server configuration, the MP Client also needs a password attribute in the myproxy configuration tab. The configured password will be used to STORE/PUT proxy certificates in the credential store. Note that this password should be the same as the password configured for myproxy in the MP Server configuration, otherwise the MP Server will be unable to retrieve proxies inserted by the MP Client.
