The Service Tag.

This is the top-level tag for a server configuration. There may be several of these in a single configuration file, all given different names.

Attribute Required? Default Description
name N (none) An arbitrary name for this configuration. Multiple configurations in a file are supported.
version N latest The version of the configuration file. If omitted, the most current is used.
address N N/A The address associated with this service. Normally this is not needed unless there is some aliasing used by the host.The host name is taken from the servlet itself and used in constructing urls that point to this server. For instance, if there is a server farm with a given external-facing address which will be resolved to one of the members based on load-balancing, this would be the external-facing address.
pollingDirectory N N/A This enables polling for client approvals. The meaning of this is that if there is a command line interface (CLI) which approves a client, a specific file is written to this directory which will be read at intervals by the server, telling it that a new approval has been written. This is because once a client configuration is loaded, it stays in memory. To disable this feature, do not set this. Note that the CLI should use the same configuration as the server.
OIDCEnabled N true OAuth 2 This toggles OIDC support for the service. If true, then required claims (such as sibject) will be checked for and ID tokens will be generated. Also, any request that does not contain the scope of openid will be rejected. Note that if false, the service is OAuth 2.0 compliant, but not OIDC compliant.
pollingInterval N N/A How frequently the polling directory will be accessed for new approvals. Note that this is ignored if polling is not enabled.
debug N "warn" Enable debugging for this service. This will be written to the Tomcat logs and might be rather verbose. Use it only if you need it. The levels supported are (in order of increasin verbosity) "off", "info", "warn", "error", "severe", "trace". Setting debug to "trace" will dump out virtually everything and give a running account of the operation of the service. This may be very, very large.
maxAllowedNewClientRequests N unlimited In the registration client, this is the maximum number of pending client requests that the server will permit. Requests received after this limit is met will be rejected. This is to prevent denial of service attacks for thousands of client requests. Since such requests are normally not too frequent, this number can realistically be set low to 10 or 20 with no issue on a production system.
refreshTokenLifetime N 1296000 OAuth 2 specific. This will set a global maximum on the server, in seconds, for how long a refresh token can remain active from issuance. The default is 15 days.
maxClientRefreshTokenLifetime N 33696000 "OAuth 2 specific. This will set a global maximum on the server, in seconds, for refresh tokens a client may request at registration. The default is 13 months.
refreshTokenEnabled N false OAuth 2 specific. This tells the server to issue refresh tokens. Setting this false means the server will not issue them, nor will clients be allowed to specify them at registration. Setting the value for the refreshTokenLifetime in the configuration will be ignored if the server does not issue refresh tokens.
clientSecretLength N 64 OAuth 2 specific. The server generates client secrets of this length in bytes, then displays them to the client in Base64 encoding, which should be returned verbatim to the server. Note that the returned secret is URL safe encoded as well.
serverDN N (none) A server DN applied to all MyProxy servers. This may also be applied individually in the MyProxy element. Note especially that this only applies to MyProxy servers and must be a valid Distinguished Name. Also, setting this in the tag for a myproxy server over-rides the global setting.
disableDefaultStores N false The default server behavior is to default to using a memory store if no other store is explicitly set. If set to true, this will make the server throw an exception if there is no store configured.
pingable N true Boolean value. If true, then contacting a server endpoint (HTTP GET) with an argument of "ping" will result in a response with HTTP return code of 204. If false, then an 500 exception will be thrown on the server.
enableTwoFactorSupport N false Boolean value. If true, the support for two factor authentication is enabled.
issuer N (none) OAuth 2 specific. The global default for the issuer. That is to say, this will be returned in the claims to the client. Note that this may be overridden by an administrative client or the client itself.
scheme N myproxy This sets the scheme for all identifiers (such as client ids) that are created by the system. The format of an identifier is
scheme:specificPart:...
the default (as of version 4.0 still) is myproxy:oa4mp,2012:... After this is a hierarchical name for the component.
schemeSpecificPart N oa4mp,2012 This sets the scheme specific part for the identifiers. Note that if this is omitted then the default is used. If you wish to suppress this, set it equal to "".

The name can be anything. The name of the configuration to use may be specified in the deployment descriptor (web.xml) file. If there is a single configuration in the file, that will be used. If there are multiple configurations and no name is specified, an exception is raised.

A Note on using Two Factor Authentication

Due to the way Two Factor works, this effectively allows you to get only a single certificate once. Because Two Factor generates a one time password that is very short lived (typically only a minute or perhaps 2 at the most), it is possible to wait too long before logging in (done when getting the cert) and have this fail. Also, as stated elsewhere and worth repeating that ever so often, Two Factor offers a challenge that requires you to log on to the RSA self-service console (For the NCSA, this is located at otp) and then exchange the next token. This is impossible to do within the delegation service, so if Two Factor requires this, get certs will fail with an "invalid password" message until further notice.

Example 1.

<config>
   <service address="http://localhost/oauth">
      <!-- more stuff -->
   </service>
</config>

Specifies that the service is located on localhost. There is a single configuration and every default will be used, including looking for a local MyProxy instance.

Example 2.

<config>
   <service address="https://chem.bigstate.edu/organic/oauth"
       name="organic"
       clientSecretLength="300"
       maxAllowedNewClientRequests="25"
       scheme="cern"
       schemeSpecificPart="">
       <!-- more stuff -->
   </service>
   <service address="https://chem.bigstate.edu/polymer/oauth" name="polymer">
       <!-- more stuff -->
   </service>
</config>

This specifies that there are two delegation services on the given machine and that both configurations reside in this file, or there are two possible configurations available for a single server. Note that in the first one, the number of new client registration is limited to 25 unappproved ones and the client secret is 300 bytes which translates into 400 characters when Base64 encoded. Also, there is some network address translation going on, so that the address tag is explicitly given.

This also specifies that the client identifiers are of the form

cern:/client_id/...

where the scheme has been set to "cern" but the scheme specific part (SPP) is to be omitted. Note that if the SPP were omitted, then the default would be used and the resulting id would be

cern:oa4mp,2012:/client_id/....

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