com.ashtonit.odb.realm

Class OdbRealm

java.lang.Object

org.apache.catalina.util.LifecycleBase

org.apache.catalina.util.LifecycleMBeanBase

org.apache.catalina.realm.RealmBase

com.ashtonit.odb.realm.OdbRealm

All Implemented Interfaces:

MBeanRegistration, org.apache.catalina.JmxEnabled, org.apache.catalina.Lifecycle, org.apache.catalina.Realm

public class OdbRealm
extends org.apache.catalina.realm.RealmBase

A Tomcat Realm class for OrientDB databases.

OdbRealm allows a web application to authenticate users against an embedded or standalone OrientDB database. It was originally written to authenticate only against the built-in OUser and ORole classes but the authentication is now configurable by a query.

It takes an OSQL query string as a attribute named query which must return the password hash and the roles for a user.

The query must:

• Take one parameter (the user name or identifier)
• Return the password hash as a String for the user with a parameter name of, "password"
• Return the role names for the user as a List of Strings with a parameter name of, "roles"

The password is checked using the method OSecurityManager.checkPassword(String, String). It checks for three different types of password hashes by looking at the prefix of the string. They are:

• SHA-256 (A string prefix of {SHA-256}-)
• PBKDF2WithHmacSHA1 (A string prefix of {PBKDF2WithHmacSHA1}-)
• PBKDF2WithHmacSHA256 (A string prefix of {PBKDF2WithHmacSHA256}-)

The simplest way to create a password hash in the correct format is to use the method OUser.encryptPassword(String).

Important things to note for OdbRealm configuration are:

1. The className attribute must have a value of "com.ashtonit.odb.realm.OdbRealm".
2. The value of the dbUser attribute must be the name of a database user with read access to the user class for this realm. The "admin" user can be used for this for development and testing purposes.
3. The value of the dbResource attribute must match the value of the "name" attribute in your OdbResource configuration. If it is not present the realm creates its own instance of OPartitionedDatabasePool with the default capacity of 100.
4. The value of the dbUrl attribute must be a valid OrientDB URI.
5. The value of the query attribute must be an OSQL query string that takes one parameter (a user identifier) and returns the password hash and roles.

An example OdbRealm definition:

   <Realm
     className="com.ashtonit.odb.realm.OdbRealm"
     dbPass="admin"
     dbResource="opdpfactory"
     dbUrl="plocal:/opt/odb/mydb"
     dbUser="admin"
     query="SELECT password, roles.name AS roles FROM OUser WHERE status = 'ACTIVE' AND name = ?"
   />
 

The Tomcat guide on realm configuration is here.

Author:

Bruce Ashton

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase

org.apache.catalina.realm.RealmBase.AllRolesMode

Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

org.apache.catalina.Lifecycle.SingleUse

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	info
protected static String	name

Fields inherited from class org.apache.catalina.realm.RealmBase

allRolesMode, container, containerLog, digest, digestEncoding, md, md5Helper, realmPath, sm, stripRealmForGss, support, validate, x509UsernameRetriever, x509UsernameRetrieverClassName

Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase

mserver

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

Constructors

Constructor and Description
OdbRealm()

Method Summary

Modifier and Type	Method and Description
Principal	authenticate(GSSContext gssContext, boolean storeCred) This method of authentication is not supported by this implementation.
Principal	authenticate(String username) This method of authentication is not supported by this implementation.
Principal	authenticate(String username, String password) Authenticates a database user.
Principal	authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, String md5a2) This method of authentication is not supported by this implementation.
Principal	authenticate(X509Certificate[] certs) This method of authentication is not supported by this implementation.
protected String	getName() Return a short name for this Realm implementation, for use in log messages.
protected String	getPassword(String username) This method is not supported by this implementation.
protected Principal	getPrincipal(String username) This method is not supported by this implementation.
void	setDbPass(String dbPass) The password for the generic user to connect to the database with so that we can look up the principal.
void	setDbResource(String dbResource) Sets the name of an arbitrary database resource instance.
void	setDbUrl(String dbUrl) Sets the URL for the OrientDB database.
void	setDbUser(String dbUser) Sets the generic username to connect to the database with so that we can look up the principal.
void	setQuery(String query) Sets the SQL query used to select the password and roles for the given user name.

Methods inherited from class org.apache.catalina.realm.RealmBase

addPropertyChangeListener, backgroundProcess, compareCredentials, digest, Digest, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDigest, getDigestCharset, getDigestEncoding, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getServer, getTransportGuaranteeRedirectStatus, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, hasUserDataPermission, initInternal, isStripRealmForGss, main, removePropertyChangeListener, setAllRolesMode, setContainer, setCredentialHandler, setDigest, setDigestEncoding, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setValidate, setX509UsernameRetrieverClassName, startInternal, stopInternal, toString

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister

Methods inherited from class org.apache.catalina.util.LifecycleBase

addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, init, removeLifecycleListener, setState, setState, start, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

info

protected static final String info

name

protected static final String name

See Also:

Constant Field Values

Constructor Detail

OdbRealm

public OdbRealm()

Method Detail

authenticate

public Principal authenticate(GSSContext gssContext,
                              boolean storeCred)
                       throws UnsupportedOperationException

This method of authentication is not supported by this implementation.

Specified by:

authenticate in interface org.apache.catalina.Realm

Overrides:

authenticate in class org.apache.catalina.realm.RealmBase

Returns:

this method never returns

Throws:

UnsupportedOperationException - when called

See Also:

RealmBase.authenticate(GSSContext, boolean)

authenticate

public Principal authenticate(String username)
                       throws UnsupportedOperationException

This method of authentication is not supported by this implementation.

Specified by:

authenticate in interface org.apache.catalina.Realm

Overrides:

authenticate in class org.apache.catalina.realm.RealmBase

Returns:

this method never returns

Throws:

UnsupportedOperationException - when called

See Also:

RealmBase.authenticate(String)

authenticate

public Principal authenticate(String username,
                              String password)

Authenticates a database user. This is the only method of authentication (username and password) that this realm implementation supports. This is because of limitations imposed by the arguments needed to construct an OrientGraph instance - one of the arguments must be the password in plain text.

Specified by:

authenticate in interface org.apache.catalina.Realm

Overrides:

authenticate in class org.apache.catalina.realm.RealmBase

Parameters:

username - the username to authenticate

password - the password associated with the username

Returns:

an OdbPrincipal instance if authentication is successful, null otherwise

See Also:

RealmBase.authenticate(String, String)

authenticate

public Principal authenticate(String username,
                              String clientDigest,
                              String nonce,
                              String nc,
                              String cnonce,
                              String qop,
                              String realm,
                              String md5a2)
                       throws UnsupportedOperationException

This method of authentication is not supported by this implementation.

Specified by:

authenticate in interface org.apache.catalina.Realm

Overrides:

authenticate in class org.apache.catalina.realm.RealmBase

Returns:

this method never returns

Throws:

UnsupportedOperationException - when called

See Also:

RealmBase.authenticate(String, String, String, String, String, String, String, String)

authenticate

public Principal authenticate(X509Certificate[] certs)
                       throws UnsupportedOperationException

This method of authentication is not supported by this implementation.

Specified by:

authenticate in interface org.apache.catalina.Realm

Overrides:

authenticate in class org.apache.catalina.realm.RealmBase

Returns:

this method never returns

Throws:

UnsupportedOperationException - when called

See Also:

RealmBase.authenticate(X509Certificate[])

setDbPass

public void setDbPass(String dbPass)

The password for the generic user to connect to the database with so that we can look up the principal.

Parameters:

dbPass - the password for the generic user

setDbResource

public void setDbResource(String dbResource)

Sets the name of an arbitrary database resource instance.

If present the realm will use it to look up the OPartitionedDatabasePoolFactory in the Tomcat JNDI service and obtain a pool from it.

If it is not present the realm will create a new OPartitionedDatabasePool with the default capacity of 100.

Parameters:

dbResource - the JNDI name of the resource

setDbUrl

public void setDbUrl(String dbUrl)

Sets the URL for the OrientDB database.

Parameters:

dbUrl - the URL for the OrientDB database

setDbUser

public void setDbUser(String dbUser)

Sets the generic username to connect to the database with so that we can look up the principal. It needs read permissions on the OUser class.

Parameters:

dbUser - the generic username to connect to the database

setQuery

public void setQuery(String query)

Sets the SQL query used to select the password and roles for the given user name.

Parameters:

query - the query used to select the password and roles for the given user name

getName

protected String getName()

Return a short name for this Realm implementation, for use in log messages.

Specified by:

getName in class org.apache.catalina.realm.RealmBase

Returns:

a short name for this Realm implementation

See Also:

RealmBase.getName()

getPassword

protected String getPassword(String username)
                      throws UnsupportedOperationException

This method is not supported by this implementation.

Specified by:

getPassword in class org.apache.catalina.realm.RealmBase

Returns:

this method never returns

Throws:

UnsupportedOperationException - when called

See Also:

RealmBase.getPassword(String)

getPrincipal

protected Principal getPrincipal(String username)
                          throws UnsupportedOperationException

This method is not supported by this implementation.

Specified by:

getPrincipal in class org.apache.catalina.realm.RealmBase

Returns:

this method never returns

Throws:

UnsupportedOperationException - when called

See Also:

RealmBase.getPrincipal(String)