FAQs

Frequently Asked Questions - realm

FAQs - realm

A security realm is a "database" against which QuartzDesk Web Application users are authenticated. It is also the main source of basic user profile attributes, such as the first name, surname and email address.

Security realms in QuartzDesk are pluggable and can be configured in quartzdesk-web.properties. Out-of-the-box, QuartzDesk Web Application provides the following security realm implementations:

ImplementationDescription
com.quartzdesk.core.security.realm.DefaultSecurityRealm

The default security realm implementation that authenticates users against QuartzDesk Web application database, i.e. the database pointed to by the configured QuartzDeskDS data source.

com.quartzdesk.core.security.realm.jndi.JNDISecurityRealm

A security realm that authenticates users against a configured directory server. This realm is highly configurable to support various types of directory services and user authentication approaches (e.g. bind mode, comparison mode).

For JNDI security realm configuration details, please refer here.

If necessary, users can create and register their own security realm implementations. To implement a custom security realm, please refer to this FAQ item.

QuartzDesk Web application comes with a ready-to-use and highly configurable JNDISecurityRealm implementation that allows you to authenticate users against a configured directory service.

For an explanation of what  QuartzDesk Web Application security realms are, please see here.

To use JNDISecurityRealm, please add the following configuration properties to your quartzdesk-web.properties:

PropertyValue
Description
security.realm.implementationcom.quartzdesk.core.security.realm.jndi.JNDISecurityRealm

The security realm implementation class suitable for all directory services accessed through JNDI.

security.realm.param.connectionUrlThe directory service connection URL, e.g. ldap://localhost:389.
security.realm.param.connectionUsernameThe username to use to connect to the directory service.
security.realm.param.connectionPasswordThe password to use to connect to the directory service.
security.realm.param.connectTimeoutThe connection timeout in milliseconds. If not specified, the timeout value is set to 10000 (10 seconds).
security.realm.param.readTimeoutThe read timeout in milliseconds. If not specified, the timeout value is set to 10000 (10 seconds).
security.realm.param.userBase

The distinguished name (DN) of the directory branch underneath which users are stored.

Example: ou=Departments,dc=MyCompany,dc=com

security.realm.param.userSearchQuery

The search query used to locate a user entry by the username. {0} in the query is automatically replaced with the username before the search is executed.

Example: (uid={0})

security.realm.param.userSearchSubtree

The user entry search scope. If set to true, the entire subtree rooted at userBase is searched. Otherwise, only the first level under userBase is searched.

security.realm.param.authCheckMethod

The user authentication method to use. The following two methods are supported:

BIND
The security realm attempts to bind with the DN of the user directory entry found by the configured userSearchQuery query and the user-provided password.

COMPARE
The security realm reads the user's password digest from the user directory entry found by the configured userSearchQuery query and compares this digest with the digest of the user-provided password.
security.realm.param.passwordMatcherImplementationcom.quartzdesk.core.security.realm.jndi.JNDIPasswordMatcher

The password matcher implementation class that is used to match the user-entered password with its digest stored in the directory. The password matcher is used only if the configured authCheckMethod is set to COMPARE.

security.realm.param.passwordMatcherImplementation implementation supports all of the following password digest algorithms used by popular directory services:

  • Unsalted MD5 digests. Digest format: {MD5}<digest>
  • Unsalted SHA-1 digests. Digest format: {SHA}<digest>
  • Unsalted SHA-256 digests. Digest format: {SHA256}<digest>
  • Unsalted SHA-384 digests. Digest format: {SHA384}<digest>
  • Unsalted SHA-512 digests. Digest format: {SHA512}<digest>
  • Salted MD5 digests. Digest format: {SMD5}<digest><salt>
  • Salted SHA-1 digests. Digest format: {SSHA}<digest><salt>
  • Salted SHA-256 digests. Digest format: {SSHA256}<digest><salt>
  • Salted SHA-384 digests. Digest format: {SSHA384}<digest><salt>
  • Salted SHA-512 digests. Digest format: {SSHA512}<digest><salt>
security.realm.param.authCheckCompareAttrPassword

The name of a required directory user entry attribute that contains the user's password digest. This attribute name is used only if the configured authCheckMethod is set to COMPARE.

Example: userPassword

security.realm.param.attrFirstName

The name of a required directory user entry attribute that contains the user's first name.

Example: givenName

security.realm.param.attrSurname

The name of a required directory user entry attribute that contains the user's first name.

Example: sn

security.realm.param.attrEmail

The name of a required directory user entry attribute that contains the user's email address.

Example: email

security.realm.param.attrWorkPhoneNumber

The name of an optional directory user entry attribute that contains the user's work phone number.

Example: telephoneNumber

security.realm.param.attrMobilePhoneNumber

The name of an optional directory user entry attribute that contains the user's mobile phone number.

Example: mobile

security.realm.param.attrAvatarUrl

The name of an optional directory user entry attribute that contains the URL of the user's avatar image.

Example: photoUrl

security.realm.param.phoneNumberParserImplementation

The name of an optional phone number parser implementation that parses phone number strings in user directory entries and produces com.quartzdesk.domain.model.common.PhoneNumber instances. The following phone number parser implementations are available out-of-the-box:

com.quartzdesk.core.security.realm.SimplePhoneNumberParser
A trivial implementation that interprets the phone number string as a subscriber number.

com.quartzdesk.core.security.realm.GooglePhoneNumberParser
An implementation that uses the Google libphonenumber library. Please note that this phone parser implementation is locale-sensitive and as such you need to specify the locale to be used. See the phoneNumberParserLocale parameter.

If no phone number parser implementation is specified, then the SimplePhoneNumberParser implementation is used.

security.realm.param.phoneNumberParserLocale

The name of the Java locale used by the phone number parser. If no locale is specified, then the en_US locale is assumed. For the list of all supported Java locales, please see here.

Examples: en_GB (for UK), en_CA (for Canada), nl_NL (for Netherlands), etc.

Short answer: yes.

If none of the out-of-the-box provided security realm implementation does not suit your needs, you can use your own implementation. This custom implementation must implement the com.quartzdesk.core.security.realm.ISecurityRealm interface.

When implementing a custom realm, it is often easier to extend one of the provided security realm implementations and just override the relevant method, or use the abstract security realm base class com.quartzdesk.core.security.realm.AbstractSecurityRealm.

Once the custom security realm implementation class is ready, copy this class and all of its dependencies to quartzdesk-web.war/WEB-INF/classes (*.class files) and quartzdesk-web.war/WEB-INF/lib (JAR files). This is required because the security realm implementation class must be on the QuartzDesk Web Application's classpath.

All of the afore-mentioned security APIs are available in quartzdesk-core.jar located in quartzdesk-web.war/WEB-INF/lib. If you need to compile your custom security realm implementation against these APIs, please extract quartzdesk-core.jar from the WAR file and upload it to your Maven repository. 

To make QuartzDesk Web Application use the custom security realm, you will need to add the following configuration property to your quartzdesk-web.properties:

security.realm.implementation = <class_name>

where <class_name> is the fully-qualified name of the custom security realm implementation class.

If your custom security realm implementation requires some initialization parameters, please add these parameters to quartzdesk-web.properties like so:

security.realm.param.<param_name> = <param_value>

where <param_name> is the parameter name and <param_value> is the parameter value. Once a security realm instance has been created, the parameters are passed to it by invoking its setParameters( Map<String,String> parameters ) method.

If you need any assistance, please do not hesitate and contact our Technical Support through our online chat or via email at support@quartzdesk.com.