Overview
Database Authorization is the main reason why JCas and its related projects
exist. This article describes the various features that are available with
JCas to authenticate and authorize users against databases.
JCas provides two mechanisms:
Both mechanisms can be enhanced by Extended
Authorization. The following sections will discuss all features of the
JDBC mechanisms in JCas.
Regardless what kind of mechanism is used, configuration is made in
two steps:
- Definition of database instances
- Definition of JDBC schemes
Definition of database instances
JCas separates scheme and instance definition due to fact that multiple
schemes might use the same database instance. By separating these
two parts, configuration is made easier.
Instances are defined in one single Instances block, each of it
being defined in a single Instance tag inside:
...
<Instances>
<Instance>
<!-- 1st instance definition -->
<Name>INSTANCE1</Name>
</Instance>
<Instance>
<!-- 2nd instance definition -->
<Name>INSTANCE2</Name>
</Instance>
<Instance>
<!-- 3rd instance definition -->
<Name>INSTANCE3</Name>
</Instance>
</Instances>
...
Each instance defines the JDBC driver it is using and the JDBC resource
path to be used. Additional definitions must be made depending on the
type of authorization mechanism being used. Instance name, driver and
path are defined as follows:
...
<Instances>
<Instance>
<!-- instance definition -->
<Name>INSTANCE1</Name>
<Driver>oracle.jdbc.driver.OracleDriver</Driver>
<Path>jdbc:oracle:thin:$uid$/$pwd$@localhost:1521:ralph</Path>
</Instance>
</Instances>
...
Instance names are logical names of database instances that do not necessarily
match the instance names within the database system. Merely, they are
JCas-internal identifiers for later use in scheme definitions (see below).
Driver is the Java class name of the JDBC driver that is able to access
the database. Please notice that the driver must be accessible by the JVM
via CLASSPATH.
Path usually corresponds somehow to the driver since
it is defined by the JDBC implementation. Please refer to your driver's
documentation. Path definitions can contain variables for username
($uid$) and password ($pwd$) to be replaced by actual
values when JCas is connecting to the database.
For information about additional definitions to be made when using a specific
authorization mechanism, please refer to the following sections.
Definition of JDBC schemes
JDBC schemes must contain links to the appropriate database instances that
are being used. Additionally they must contain a special definition for
the appropriate authorization mechanism (see sections below).
...
<Instances>
<Instance>
<!-- instance definition -->
<Name>MY_INSTANCE</Name>
<Driver>oracle.jdbc.driver.OracleDriver</Driver>
<Path>jdbc:oracle:thin:$uid$/$pwd$@localhost:1521:ralph</Path>
...
</Instance>
...
<Scheme>
<Name>MY_SCHEME</Name>
<Instance>MY_INSTANCE</Instance>
...
</Scheme>
Next sections will discuss the special configuration definitions that
need to be added to the tags introduced when using special authorization
schemes.
System Authorization
System Authorization mechanism makes use of the native authorization
features a database system provides. JCas will try to connect to
a specified database instance using username and password provided by
a CAS client. If the database refuses the connection, JCas will return
an error code indicating a failed login.
System Authorization is used for a specific scheme if a
<SystemAuthorization> tag is present within the
<Scheme> tag:
...
<Scheme>
...
<SystemAuthorization>
...
</SystemAuthorization>
...
</Scheme>
...
JCas needs three configuration information to successfully authorize
users using System Authorization mechanism:
- SELECT statement to retrieve active user roles from database
- Name of Administrator role
- Name of active user role required (optional)
SELECT statement to retrieve active user roles from database
This information is required to enable JCas to query information about
active roles of the user to be authorized. A SELECT statement must be
given and it should return all of the active roles.
Examples:
Oracle Databases: SELECT ROLE FROM SESSION_ROLES
TODO: other databases
The statements are given in the <RoleSelect> tag within
the <Instance> definition:
...
<Instance>
...
<RoleSelect>SELECT ROLE FROM SESSION_ROLES</RoleSelect>
...
</Instance>
...
Name of Administrator role
Database Administrators (DBA) are authorized automatically. JCas will
need the specific user role of the database instance. Usually, they are
named DBA. The role is given in the <AdminRole>
tag within the <Instance> definition:
...
<Instance>
...
<AdminRole>DBA</AdminRole>
...
</Instance>
...
Name of active user role required
After JCas successfully authenticated a user against a JDBC source, it
provides an optional check of a specific active user role. If the scheme
definition contains such a role, the server will check if the role
of the specific user is active and authorize her based on this information.
If the role is missing then JCas will return an error indicating failed
authorization.
Required user roles are defined in the
<SystemAuthorization> tag within a scheme definition:
...
<Scheme>
...
<SystemAuthorization>
<RequireRole>MY_APPLICATION_ROLE</RequireRole>
</SystemAuthorization>
...
</Scheme>
...
If multiple roles are defined, all of these roles must be active to successfully
authorize a specific user. If no role is given, JCas will not check for any
active role. Nevertheless you need to include an empty
<SystemAuthorization> tag.
Customized Authorization
In a Customized Authorization mechanism, users are authenticated using a specific
database table (by default: JCAS_USER_TABLE). The table contains all permitted
users and their passwords.
Before making use of this mechanism, JCas needs login information for the database
instance to access the user table. This information is given in the <User>
and <Password> tags within the instance definitions:
...
<Instance>
...
<User>MY_TECH_USER</User>
<Password>MY_TECH_PASSWORD</Password>
...
</Instance>
The <Scheme> tag must include a <CustomAuthorization> tag
to switch on this kind of mechanism. By default, JCas will use the columns UID and PWD
of the JCAS_USER_TABLE database table. These names can be changed by including the
appropriate configuration tags:
...
<Scheme>
...
<CustomAuthorization>
<TableName>APPL_USERS</TableName>
<UidColumn>LOGIN_NAME</UidColumn>
<PwdColumn>PASSWORD</PwdColumn>
</CustomAuthorization>
...
</Scheme>
Not all of these tags must be present. If you are fine with the default names, leave the
<CustomAuthorization> tag empty.
Extended Authorization
Additional authorization can be performed optionally after authentication
was performed successfully. There are two types of Extended AUthorization:
- Execution of a user defined database function
- Execution of a user defined SQL query
Both types expect certain return values that tell if authorization
was successful or not.
Execution of a user defined database function
Some database vendors, such as Oracle, allow users to program their
own functions using a specific database language (PL/SQL, Java, etc.).
If you need to perform a specific authorization not covered by standard
mechanism described above, then you can implement this requirements
in such a user-defined function. JCas will execute the function and
evaluate its return code. However, the function must fulfill some
interface conditions:
- It must take a single argument, a string containing the
username to be authorized.
- It must return a string.
- Following return values indicate successful authorization:
To enable JCas to execute a function on a specific database, you first need
to specify a so called "dummy table". This table is used to query a single
row containing the result of the function. Let's have a look at an example:
To authorize user FRED it is necessary to call a function
named MY_AUTHORIZATION(UID VARCHAR). JCas will issue the
following SQL Query:
SELECT MY_AUTHORIZATION('FRED') FROM DUMMY_TABLE
The dummy table MUST contain a single row. It can contain more rows but JCas
will query the first one only. A side-effect of having more than one rows in
the dummy table would be decreased efficiency since databases will compute
the function's result for each single row.
Some database vendors have such a dummy table built in, e.g. Oracle named
it DUAL. However, you can use your own table if you like but you need
to specify it in the <Instance> definition:
...
<Instance>
...
<DummyTable>DUAL</DummyTable>
...
<Instance>
...
Now you're ready to configure the function call. Here is an example of an
extended authorization by a user-defined function:
...
<Scheme>
...
<ExtendedAuthorization>
...
<PLSQLFunction>
<Name>my_user_function</Name>
</PLSQLFunction>
...
</ExtendedAuthorization>
...
</Scheme>
If multiple functions are defined then all functions must accept the user
and return an accepted return value (see above).
The set of accepted return values can be changed by including <ReturnValue>
tags, replacing the default set:
...
<PLSQLFunction>
...
<!-- This tag will allow "Accepted" only -->
<ReturnValue>Accepted</ReturnValue>
...
</PLSQLFunction>
...
Multiple <ReturnValue> tags are permitted.
Execution of a user defined SQL query
If you need to query additional tables to authorize users, you can do
so by defining queries within the <ExtendedAuthorization> tag:
...
<Scheme>
...
<ExtendedAuthorization>
...
<Query>
<Select>SELECT 'Y' FROM my_users WHERE userid='$uid$' AND scheme='$scheme$'</Select>
</Query>
...
</ExtendedAuthorization>
...
</Scheme>
You can use placeholders to use user ID and scheme information within
your query.
You can change the set of accepted return values for your query
by including <ReturnValue> tags as described in the
previous section.
|