Oauth2/OIDC Server Setup

Deploy the server webapp:

$ cd $CATALINA_HOME/webapps
$ curl -sO https://github.com/ncsa/oa4mp/releases/latest/download/oauth2.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: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 (or whatever the address is goign to be) 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 https://github.com/ncsa/oa4mp/releases/latest/download/oa2-cli.jar
$ curl -sO https://github.com/ncsa/oa4mp/releases/latest/download/oa2-cli

You will probably need to edit oa2-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 oa2-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 https://github.com/ncsa/oa4mp/releases/latest/download/client2.jar

All Done!

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

Running Without CATALINA_OPTS, self-signed cert

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. You must generate your certificates and add them as well to your trust store. Here is a sample: 
    <Connector port="9443"
                protocol="HTTP/1.1"
                SSLEnabled="true"
                maxThreads="150"
                scheme="https"
                secure="true"
            URIEncoding="UTF-8"

                keystoreFile="${user.home}/certs/localhost-2020.jks"
                keystorePass="XXXXX"
                keystoreType="JKS"
                truststoreFile="${user.home}/dev/csd/config/ncsa-cacerts"
                truststorePass="YYYYY"
                truststoreType="JKS"
                clientAuth="false" sslProtocol="TLS" />

For the client, you should set atServerDN="localhost" in the client tag, e.g.

    <client name="client2-config" atServerDN="localhost">

you should simply add a keystore section to your client configuration (works with all versions of OA4MP) as described here. E.g. 

    <ssl debug="false"
         useJavaTrustStore="true">
        <trustStore>
            <path>/home/ncsa/certs/localhost-2020.jks</path>
            <password><![CDATA[XXXXX]]></password>
            <type>JKS</type>
            <certDN><![CDATA[CN=localhost]]></certDN>
        </trustStore>
    </ssl>

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.