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 |
| notifyACEmailAddresses | N | false | A semi-colon separated list of email addresses where notifications from the client management servlet are sent on actions. Note that are only sent if the admin client has been enabled to do so. |
| address | N | N/A | The address associated with this service. Normally this is not needed unless either there is some aliasing used by the host or safe garbage collection is needed. Otherwise 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. |
| accessTokenLifetime | N | 900 | Deprecated. Use defaultAccessTokenLifetime instead. |
| authorizationGrantLifetime | N | 900 | "OAuth 2 specific. This will set the lifetime of authorization grants, in seconds, issued by the server. The default is 900 seconds = 15 minutes. As long as the grant has not expired, the second leg of the exchange (getting an access token) can be done. If there is too long a gap between authentication and getting an access token, it will fail. Generally the default is quite reasonable. See note on units. |
| cleanupInterval | N | 20 minutes | How often should the cleanup thread run (in seconds). To disable cleanup completely, set this ≤ 0 and do not set alarms. |
| cleanupAlarms | N | N/A | Comma delimited list of times of the form hh:mm:ss.
Times are on a 24 hour clock and fractions of seconds are ignored.
Cleanups will happen daily at these times.
Note that alarms have right of way in that if you define alarms
and a cleanupInterval, the alarms will be done. If you do not want alarms,
omit this entry. E.g. cleanupAlarms="06:00:00, 18:30:00" Would have garbage collection run daily at 6:00 am and 6:30 pm. |
| cleanupFailOnErrors | N | true | If cleanup threads should continue processing if there is an error. A typical casse is that there are munged or otherwise unparseable files in a transaction file store (e.g. someone copied a non-transaction to the directory). If cleaup stops when it hits a bad file, then no more cleanup will happen and stale file store entries will accumulate. If it's an active server, this may happen quite quickly. In other contexts, such as a database store, a failure often means that the database itself is unreachable and attempting further processing is a waste of resources. Note that a list of failures is written to the log if debugging is enabled. |
| cleanupLockingEnabled | N | false | Enabled locking the stores during cleanup. This is useful if the store is shared among OA4MP instances (e.g. there are several behind a load balancer that share the same database). If you do not have multiple concurrent instances of OA4MP running, you do not need to enable this feature. |
| 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. The default is 64 bytes = 512 bits. |
| 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 increasing 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. |
| defaultAccessTokenLifetime | N | 900 sec | specific. This will set the lifetime of access tokens issued by the server. The default is 900 seconds = 15 minutes. Note that generally access tokens should have much shorter lifetime than refresh tokens. The reason is that access tokens allow access to a resource and refresh tokens let a client get access tokens. Best practices is that an access token is gotten for a specific task and should be therefore short lived. Clients may set this to -1 which means to use this value. Clients may request different lifetimes, but are limited to the maximum value as set below. See note on units. |
| defaultIDTokenLifetime | N | 900 sec | specific. This will set the lifetime of id tokens issued by the server. The default is 900 seconds = 15 minutes. Clients may request different lifetimes, but are limited to the maximum value as st below. See note on units. Clients may set this to -1 which means to use this value. |
| defaultRefreshTokenLifetime | N | 1296000 sec | specific. This will set the lifetime of refresh tokens issued by the server. The default is 129600 seconds = 15 days. Clients may request different lifetimes, but are limited to the maximum value as set below. See note on units. Clients may also set their value to 0 (zero) which disabled refresh tokens or -1 which means to use this value. |
| demoModeEnabled | N | false | Enable demo mode. This just shuts off authorization and is intended that an administrator can quickly set up OA4MP to evaluate it. See using demo mode. |
| disableDefaultStores | N | true | Allow the server to use memory stores 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. The default is true precisely to force you to explicitly enable this, since otherwise a store misconfiguration might be a silent error and everything (such as client registrations, approvals, etc.) might end up in memory where they would vanish at service restart. |
| enableDeviceFlow | N | false | Boolean value. If true, the support for the device authorization flow as per RFC 8628 is enabled with defaults. Alternately there is a device flow servlet configuration that will be used. |
| enableTokenExchange | N | true | Boolean value. If true, the support for exchanging tokens as per RFC 8693 is enabled. |
| 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. |
| maxAccessTokenLifetime | N | 1800 | This is the largest access token lifetime, in seconds, that the server will permit, regardless of what is requested. Contrast this with the defaultAccessTokenLifetime property which is used if clients specify nothing. The default is 30 minutes or 1800 seconds. See note on units. |
| 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. |
| maxAuthorizationGrantLifetime | N | 1800 | This is the largest authorization grant lifetime, in seconds, that the server will permit, regardless of what is requested. Note that there is no way for clients to request this except as part of a device flow. Contrast this with the defaultAuthorizationGrantLifetime property which is used if clients specify nothing. The default is 30 minutes or 1800 seconds. See note on unitss. |
| maxIDTokenLifetime | N | maxAccessTokenLifetime | This is the largest ID token lifetime, in seconds, that the server will permit, regardless of what is requested. Contrast this with the defaultIDTokenLifetime property which is used if clients specify nothing. The default is the same as for access tokens since that most often conforms to use patterns. See note on units. |
| maxClientRefreshTokenLifetime | N | 2592000 | "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. Note that in practice this should never exceed the server default maximum, because the server default is always enforced. See note below on units. |
| maxRefreshTokenLifetime | N | 2592000 | This is the largest refresh token lifetime in seconds that the server will permit, regardless of what is requested. Default is 30 days or 2592000 seconds. See note on units. |
| monitorEnable | N | false | Enable monitoring of access to clients, admin clients, virtual organizations and (in CILogon) users. This will start a thread that will update the objects either at intervals (monitorInterval) or at given set times (monitorAlarms). The reason for this is that very high traffic servers should not hammer storage for every access. What this feature does is buffer the accesses and make a single update per object. |
| monitorInterval | N | 2 hours | How often should the monitor thread run. |
| monitorAlarms | N | N/A | Comma delimited list of times of the form hh:mm:ss.
Times are on a 24 hour clock and fractions of seconds are ignored.
Monitoring will happen daily at these times.
Note that alarms have right of way in that if you define alarms
and a monitorInterval, the alarms will be done. If you do not want alarms,
omit this entry. E.g. monitorAlarms="06:00:00, 18:30:00" Would have updates run daily at 6:00 am and 6:30 pm. |
| name | N | (none) | An arbitrary name for this configuration. Multiple configurations in a file are supported. |
| 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. |
| 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. |
| 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. |
| 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. |
| printTSInDebug | N | true | OAuth 2 If true, this tells the server to print all debug message with a leading timestamp. Some systems have multiple layers of logging and disabling this is needed. Note: on CILogon server deploys this is set to false automatically. |
| qdlConfigName | N | qdl-default | OAuth 2If there is are multiple qdl configurations, this allows to specify the active one. If this is omitted, the assumption is that the default is named qdl-default, however, if there is only one QDL configuration, then that is used regardless of this setting. |
| 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. |
| refreshTokenLifetime | N | 1296000 | deprecated. Use maxRefreshTokenLifetime instead. |
| rfc7636Required | N | false | Set to true if you want to require all public clients to use code challenges as per RFC 7636. Note that OA4MP will allow any client to send along a challenge. If this flag is set to true though, public clients will be required to use it or will be denied access. |
| rtGracePeriod | N | -1 | For 0 ≤ values, this sets the lifetime in seconds of the refresh token on
refresh.
If the value is 0, this invalidates the token immediately. A value of -1 means to simply let
the tokens age with their current lifetimes. Each client may have this set as well which will
override the server setting. The client default is to use whatever the server has configured. See note on units. |
| safe_gc | N | true | Enable safe garbage collection in the various clean up threads. This means that the server will not remove any token unless it is from the current service address. This allows deploying OA4MP to environments with a shared database and possibly many other OA4MP services. Be sure to set the service address (the address attribute described in this table. |
| 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 "". |
| 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. |
| version | N | latest | The version of the configuration file. If omitted, the most current is used. |
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.
<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.
<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/....