OAuth 1.0a for MyProxy: Installation Walk-through

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.

Prerequisites

First we set up our Java and MyProxy environments.

Java and Tomcat

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>

MyProxy

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/.

Oauth 1 Server Setup

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

Oauth1 Client Setup

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.

Oauth1 Client Approval

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

All Done!

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.

Oauth2/OIDC Server Setup

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

Oauth2/OIDC Client Setup

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

Oauth2/OIDC Client Approval

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

All Done!

If everything went well, the example OAuth for MyProxy client should be running at https://localhost:8443/client2/.

Running Without CATALINA_OPTS

This walkthrough will get you up to speed in a hurry. Should you wish to run the server locally regularly, you will need to configure the Tomcat SSL connector. Here is a sample:
<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.


Last modified 10/30/17.
©2000-2013 Board of Trustees of the University of Illinois.