org.norther.tammi.core.realm
Interface Realm

All Superinterfaces:

Configurable

All Known Subinterfaces:

JndiRealm, MemoryRealm, NativeRealm, RepositoryRealm

All Known Implementing Classes:

AbstractRealm, DefaultJndiRealm, DefaultMemoryRealm, DefaultNativeRealm, DefaultRepositoryRealm

public interface Realm
extends Configurable

An interface to realms.

Based on Realm in the Apache Jakarta Tomcat project.

Author:

Craig R. McClanahan, Ilkka Priha

Field Summary

static String	ANONYMOUS_USER_PROPERTY The anonymous user property.
static String	CACHED_PASSWORDS_PROPERTY The cached passwords property.
static String	DEFAULT_ROLE_PROPERTY The default role property.
static String	DIGEST_ALGORITHM_PROPERTY The digest algorithm property.
static String	MEMBER_PROPERTY The member property.
static String	PUBLIC_NAME_PROPERTY The public name property.

Method Summary

Principal	authenticate(Certificate[] certs) Authenticates the principal with a certificate.
Principal	authenticate(Principal principal, String scheme) Authenticates the specified principal in this realm.
Principal	authenticate(String domain, Certificate[] certs) Authenticates the principal with a certicate in the specified domain.
Principal	authenticate(String domain, Principal principal, String scheme) Authenticates the specified principal in the specified domain of this realm.
Principal	authenticate(String username, String password, String scheme) Authenticates the principal associated with the specified username and password using the specified scheme, if there is one.
Principal	authenticate(String domain, String username, String password, String scheme) Authenticates the principal associated with the specified username and password in the specified domain using the specified scheme, if there is one.
Principal	authenticate(String username, String realmname, String resp, String nonce, String nc, String cnonce, String qop, String md5a2, String encoding) Authenticates the principal associated with the specified username matching the digest calculated using the given parameters using the method described in RFC2617/2831.
Principal	authenticate(String domain, String username, String realmname, String resp, String nonce, String nc, String cnonce, String qop, String md5a2, String encoding) Authenticates the principal associated with the specified username in the specified domain matching the digest calculated using the given parameters using the method described in RFC2617/2831.
String	digest(String username, String password) Digests the password for the specified username using the defined algorithm and converts the result to a corresponding hexadecimal string.
String	generateAuthenticate(String username, String password, String scheme) Generates the authentication header.
String	getAnonymousUser() Gets the username for anonymous principals.
String	getAuthType() Gets the authentication scheme.
String	getDefaultRole() Gets the default role of authenticated principals.
String	getDigestAlgorithm() Gets the digest algorithm used to store credentials.
String	getPublicName() Gets the public name of this realm.
Principal	identify(String identity) Identifies the principal associated with the specified identity.
Principal	identify(String username, String password) Identifies the principal associated with the specified username and password.
boolean	isAuthenticated(Principal principal) Checks whether the specified principal is authenticated in this realm.
boolean	isAuthenticated(String domain, Principal principal) Checks whether the specified principal is authenticated in the specified domain of this realm.
boolean	isCachedPasswords() Checks whether non-digested client passwords are cached.
boolean	isUserInRole(Principal principal, String role) Checks whether the specified principal is in the specified security role within the context of any domain in this realm.
void	setAnonymousUser(String username) Sets the username for anonymous principals.
void	setCachedPasswords(boolean flag) Sets the option to cache non-digested client passwords of authenticated principals to be used in e.g.
void	setDefaultRole(String role) Sets the default role of authenticated principals.
void	setDigestAlgorithm(String digest) Sets the digest algorithm used to store credentials.
void	setPublicName(String name) Sets the public name of this realm.

Methods inherited from interface org.norther.tammi.core.config.Configurable

addProperty, addProperty, clearProperties, containsProperty, getConfigKey, getProperties, getProperty, getPropertyFilePath, indexOfProperty, propertyMap, propertyMap, removeProperty, removeProperty, setConfigKey, setProperties, setProperty, setPropertyFilePath, setPropertyFilePath, storeProperties

Field Detail

PUBLIC_NAME_PROPERTY

static final String PUBLIC_NAME_PROPERTY

The public name property.

See Also:

Constant Field Values

DIGEST_ALGORITHM_PROPERTY

static final String DIGEST_ALGORITHM_PROPERTY

The digest algorithm property.

See Also:

Constant Field Values

CACHED_PASSWORDS_PROPERTY

static final String CACHED_PASSWORDS_PROPERTY

The cached passwords property.

See Also:

Constant Field Values

DEFAULT_ROLE_PROPERTY

static final String DEFAULT_ROLE_PROPERTY

The default role property.

See Also:

Constant Field Values

ANONYMOUS_USER_PROPERTY

static final String ANONYMOUS_USER_PROPERTY

The anonymous user property.

See Also:

Constant Field Values

MEMBER_PROPERTY

static final String MEMBER_PROPERTY

The member property.

See Also:

Constant Field Values

Method Detail

getPublicName

String getPublicName()

Gets the public name of this realm.

Returns:

the public name.

setPublicName

void setPublicName(String name)

Sets the public name of this realm.

Note that if both the digest algorithm and the public name are defined, the digested passwords must include the username and the realmname in the form: <username>:<realmname>:<password>.

Parameters:

name - the public name.

getDigestAlgorithm

String getDigestAlgorithm()

Gets the digest algorithm used to store credentials.

Returns:

the digest algorithm.

setDigestAlgorithm

void setDigestAlgorithm(String digest)

Sets the digest algorithm used to store credentials.

Parameters:

digest - the digest algorithm.

isCachedPasswords

boolean isCachedPasswords()

Checks whether non-digested client passwords are cached.

Returns:

the cached passwords option.

setCachedPasswords

void setCachedPasswords(boolean flag)

Sets the option to cache non-digested client passwords of authenticated principals to be used in e.g. JDBC authentication. The default is to cache only the digested server credentials.

Parameters:

flag - the cached passwords option.

getDefaultRole

String getDefaultRole()

Gets the default role of authenticated principals.

Returns:

the default role.

setDefaultRole

void setDefaultRole(String role)

Sets the default role of authenticated principals. If set, it will be associated to all authenticated principals in addition to their account specific roles.

Parameters:

role - the default role.

getAnonymousUser

String getAnonymousUser()

Gets the username for anonymous principals.

Returns:

the anonymous username.

setAnonymousUser

void setAnonymousUser(String username)

Sets the username for anonymous principals. If set, it will be associated to unauthenticated principals without a username.

Note that the anonymous user must be known within the realm but its credentials are not necessarily verified during authentication.

Parameters:

username - the default guest.

isUserInRole

boolean isUserInRole(Principal principal,
                     String role)

Checks whether the specified principal is in the specified security role within the context of any domain in this realm.

Parameters:

principal - the principal for whom the role is to be checked.

role - the security role to be checked.

Returns:

true or false.

isAuthenticated

boolean isAuthenticated(Principal principal)

Checks whether the specified principal is authenticated in this realm.

Parameters:

principal - the principal to be checked.

Returns:

true or false.

isAuthenticated

boolean isAuthenticated(String domain,
                        Principal principal)

Checks whether the specified principal is authenticated in the specified domain of this realm.

Parameters:

domain - the domain of the user.

principal - the principal to be checked.

Returns:

true or false.

identify

Principal identify(String identity)

Identifies the principal associated with the specified identity.

Parameters:

identity - the identity.

Returns:

the identified principal.

identify

Principal identify(String username,
                   String password)

Identifies the principal associated with the specified username and password.

Parameters:

username - the username.

password - the password.

Returns:

the identified principal.

authenticate

Principal authenticate(Principal principal,
                       String scheme)

Authenticates the specified principal in this realm.

Parameters:

principal - principal to be authenticated.

scheme - the authentication scheme to be applied.

Returns:

the authenticated principal, identified principal or null.

authenticate

Principal authenticate(String domain,
                       Principal principal,
                       String scheme)

Authenticates the specified principal in the specified domain of this realm.

Parameters:

domain - the domain of the user.

principal - principal to be authenticated.

scheme - the authentication scheme to be applied.

Returns:

the authenticated principal, identified principal or null.

authenticate

Principal authenticate(String username,
                       String password,
                       String scheme)

Authenticates the principal associated with the specified username and password using the specified scheme, if there is one.

The username can be null or empty for an anonymous authentication.

Parameters:

username - the username to look up.

password - the password to use in authentication.

scheme - the authentication scheme to be applied.

Returns:

the authenticated principal, identified principal or null.

authenticate

Principal authenticate(String domain,
                       String username,
                       String password,
                       String scheme)

Authenticates the principal associated with the specified username and password in the specified domain using the specified scheme, if there is one.

The username can be null or empty for an anonymous authentication.

Parameters:

domain - the domain of the user.

username - the username to look up.

password - the password to use in authentication.

scheme - the authentication scheme to be applied.

Returns:

the authenticated principal, identified principal or null.

authenticate

Principal authenticate(String username,
                       String realmname,
                       String resp,
                       String nonce,
                       String nc,
                       String cnonce,
                       String qop,
                       String md5a2,
                       String encoding)

Authenticates the principal associated with the specified username matching the digest calculated using the given parameters using the method described in RFC2617/2831.

Note that either non-encrypted or MD5 digested passwords must be applied. Digested passwords must include the username and realmname in the form: <username>:<realmname>:<password>.

The username can be null or empty for an anonymous authentication.

Parameters:

username - the username to look up.

realmname - the realm, i.e. the identification of the server.

resp - the digest which has been submitted by the client.

nonce - a unique token which has been used for this request.

nc - a nonce count.

cnonce - a client nonce.

qop - the quality of protection ("auth", "auth-int",...)

md5a2 - the second MD5 digest used to calculate the digest: MD5(Method + ':' + uri).

encoding - the chareacter encoding to apply.

Returns:

the authenticated principal, identified principal or null.

authenticate

Principal authenticate(String domain,
                       String username,
                       String realmname,
                       String resp,
                       String nonce,
                       String nc,
                       String cnonce,
                       String qop,
                       String md5a2,
                       String encoding)

Authenticates the principal associated with the specified username in the specified domain matching the digest calculated using the given parameters using the method described in RFC2617/2831.

Note that either non-encrypted or MD5 digested passwords must be applied. Digested passwords must include the username and realmname in the form: <username>:<realmname>:<password>.

The username can be null or empty for an anonymous authentication.

Parameters:

domain - the domain of the user.

username - the username to look up.

realmname - the realm, i.e. the identification of the server.

resp - the digest which has been submitted by the client.

nonce - a unique token which has been used for this request.

nc - a nonce count.

cnonce - a client nonce.

qop - the quality of protection ("auth", "auth-int",...)

md5a2 - the second MD5 digest used to calculate the digest: MD5(Method + ':' + uri).

encoding - the character encoding to apply.

Returns:

the authenticated principal, identified principal or null.

authenticate

Principal authenticate(Certificate[] certs)

Authenticates the principal with a certificate.

Parameters:

certs - the peer certificate chain.

Returns:

the authenticated principal, identified principal or null.

authenticate

Principal authenticate(String domain,
                       Certificate[] certs)

Authenticates the principal with a certicate in the specified domain.

Parameters:

domain - the domain of the user.

certs - the peer certificate chain.

Returns:

the authenticated principal, identified principal or null.

getAuthType

String getAuthType()

Gets the authentication scheme. Usually this is defined by the authenticator, but some native realms provide proprietary authentication schemes.

Returns:

the authentication scheme or null.

generateAuthenticate

String generateAuthenticate(String username,
                            String password,
                            String scheme)

Generates the authentication header. Usually this can be done by the authenticator, but some native realms provide proprietary authentication schemes.

The username can be null or empty for an anonymous authentication.

Parameters:

username - the username to look up.

password - the password to use in authentication.

scheme - the authentication scheme to be used.

Returns:

the authentication header value.

Throws:

UnsupportedOperationException - if not supported.

digest

String digest(String username,
              String password)

Digests the password for the specified username using the defined algorithm and converts the result to a corresponding hexadecimal string. The UTF-8 encoding is applied.

Parameters:

username - the username.

password - the password or other credentials.

Returns:

the digest as a hexadecimal string.