This page contains the annotated DTD for the service configuration file. To see what something does, click on it. For a note generally on how to use configurations, look here.

NOTES: This is for a configuration file and the tag names are case sensitive, so <filestore> and <fileStore> are not the same! Also, note the color of OAuth 2 only options!

<!ELEMENT config (service)*>
<!ELEMENT service (myproxy|
      mysql|
      mariadb|
      postgresql|
      fileStore|memoryStore|
      mail|
      scopes|
      messages|
      logging|
      authorizationServlet|
      ldap|
      JSONWebKey
    )*>
<!ATTLIST service
    address CDATA #IMPLIED
    name CDATA #IMPLIED
    version CDATA #IMPLIED
    maxAllowedNewClientRequests CDATA #IMPLIED
    disableDefaultStores CDATA #IMPLIED
    serverDN CDATA #IMPLIED
    pingable CDATA #IMPLIED
    refreshTokenEnabled CDATA #IMPLIED
    refreshTokenLifetime CDATA #IMPLIED
    clientSecretLength CDATA #IMPLIED
    debug CDATA #IMPLIED>
<!ELEMENT messages (retryMessage)*>
<!ELEMENT retryMessage (#PCDATA)>
<!ELEMENT myproxy (keystore|
    ssl)>
<!ATTLIST myproxy
    host CDATA #REQUIRED
    port CDATA #REQUIRED
    socketTimeout CDATA #IMPLIED
    serverDN CDATA #IMPLIED>
<!ELEMENT keystore (assetStore)*>
<!ATTLIST keystore
    path CDATA #REQUIRED
    password CDATA #REQUIRED
    type CDATA #REQUIRED
    factory CDATA #REQUIRED
    useJavaKeystore CDATA #IMPLIED>
<!ELEMENT clients>
<!ELEMENT clientApprovals>
<!ELEMENT transactions>
<!ATTLIST clients
    tablename CDATA #IMPLED>
<!ATTLIST clientApprovals
    tablename CDATA #IMPLIED>
<!ATTLIST transactions
    tablename CDATA #IMPLIED>
<!ELEMENT memoryStore (clients|clientApprovals|transactions)*>
<!ELEMENT fileStore (clients|clientApprovals|transactions)*>
<!ATTLIST fileStore
    dataPath CDATA #IMPLIED
    indexPath CDATA #IMPLIED
    path CDATA #IMPLIED>
<!ELEMENT mysql (clients|clientApprovals|transactions)*>
<!ATTLIST mysql
    password CDATA #REQUIRED
    port CDATA #IMPLIED
    host CDATA #IMPLIED
    username CDATA #REQUIRED
    schema CDATA #IMPLIED
    database CDATA #IMPLIED
    tablename CDATA #IMPLIED
    tablePrefix CDATA #IMPLIED
    driver CDATA #IMPLIED>
<!ELEMENT mariadb (clients|clientApprovals|transactions)*>
<!ATTLIST mariadb
    password CDATA #REQUIRED
    port CDATA #IMPLIED
    host CDATA #IMPLIED
    username CDATA #REQUIRED
    schema CDATA #IMPLIED
    database CDATA #IMPLIED
    tablename CDATA #IMPLIED
    tablePrefix CDATA #IMPLIED
    driver CDATA #IMPLIED>
<!ELEMENT postgresql (clients|clientApprovals|transactions)*>
<!ATTLIST postgresql
    username CDATA #REQUIRED
    password CDATA #REQUIRED
    port CDATA #IMPLIED
    schema CDATA #IMPLIED
    database CDATA #IMPLIED
    tablename CDATA #IMPLIED
    tablePrefix CDATA #IMPLIED
    driver CDATA #IMPLIED>
<!ELEMENT ldap(address|port|password|principal|searchBase|searchAttributes|ssl)*
<!ELEMENT ldap (address|port|password|principal|searchBase|searchAttributes|ssl)*>
<!ATTLIST ldap
        enabled CDATA #REQUIRED>
<!ELEMENT address (#PCDATA)>
<!ELEMENT port (#PCDATA)>
<!ELEMENT password (#PCDATA)>
<!ELEMENT principal (#PCDATA)>
<!ELEMENT searchBase (#PCDATA)>
<!ELEMENT searchAttributes (attribute)*>
<!ELEMENT attribute (#PCDATA)>
    <!ELEMENTssl(trustStore|keystore)*
        debug CDATA #IMPLIED
        tlsVersion CDATA #REQUIRED
        useJavaTrustStore CDATA #IMPLIED>
<!ELEMENT trustStore (path|password|type)*>
<!ELEMENT path (#PCDATA)>
<!ELEMENT password (#PCDATA)>
<!ELEMENT type (#PCDATA)>
<!ELEMENT keyStore (path|password|factory|type)*>
<!ELEMENT path (#PCDATA)>
<!ELEMENT password (#PCDATA)>
<!ELEMENT factory (#PCDATA)>
<!ELEMENT type (#PCDATA)>
<!ELEMENT logging
<!ATTLIST logFileName CDATA #REQUIRED
    logName CDATA #IMPLIED
    logSize CDATA #IMPLIED
    logFileCount CDATA #IMPLIED
    debug CDATA #IMPLIED>
<!ELEMENT messageTemplate (#PCDATA)>
<!ELEMENT subjectTemplate (#PCDATA)>
<!ELEMENT authorizationServlet (#PCDATA)>
<!ATTLIST
     useHeader CDATA #IMPLIED
     requireHeader CDATA #IMPLIED
     headerFieldName CDATA #IMPLIED
     returnDNAsUsername CDATA #IMPLIED
     verifyUsername CDATA #IMPLIED
     showLogon CDATA #IMPLIED>
<!ELEMENT mail (messageTemplate|subjectTemplate)*>
<!ATTLIST mail
    enabled CDATA #IMPLIED
    useSSL CDATA #IMPLIED
    starttls CDATA #IMPLIED
    username CDATA #IMPLIED
    password CDATA #IMPLIED
    debug CDATA #IMPLIED
    server CDATA #IMPLIED
    port CDATA #IMPLIED
    recipents CDATA #IMPLIED>
<!ELEMENT JSONWebKey (path)>
<!ATTLIST
    defaultKeyID CDATA #IMPLIED>
<!ELEMENT path (#PCDATA)>
<!ELEMENT scopes(scope)>
<!ELEMENT scope(#PCDATA)>
<!ATTLIST scope
     enabled CDATA #IMPLIED>
]>

A few examples

Example 1. A quick & dirty configuration for debugging/evaluation.

Drop the war from the website into your Tomcat webapps directory, then put this into a file called cfg.xml and drop it into the WEB-INF directory. This will

  • put everything (client entries, approvals, transactions) into a memory store, so there will be no persistence between service restarts,
  • not enable email notifications,
  • Turn on debugging to see everything. This might be quite verbose at times.
  • assume that MyProxy is on localhost at port 7512. The assumption is that it is deployed as "oauth" locally in Tomcat. It will, however, allow for testing the entire lifecycle and allowing for very simple evaluation.
<config>
   service address="http://localhost/oauth"
            debug="true"/>
</config>

This is very simple and easy to get up and running. This does not give a usable configuration though, since there is no way to store or approve clients since they live only in memory. This useful to show that your installation is correct and that the configuration file itself can be found. Note that on redeploys the cfg.xml file might get over-written. See the configuration page for how to specify an alternate location.

Example 2. Stashing everything in a file store.

This will store all items into the local file system and use the specified myproxy server.

<config>
   <service address="https://www.bigstate.edu/oauth/">
        <myproxy host="myproxy.teragrid.org"
                 port="7512"/>
        <fileStore path="/var/www/store">
        <transactions/>
        <clients/>
        <clientApprovals/>
   </fileStore>
   </service>
</config>

Example 3. Enabling email notifications.

Same as example 2, but with email notifications enabled. This will send out a message whenever a new client registers itself so that an approver will know to review to application.

<config>
   <service address="https://www.bigstate.edu/oauth/">
        <myproxy host="myproxy.teragrid.org" port="7514"/>
        <fileStore path="/var/www/store">
        <transactions/>
        <clients/>
        <clientApprovals/>
   </fileStore>
   <mail
        enabled="true"
        useSSL="true"
        username="admin@bigstate.edu"
        password="www"
        server="fnord.foo.baz"
        recipents="approvals@bigstate.edu;admin@bigstate.edu">
       <messageTemplate>/var/www/config/message.txt</messageTemplate>
       <subjectTemplate>/var/www/config/subject.txt</subjectTemplate>
    </mail>
    <logging logFileName="/var/log/tomcat6/oa4mp.xml"
             logName="oa4mp"
             logSize="100000"
             logFileCount="2"
             debug="true/>
      </service>
</config>

This will enable email, use ssl and login in as the given username. Note that there are two recipients in the (comma-separated) list. A message and subject template are specified.

Example 4. Using up a database

In this example, different accounts are required for each component. To keep the size down, no email notifications are enabled here and MyProxy is assumed to be running on localhost.

<config>
  <service name="my-config">
     <mysql host="my.secret.host.org" username="xup-portal" password="bar">
       <transactions/>
     </mysql>
     <mysql username="xup-client" password="bar">
         <clients/>
     </mysql>
     <mysql username="xup-approver" password="bar">
         <clientApprovals/>
     </mysql>
 </service>
</config>

Example 5. Mixed storage.

Several different types of storage are mixed in the next example. This is just to show how it is done.

<config>
  <service name="my fancy configuration"
         version="1.0"
         address="https://research.bigstate.edu/oauth">
      <myproxy host="myproxy.bigstate.edu"
          port="7512"/>
      <mysql username="foo"
          password="bar">
         <clients/>
      </mysql>
      <fileStore  path="/path/to/store">
         <clientApprovals/>
      </fileStore>
      <memoryStore>
         <transactions/>
      </memoryStore>
      <mail enabled="true"
         useSSL="true"
         username="qqq"
         password="www"
         server="fnord.foo.baz"
         port="3321"
         recipents="tom;dick;harry">
         <messageTemplate>/var/www/config/message.txt</messageTemplate>
         <subjectTemplate>/var/www/config/subject.txt</subjectTemplate>
      </mail>
 </service>
</config>

Last modified 11/20/19.
©2000-2013 Board of Trustees of the University of Illinois.