The following walk-through illustrates how to locally install, configure, and run an OAuth 1.0a for MyProxy client and server as a regular system user. This not how to set it up in a production system or even a standard Tomcat installation. Pay especial attention to the environment variables. You must set them each time manually before you run the client and server.
First we set up our Java and MyProxy environments.
The OAuth for MyProxy client and server are Java web applications, so first we need to configure our Tomcat web application container.
Confirm that Java is installed:
$ java -version java version "1.8.0_05"
Install Tomcat 6 or 7:
$ tar xvfz ~/Downloads/apache-tomcat-6.0.35.tar.gz $ cd apache-tomcat-7.0.63 $ export CATALINA_HOME=`pwd` $ export CATALINA_BASE=$CATALINA_HOME # start with an empty webapps directory $ mv webapps webapps.orig $ mkdir webapps
Next configure Tomcat SSL. We use a self-signed X 509 certificate in this walk-through, but a production install should use an SSL certificate that will be trusted by web browsers and Java applications by default (i.e., from a commercial certification authority).
$ mkdir ~/oa4mp $ cd ~/oa4mp $ keytool -genkeypair -alias tomcat -keyalg RSA -dname "cn=localhost" -keypass changeit -storepass changeit $ keytool -exportcert -alias tomcat -storepass changeit -file tomcat.cer $ keytool -importcert -v -trustcacerts -alias tomcat -file tomcat.cer -keystore cacerts.jks -keypass changeit -storepass changeit $ export CATALINA_OPTS="-Djavax.net.ssl.trustStore=$HOME/oa4mp/cacerts.jks" # trust our self-signed certificate $ vi $CATALINA_BASE/conf/server.xml # uncomment the "SSL HTTP/1.1 Connector" entry
Next enable Tomcat email support:
The installation of the server requires that Java mail be installed.
$ cd $CATALINA_HOME $ unzip ~/Downloads/javamail1_4_5.zip $ cp -p javamail-1.4.5/mail.jar lib $ vi $CATALINA_HOME/conf/context.xml # add javax.mail.Session Resource configuration $ tail -2 $CATALINA_HOME/conf/context.xml <Resource name="mail/Session" type="javax.mail.Session" auth="Container"/> </Context>
The OAuth for MyProxy server acts as a front-end to an existing MyProxy server. The OAuth
server can run on the same system as the MyProxy server or they can run on separate systems. To connect securely to
the MyProxy server, the OAuth for MyProxy install must include a trusted CA certificates directory (in /etc/grid-security/certificates
or $HOME/.globus/certificates). Since we're installing as a regular system user, we use the myproxy-get-trustroots
command to create our $HOME/.globus/certificates directory.
Alternatively, you can manually setup a $HOME/.globus/certificates directory using a CA distribution
from IGTF or XSEDE or another trusted source. You will have to do this anyway
if your platform does not have a myproxy client available.
$ myproxy-get-trustroots -s myproxy.example.edu Bootstrapping MyProxy server root of trust. New trusted MyProxy server: /C=US/O=National Center for Supercomputing Applications/OU=Services/CN=myproxy.example.edu New trusted CA (9b95bbf2.0): /C=US/O=National Center for Supercomputing Applications/OU=Certificate Authorities/CN=CACL Trust roots have been installed in /Users/username/.globus/certificates/.
Deploy the server webapp:
$ cd $CATALINA_HOME/webapps $ curl -sO http://svn.code.sf.net/p/cilogon/code/tags/latest/server/oauth.war
Next, configure the server:
$ vi $CATALINA_HOME/conf/web.xml # add oa4mp:server.config.file parameter
$ tail -9 $CATALINA_HOME/conf/web.xml
<context-param>
<param-name>oa4mp:server.config.file</param-name>
<param-value>/Users/username/oa4mp/server-cfg.xml</param-value>
</context-param>
<context-param>
<param-name>oa4mp:server.config.name</param-name>
<param-value>default</param-value>
</context-param>
</web-app>
$ mkdir -p ~/oa4mp/storage
$ vi ~/oa4mp/server-cfg.xml # set myproxy-server hostname, fileStore path, mail config
$ cat ~/oa4mp/server-cfg.xml # OAuth server on localhost, myproxy-server on myproxy.example.edu
<config>
<service address="https://localhost:8443/oauth" name="default">
<fileStore path="/Users/username/oa4mp/storage">
<clients/>
<clientApprovals/>
</fileStore>
<myproxy host="myproxy.example.edu" port="7512"/>
<mail enabled="true"
server="smtp.example.edu"
username="username@example.edu"
recipients="username@example.edu">
<messageTemplate>/Users/username/oa4mp/message.txt</messageTemplate>
<subjectTemplate>/Users/username/oa4mp/subject.txt</subjectTemplate>
</mail>
</service>
</config>
$ vi ~/oa4mp/message.txt
$ cat ~/oa4mp/message.txt
# A sample template
A client has requested approval.
Name: ${name}
Contact email: ${email}
Home uri: ${homeUri}
Failure uri:${failureUri}
Creation time: ${creationTime}
Generated identifier: ${identifier}
If you approve this request, you should send a notice
to the contact email and include the generated identifier.
$ vi ~/oa4mp/subject.txt
$ cat ~/oa4mp/subject.txt
Client approval request received for ${name}
$ $CATALINA_HOME/bin/startup.sh # start up the server
Next, registering the client. The first step is to generate the client keys:
$ cd ~/oa4mp $ openssl genrsa -out oauth-privkey.pem 2048 $ chmod 0600 oauth-privkey.pem $ openssl rsa -in oauth-privkey.pem -pubout -out oauth-pubkey.pem $ openssl pkcs8 -topk8 -in oauth-privkey.pem -nocrypt -out oauth-privkey.pk8 $ chmod 0600 oauth-privkey.pk8
Then submit the web form at https://localhost:8443/oauth/register
to register the client and get a client ID. Paste in the contents of ~/oa4mp/oauth-pubkey.pem in the
"Public Key" field.
Next, configure the client, entering the client ID value given as output from the client registration web form:
$ vi $CATALINA_HOME/conf/web.xml # add oa4mp:client.config.file parameter $ tail -5 $CATALINA_HOME/conf/web.xml <context-param> <param-name>oa4mp:client.config.file</param-name> <param-value>/Users/username/oa4mp/client-cfg.xml</param-value> </context-param> </web-app> $ vi ~/oa4mp/client-cfg.xml $ cat ~/oa4mp/client-cfg.xml <config> <client> <callbackUri>https://localhost:8443/client/ready</callbackUri> <privateKeyFile>/Users/username/oa4mp/oauth-privkey.pk8</privateKeyFile> <publicKeyFile>/Users/username/oa4mp/oauth-pubkey.pem</publicKeyFile> <serviceUri>https://localhost:8443/oauth</serviceUri> <id>myproxy:oa4mp,2012:/client/21653006d3ffb1344480e06e97207578</id> <showRedirectPage>true</showRedirectPage> </client> </config>Note that the last option for showRedirectPage will pause the control immediately after the first call to the server and display a url for where the client would normally be redirected and the user's private key. This is good for testing but should not be used in production servers. The default is never to show this page, so simply removing this element will allow for the redirect immediately.
Next we need to approve the client registration request with the command-line tool:
$ cd ~/oa4mp $ curl -sO http://svn.code.sf.net/p/cilogon/code/tags/latest/server/oa4mp-cli.jar $ curl -sO http://svn.code.sf.net/p/cilogon/code/tags/latest/server/oa4mp-cli
You will probably need to edit oa4mp-cli to make the paths work on your system. You will also need to either create a config file or point it at the server config file that you are already using. We recommend the latter.
Edit oa4mp-cli to point to the right paths for the config file and jar, and make sure that the permission is set to executable. Run the tool, passing in the name of the configuration as a parameter ("default" was the name in our example server configuration).
$ ./oa4mp-cli default
oa4mp >use clients
clients >ls
0. (N) myproxy:oa4mp,2012:/client_id/600019ae306de2049a701144df34ccd3 (Test428)
clients >approve 0
approver[(null)]:admin
approve this[n]:y
save this approval record [y/n]?y
approval saved
clients >exit
oa4mp >exit
Finally, Deploy the client webapp:
$ cd $CATALINA_HOME/webapps $ curl -sO http://svn.code.sf.net/p/cilogon/code/tags/latest/client/client.war
If everything went well, the example OAuth for MyProxy client should be running at https://localhost:8443/client/.
In case of trouble, check $CATALINA_HOME/logs. Post questions/comments to the discussion mailing list.
Deploy the server webapp:
$ cd $CATALINA_HOME/webapps $ curl -sO http://svn.code.sf.net/p/cilogon/code/tags/latest/server/oauth2.war
Next, configure the server. (Note: Oauth1 and Oauth2 need to use different directories for their filestores, because they use different file formats and different approver tools.)
$ vi $CATALINA_HOME/conf/web.xml # add oa4mp:server.config.file parameter
$ tail -9 $CATALINA_HOME/conf/web.xml
<context-param>
<param-name>oa4mp:oauth2.server.config.file</param-name>
<param-value>/Users/username/oa4mp/server2-cfg.xml</param-value>
</context-param>
<context-param>
<param-name>oa4mp:oauth2.server.config.name</param-name>
<param-value>server2-config</param-value>
</context-param>
</web-app>
$ mkdir -p ~/oa4mp/storage
$ vi ~/oa4mp/server-cfg.xml # set myproxy-server hostname, fileStore path, mail config
$ cat ~/oa4mp/server-cfg.xml # OAuth server on localhost, myproxy-server on myproxy.example.edu
<config>
<service address="https://localhost:8443/oauth2" name="server2-config">
<fileStore path="/Users/username/oa4mp/storage2">
<clients/>
<clientApprovals/>
</fileStore>
<myproxy host="myproxy.example.edu" port="7512"/>
<mail enabled="true"
server="smtp.example.edu"
username="username@example.edu"
recipients="username@example.edu">
<messageTemplate>/Users/username/oa4mp/message.txt</messageTemplate>
<subjectTemplate>/Users/username/oa4mp/subject.txt</subjectTemplate>
</mail>
</service>
</config>
$ vi ~/oa4mp/message.txt
$ cat ~/oa4mp/message.txt
# A sample template
A client has requested approval.
Name: ${name}
Contact email: ${email}
Home uri: ${homeUri}
Failure uri:${failureUri}
Creation time: ${creationTime}
Generated identifier: ${identifier}
If you approve this request, you should send a notice
to the contact email and include the generated identifier.
$ vi ~/oa4mp/subject.txt
$ cat ~/oa4mp/subject.txt
Client approval request received for ${name}
$ $CATALINA_HOME/bin/startup.sh # start up the server
Next, registering the client You must submit the web form at https://localhost:8443/oauth2/register to register the client and get both a client ID and client secret.
Next, configure the client. You must preserve botht he client ID and client secret in the configuration file. Note that the client secret is a single string. Do not add any line breaks or spaces and be aware that some browsers will add these when you copy the secret to the clipboard. A typical example configuration might be
$ vi $CATALINA_HOME/conf/web.xml # add oa4mp:client.config.file parameter $ tail -5 $CATALINA_HOME/conf/web.xml <config> <client name="client2-config"> <callbackUri>https://localhost:8443/client2/ready</callbackUri> <secret>DMfidLiDbA1SfH9in_QoI9tfa48HmOW18ubcOLTPHgMtrJ5G8PnNuq0hQB3E6daRXwSqe9V6O14C7jRwI7KkoM2VSCfTmGrcRJQTRL</secret> <serviceUri>https://localhost:8443/oauth2</serviceUri> <authorizeUri>https://localhost:8443/oauth2/authorize</authorizeUri> <id>myproxy:oa4mp,2012:/client/21653006d3ffb1344480e06e97207578</id> <showRedirectPage>true</showRedirectPage> </client> </config>Note that the last option for showRedirectPage will pause the control immediately after the first call to the server and display a url for where the client would normally be redirected and the user's private key. This is good for testing but should not be used in production servers. The default is never to show this page, so simply removing this element will allow for the redirect immediately.
Restart Tomcat so the new client configuration takes effect:
$ $CATALINA_HOME/bin/shutdown.sh $ $CATALINA_HOME/bin/startup.sh
Next we need to approve the client registration request with the command-line tool:
$ cd ~/oa4mp $ curl -sO http://svn.code.sf.net/p/cilogon/code/tags/latest/server/oa2-cli.jar $ curl -sO http://svn.code.sf.net/p/cilogon/code/tags/latest/server/oa2-cli
You will probably need to edit oa4mp-cli to make the paths work on your system. You will also need to either create a config file or point it at the server config file that you are already using. We recommend the latter.
Edit oa4mp-cli to point to the right paths for the config file and jar, and make sure that the permission is set to executable. Run the tool, passing in the name of the configuration as a parameter ("server2-config" in the example).
$ ./oa2-cli server2-config
oa2 >use clients
clients >ls
0. (N) myproxy:oa4mp,2012:/client_id/600019ae306de2049a701144df34ccd3 (Test428)
clients >approve 0
approver[(null)]:admin
approve this[n]:y
save this approval record [y/n]?y
approval saved
clients >exit
oa2 >exit
Deploy the client webapp:
$ cd $CATALINA_HOME/webapps $ curl -sO http://svn.code.sf.net/p/cilogon/code/tags/latest/client/client2.war
If everything went well, the example OAuth for MyProxy client should be running at https://localhost:8443/client2/.
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
URIEncoding="UTF-8"
maxThreads="150" scheme="https" secure="true"
keystoreFile="${user.home}/oa4mp/tomcat.cer"
keystorePass="changeit"
keystoreType="PKCS12"
truststoreFile="${user.home}/certs/cacerts.jks"
truststorePass="changeit"
truststoreType="JKS"
clientAuth="false" sslProtocol="TLS" />
For the client, you should simply add a keystore section to your client configuration (works with all versions of OA4MP) as described here. This is the platform independent way to make the client aware of a certificate.
This walkthrough assumes unix (CentOS, Unbuntu server). If you wish to try this under Windows or some other more exotic version of unix (such as Solaris) you should bee aware that setting the certs in CATALINA_OPTS will not be read without more tinkering with the Tomcat startup scripts. In that case the easiest thing to do is to simply add a keystore section to your client configuration.