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|
      apache derby|
      fileStore|memoryStore|
      mail|
      scopes|
      messages|
      logging|
      clientManagement|
      authorizationServlet|
      deviceFlowServlet|
      QDL|
      
      JSONWebKey
    )*>
<!ATTLIST service
    address CDATA #IMPLIED
    accessTokenLifetime
    authorizationGrantLifetime
    clientSecretLength CDATA #IMPLIED
    debug CDATA #IMPLIED
    defaultAccessTokenLifetime CDATA #IMPLIED
    defaultRefreshTokenLifetime CDATA #IMPLIED
    defaultIDTokenLifetime CDATA #IMPLIED
    disableDefaultStores CDATA #IMPLIED
    enableDeviceFlow CDATA #IMPLIED
    enableMontor CDATA #IMPLIED
    enableMontor CDATA #IMPLIED
    enableMontor CDATA #IMPLIED
    enableTokenExchange CDATA #IMPLIED
    enableTwoFactorSupport CDATA #IMPLIED
    issuer CDATA #IMPLIED
    maxAuthorizationGrantLifetime CDATA #IMPLIED
    maxAccessTokenLifetime CDATA #IMPLIED
    maxAllowedNewClientRequests CDATA #IMPLIED
    maxClientRefreshTokenLifetime CDATA #IMPLIED
    maxIDTokenLifetime CDATA #IMPLIED
    maxRefreshTokenLifetime CDATA #IMPLIED
    name CDATA #IMPLIED
    OIDCEnabled CDATA #IMPLIED
    pingable CDATA #IMPLIED
    rfc7636Required CDATA #IMPLIED
    pollingDirectory CDATA #IMPLIED
    pollingInterval CDATA #IMPLIED
    cleanupInterval CDATA #IMPLIED
    cleanupAlarms CDATA #IMPLIED
    refreshTokenEnabled CDATA #IMPLIED
    refreshTokenLifetime CDATA #IMPLIED
    safe_gc CDATA #IMPLIED
    scheme CDATA #IMPLIED
    schemeSpecificPart CDATA #IMPLIED
    serverDN CDATA #IMPLIED
    version 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>
<!ELEMENT permissions>
<!ELEMENT adminClients>
<!ELEMENT txStore>
<!ELEMENT voStore>
<!ATTLIST clients
    tablename CDATA #IMPLED>
<!ATTLIST clientApprovals
    tablename CDATA #IMPLIED>
<!ATTLIST transactions
    tablename CDATA #IMPLIED>
  <!ATTLIST permissions
      tablename CDATA #IMPLED>
  <!ATTLIST adminClients
      tablename #IMPLED>
  <!ATTLIST txStore
       tablename CDATA #IMPLED>
  <!ATTLIST voStore
      tablename CDATA #IMPLED>

<!ELEMENT memoryStore (clients|clientApprovals|transactions|permissions|adminClients|txStore|voStore)*>
    <!ELEMENT fileStore (clients|clientApprovals|transactions|permissions|adminClients|txStore|voStore)*>
<!ATTLIST fileStore
    dataPath CDATA #IMPLIED
    indexPath CDATA #IMPLIED
    path CDATA #IMPLIED>
<!ELEMENT mysql (clients|clientApprovals|transactions|permissions|adminClients|txStore|voStore)*>
<!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 derby (clients|clientApprovals|transactions|permissions|adminClients|txStore|voStore)*>
    <!ATTLIST derby
        password CDATA #REQUIRED
        username CDATA #REQUIRED
        bootPassword CDATA #REQIRED
        database CDATA #REQUIRED
        schema CDATA #IMPLIED>
<!ELEMENT mariadb (clients|clientApprovals|transactions|permissions|adminClients|txStore|voStore)*>
<!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|permissions|adminClients|txStore|voStore)*>
<!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 deviceFlowServlet (#PCDATA)>
<!ATTLIST
     verificationURI CDATA #IMPLIED
     interval CDATA #IMPLIED
     codeChars CDATA #IMPLIED
     codeLength CDATA #IMPLIED
     codeSeparator CDATA #IMPLIED
     codePeriodLength CDATA #IMPLIED>
<!ELEMENT clientManagement (api)*>
<!ATTLIST
     enabled CDATA #IMPLIED>
<!ELEMENT api (#PCDATA)>
<!ATTLIST
     enabled CDATA #IMPLIED
     protocol CDATA #REQUIRED
     endpoint CDATA #IMPLIED
     url CDATA #IMPLIED
     anonymousOK CDATA #IMPLIED
     template CDATA #IMPLIED
     autoApprove CDATA #IMPLIED
     autoApproverName 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)*>
<!ATTLIST scopes
    handler CDATA #IMPLIED>
<!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>