JCas - JCas Configuration Reference

JCas User Guide

        Introduction
        Setup
        First CAS server
        Access Control
        JDBC Database Authorization
        JAAS User Authorization
        SSL Setup
        JSP Taglib
        JCas Client
        JLL - JAAS Login Library

Reference

        Release Notes
        JCas Configuration
        FAQ
        Help Forum

JCas Developers

API Javadocs
CAS Specification

DTD

<!DOCTYPE CAS PUBLIC "-//GPL//DTD//JCAS//1-0" 
                         "http://jcas.sourceforge.net/dtd/jcas_1_0.dtd">
<?xml version="1.0"?>
<!ELEMENT CAS (Server, Instances?, Cookies?, Scheme+)>
<!ELEMENT Server (Bind?, (SSLKeyFile, SSLCertificateFile, SSLKeyPassword)?, 
                  ThreadStart?, ThreadSpareMin?, ThreadSpareMax?, ThreadRequestMax?,
                  RequestTimeout?, Admin?, AllowFrom*, Logfile?)>
<!ELEMENT Bind (Address?, Port?, SSL?)>
<!ELEMENT Address (#PCDATA)>
<!ELEMENT Port (#PCDATA)>
<!ELEMENT SSL ("true"|"false")>
<!ELEMENT SSLKeyFile (#PCDATA)>
<!ELEMENT SSLCertificateFile (#PCDATA)>
<!ELEMENT SSLKeyPassword (#PCDATA)>
<!ELEMENT ThreadStart (#PCDATA)>
<!ELEMENT ThreadSpareMin (#PCDATA)>
<!ELEMENT ThreadSpareMax (#PCDATA)>
<!ELEMENT ThreadRequestMax (#PCDATA)>
<!ELEMENT RequestTimeout (#PCDATA)>
<!ELEMENT Admin (User, Password, AllowFrom*)>
<!ELEMENT User (#PCDATA)>
<!ELEMENT Password (#PCDATA)>
<!ELEMENT AllowFrom (Address*, Subnet*, Agent*)>
<!ELEMENT Subnet (#PCDATA)>
<!ELEMENT Agent (#PCDATA)>
<!ELEMENT Logfile (#PCDATA)>
<!ELEMENT Instances (Instance+)>
<!ELEMENT Instance (Name, Driver, Path, (User, Password)?, RoleSelect?, AdminRole*, DummyTable?)>
<!ELEMENT Name (#PCDATA)>
<!ELEMENT Driver (#PCDATA)>
<!ELEMENT Path (#PCDATA)>
<!ELEMENT RoleSelect (#PCDATA)>
<!ELEMENT AdminRole (#PCDATA)>
<!ELEMENT DummyTable (#PCDATA)>
<!ELEMENT Cookies (File, Timeout?)>
<!ELEMENT File (#PCDATA)>
<!ELEMENT Timeout (#PCDATA)>
<!ELEMENT Scheme (Name, 
                 (InstanceName, (SystemAuthorization | CustomAuthorization), ExtendedAuthorization) |
                 Jaas,
                 AllowFrom?, Cookies?, UseCookies?, Logfile?)>
<!ELEMENT InstanceName (#PCDATA)>
<!ELEMENT SystemAuthorization (RequireRole*)>
<!ELEMENT RequireRole (#PCDATA)>
<!ELEMENT CustomAuthorization (TableName?, UidColumn?, PwdColumn?)>
<!ELEMENT TableName (#PCDATA)>
<!ELEMENT UidColumn (#PCDATA)>
<!ELEMENT PwdColumn (#PCDATA)>
<!ELEMENT ExtendedAuthorization ((PLSQLFunction | Query)+)>
<!ELEMENT PLSQLFunction (Name, ReturnValue*)>
<!ELEMENT Query (Select, ReturnValue*)>
<!ELEMENT ReturnValue (#PCDATA)>
<!ELEMENT Select (#PCDATA)>
<!ELEMENT Jaas (#PCDATA)>
<!ELEMENT UseCookies ("true"|"false")>

`<Address>`

DTD Element Definition:	`<!ELEMENT Address (#PCDATA)>`
Attributes:	None.
Context:	`<Bind> <AllowFrom>`
Child elements:	Character data
Description:	Describes hostnames or IP addresses. Within `<Bind>`: Defines IP adapter to bind listener socket at. Within `<AllowFrom>`: Defines hostnames or IP addresses that are allowed in context. Wildcard * can be used.

`<Admin>`

DTD Element Definition:	`<!ELEMENT Admin (User, Password, AllowFrom*)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	`<User> <Password> <AllowFrom>`
Description:	Defines an administrator that can issue CAS Admin Requests for JCas server.

`<AdminRole>`

DTD Element Definition:	`<!ELEMENT AdminRole (#PCDATA)>`
Attributes:	None.
Context:	`<Instance>`
Child elements:	Character data
Description:	Defines the user role that has admin privileges on a database instance, usually `DBA`.

`<Agent>`

DTD Element Definition:	`<!ELEMENT Agent (#PCDATA)>`
Attributes:	None.
Context:	`<AllowFrom>`
Child elements:	Character data
Description:	Defines eligible client agents that are allowed within the context. Placeholder * can be used.

`<AllowFrom>`

DTD Element Definition:	`<!ELEMENT AllowFrom (Address, Subnet, Agent*)>`
Attributes:	None.
Context:	`<Server> <Admin> <Scheme>`
Child elements:	`<Address> <Subnet> <Agent>`
Description:	Describes clients that are allowed to connect and issue requests within the given context.

`<Bind>`

DTD Element Definition:	`<!ELEMENT Bind (Address?, Port?, SSL?)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	`<Address> <Port> <SSL>`
Description:	Defines properties of the TCP/IP listener that JCas creates for the service.

`<CAS>`

DTD Element Definition:	`<!ELEMENT CAS (Server, Instances?, Cookies?, Scheme+)>`
Attributes:	None.
Context:	None.
Child elements:	`<Cookies> <Instances> <Server> <Scheme>`
Description:	Root tag of the configuration. It contains all relevant information to run a JCas instance.

`<Cookies>`

DTD Element Definition:	`<!ELEMENT Cookies (File, Timeout?)>`
Attributes:	None.
Context:	`<CAS> <Scheme>`
Child elements:	`<File> <Timeout>`
Description:	Defines a specific cookie managment system. Cookies usually are organized in a global, default pool. Scheme specific cookie pools can be created and configured using this tag. In a `<CAS>` context, it configures the global pool.

`<CustomAuthorization>`

DTD Element Definition:	`<!ELEMENT CustomAuthorization (TableName?, UidColumn?, PwdColumn?)>`
Attributes:	None.
Context:	`<Scheme>`
Child elements:	`<PwdColumn> <TableName> <UidColumn>`
Description:	Defines usage of Custom Authorization mechanism. Configuration about behaviour of the mechanism are configured inside the tag. Please note that System Authorization cannot be used when using this mechanism.

`<Driver>`

DTD Element Definition:	`<!ELEMENT Driver (#PCDATA)>`
Attributes:	None.
Context:	`<Instance>`
Child elements:	Character data
Description:	Defines the JDBC driver class that will be used for a database instance.

`<DummyTable>`

DTD Element Definition:	`<!ELEMENT DummyTable (#PCDATA)>`
Attributes:	None.
Context:	`<Instance>`
Child elements:	Character data
Description:	Defines the name of a database table within the specific instance that contains a single row. The table will be used for Extended Authorization and provides a way to call user-defined functions.

`<ExtendedAuthorization>`

DTD Element Definition:	`<!ELEMENT ExtendedAuthorization ((PLSQLFunction \| Query)+)>`
Attributes:	None.
Context:	`<Scheme>`
Child elements:	`<PLSQLFunction> <Query>`
Description:	Defines usage of addtional, Extended Authorization. If this tag is present, additional authorization will be performed after System or Customized Authorization succeeded.

`<File>`

DTD Element Definition:	`<!ELEMENT File (#PCDATA)>`
Attributes:	None.
Context:	`<Cookies>`
Child elements:	Character data
Description:	Defines a file that can be used to store cookies. Cookies are usually held in memory and do not survive a server restart. By using this tag, cookies are permanently stored and will be valid after JCas was restarted.

`<Instance>`

DTD Element Definition:	`<!ELEMENT Instance (Name, Driver, Path, (User, Password)?, RoleSelect?, AdminRole*, DummyTable?)>`
Attributes:	None.
Context:	`<Instances>`
Child elements:	`<AdminRole> <Driver> <DummyTable> <Name> <Path> <Password> <RoleSelect> <User>`
Description:	Defines a JDBC database instance. Here, properties of single database instance are configured. Instances are later referenced by its name within the `<Scheme>` definition.

`<InstanceName>`

DTD Element Definition:	`<!ELEMENT InstanceName (#PCDATA)>`
Attributes:	None.
Context:	`<Scheme>`
Child elements:	Character data
Description:	References the name of a database instance to be used for JDBC authorization. The tag must be present if such authorization is being used.

`<Instances>`

DTD Element Definition:	`<!ELEMENT Instances (Instance+)>`
Attributes:	None.
Context:	`<CAS>`
Child elements:	`<Instance>`
Description:	Holds definitions of all JDBC database instances.

`<Jaas>`

DTD Element Definition:	`<!ELEMENT Jaas (#PCDATA)>`
Attributes:	None.
Context:	`<Scheme>`
Child elements:	Character data
Description:	Defines the JAAS context name to be used to authenticate and authorize users that request the scheme.

`<Logfile>`

DTD Element Definition:	`<!ELEMENT Logfile (#PCDATA)>`
Attributes:	None.
Context:	`<Server> <Scheme>`
Child elements:	Character data
Description:	Defines the logfile for requests of that specific context.

`<Name>`

DTD Element Definition:	`<!ELEMENT Name (#PCDATA)>`
Attributes:	None.
Context:	`<Instance> <PLSQLFunction> <Scheme>`
Child elements:	Character data
Description:	Defines the name of the context.

`<Password>`

DTD Element Definition:	`<!ELEMENT Password (#PCDATA)>`
Attributes:	None.
Context:	`<Admin> <Instance>`
Child elements:	Character data
Description:	Defines the password of an administrator or database login.

`<Path>`

DTD Element Definition:	`<!ELEMENT Path (#PCDATA)>`
Attributes:	None.
Context:	`<Instance>`
Child elements:	Character data
Description:	Defines the URL for a JDBC database instance.

`<PLSQLFunction>`

DTD Element Definition:	`<!ELEMENT PLSQLFunction (Name, ReturnValue*)>`
Attributes:	None.
Context:	`<ExtendedAuthorization>`
Child elements:	`<Name> <ReturnValue>`
Description:	Performs a extended authorization with a user-defined function. The tag defines properties of this authorization.

`<Port>`

DTD Element Definition:	`<!ELEMENT Port (#PCDATA)>`
Attributes:	None.
Context:	`<Bind>`
Child elements:	Character data
Description:	Defines the port for the TCP/IP listener. If not present, port 6688 will be used.

`<PwdColumn>`

DTD Element Definition:	`<!ELEMENT PwdColumn (#PCDATA)>`
Attributes:	None.
Context:	`<CustomAuthorization>`
Child elements:	Character data
Description:	Defines the name of the table column that contains user passwords for Customized Authorization. If not present, `PWD` will be used.

`<Query>`

DTD Element Definition:	`<!ELEMENT Query (Select, ReturnValue*)>`
Attributes:	None.
Context:	`<ExtendedAuthorization>`
Child elements:	Character data
Description:	Performs extended authorization by executing a defined SQL query on the JDBC database instance. The tag further specifies the query.

`<RequestTimeout>`

DTD Element Definition:	`<!ELEMENT RequestTimeout (#PCDATA)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	Character data
Description:	Maximum duration of a single request. If a request takes more time than specified, it will be aborted. Default is 5.

`<RequireRole>`

DTD Element Definition:	`<!ELEMENT RequireRole (#PCDATA)>`
Attributes:	None.
Context:	`<SystemAuthorization>`
Child elements:	Character data
Description:	Performs an additional user role check after authentication was done. The tag contains the name of a user role that authenticated users must have been granted.

`<ReturnValue>`

DTD Element Definition:	`<!ELEMENT ReturnValue (#PCDATA)>`
Attributes:	None.
Context:	`<PLSQLFunction> <Query>`
Child elements:	Character data
Description:	Overwrites the default set of accepted return values for Extended Authorization. Only accepted values will lead to successful authorization of a specific user.

`<RoleSelect>`

DTD Element Definition:	`<!ELEMENT RoleSelect (#PCDATA)>`
Attributes:	None.
Context:	`<Instance>`
Child elements:	Character data
Description:	Defines the query that returns all user roles a logged-in user has been granted on a JDBC database instance. This tag must be present if System Authorization will be performed.

`<Scheme>`

DTD Element Definition:	`<!ELEMENT Scheme (Name, (InstanceName, (SystemAuthorization \| CustomAuthorization), ExtendedAuthorization) \| Jaas, AllowFrom?, Cookies?, UseCookies?, Logfile?)>`
Attributes:	None.
Context:	`<CAS>`
Child elements:	`<AllowFrom> <Cookies> <CustomAuthorization> <ExtendedAuthorization> <InstanceName> <Jaas> <Logfile> <Name> <SystemAuthorization> <UseCookies>`
Description:	Defines a scheme and its properties for authorization.

`<Select>`

DTD Element Definition:	`<!ELEMENT Select (#PCDATA)>`
Attributes:	None.
Context:	`<Query>`
Child elements:	Character data
Description:	Defines the SQL query for Extended Authorization. Placeholders for user ($uid$), password ($pwd$) and scheme ($scheme$) can be used within the query.

`<Server>`

DTD Element Definition:	`<!ELEMENT Server (Bind?, (SSLKeyFile, SSLCertificateFile, SSLKeyPassword)?, ThreadStart?, ThreadSpareMin?, ThreadSpareMax?, ThreadRequestMax?, RequestTimeout?, Admin?, AllowFrom*, Logfile?)>`
Attributes:	None.
Context:	`<CAS>`
Child elements:	`<Admin> <AllowFrom> <Bind> <Logfile> <RequestTimeout> <SSLCertificateFile> <SSLKeyFile> <SSLKeyPassword> <ThreadRequestMax> <ThreadSpareMax> <ThreadSpareMin> <ThreadStart>`
Description:	Defines all global, server specific properties for JCas.

`<SSL>`

DTD Element Definition:	`<!ELEMENT SSL ("true"\|"false")>`
Attributes:	None.
Context:	`<Bind>`
Child elements:	Character data ("true" \| "false")
Description:	Defines whether SSL will be used for encryption on TCP/IP listener socket.

`<SSLCertificateFile>`

DTD Element Definition:	`<!ELEMENT SSLCertificateFile (#PCDATA)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	Character data
Description:	Defines a file that contains a X.509 encoded server certificate presented to clients when using SSL encryption. The file must be DER formatted. See SSL Setup for detailed information.

`<SSLKeyFile>`

DTD Element Definition:	`<!ELEMENT SSLKeyFile (#PCDATA)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	Character data
Description:	Defines a file that contains the PKCS#8 encoded private key for the SSL server certificate. The file must be DER formatted. See SSL Setup for detailed information.

`<SSLKeyPassword>`

DTD Element Definition:	`<!ELEMENT SSLKeyPassword (#PCDATA)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	Character data
Description:	Defines how password of private key can be retrieved. The value's syntax is: `method:value`. where `method` can be: `exec`, `pass` or `file`. `exec` orders JCas to execute the program given as `value` and retrieve the password from its standard output. `pass` directly gives the password as `value`, `file` reads the password from the file given as `value`.

`<Subnet>`

DTD Element Definition:	`<!ELEMENT Subnet (#PCDATA)>`
Attributes:	None.
Context:	`<AllowFrom>`
Child elements:	Character data
Description:	Defines a subnet that is accepted. Only clients from accepted subnets are permitted to issue requests within the given context.

`<SystemAuthorization>`

DTD Element Definition:	`<!ELEMENT SystemAuthorization (RequireRole*)>`
Attributes:	None.
Context:	`<Scheme>`
Child elements:	`<RequireRole>`
Description:	Performs System Authorization for users requesting the scheme. The tag can further specify properties for the authorization. If present, Customized Authorization cannot be used.

`<TableName>`

DTD Element Definition:	`<!ELEMENT TableName (#PCDATA)>`
Attributes:	None.
Context:	`<CustomAuthorization>`
Child elements:	Character data
Description:	Defines name of a table the contains all users and their passwords for Customized Authorization. Default value is `JCAS_USER_TABLE`.

`<ThreadRequestMax>`

DTD Element Definition:	`<!ELEMENT ThreadRequestMax (#PCDATA)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	Character data
Description:	Defines number of requests that a single thread will handle before it is destroyed. Default is 10,000. 0 means unlimited.

`<ThreadSpareMax>`

DTD Element Definition:	`<!ELEMENT ThreadSpareMax (#PCDATA)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	Character data
Description:	Defines the number of idle threads that JCas will have in spare at most. If more than the given number of threads are idle, JCas will destroy the additional threads to free up memory. Default is 5.

`<ThreadSpareMin>`

DTD Element Definition:	`<!ELEMENT ThreadSpareMin (#PCDATA)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	Character data
Description:	Defines the number of idle threads that JCas will have in space at least. JCas will create additional threads if the given number is larger then the current number of idle threads. Default is 5.

`<ThreadStart>`

DTD Element Definition:	`<!ELEMENT ThreadStart (#PCDATA)>`
Attributes:	None.
Context:	`<Server>`
Child elements:	Character data
Description:	Number of threads that JCas will create at startup. Default is 5.

`<Timeout>`

DTD Element Definition:	`<!ELEMENT Timeout (#PCDATA)>`
Attributes:	None.
Context:	`<Cookies>`
Child elements:	Character data
Description:	Time in seconds an unused cookie remains valid.

`<UidColumn>`

DTD Element Definition:	`<!ELEMENT UidColumn (#PCDATA)>`
Attributes:	None.
Context:	`<CustomAuthorization>`
Child elements:	Character data
Description:	Defines name of the column in a database table that contains the usernames for Customized Authorization. Default is `UID`.

`<UseCookies>`

DTD Element Definition:	`<!ELEMENT UseCookies ("true"\|"false")>`
Attributes:	None.
Context:	`<Scheme>`
Child elements:	Character data ("true" \| "false")
Description:	Defines whether cookies are enebaled for the specific scheme. Default is `true`.

`<User>`

DTD Element Definition:	`<!ELEMENT User (#PCDATA)>`
Attributes:	None.
Context:	`<Admin> <Instance>`
Child elements:	Character data
Description:	Name of a JDBC database instance login.