2.13. Digest authentication

A web server can use Digest access authentication - one of agreed-upon methods, to negotiate credentials with a web user's browser. Digest access authentication uses encryption to send a password over the network which is safer than the Basic access authentication that sends plaintext.

Technically, the digest authentication is an application of MD5 cryptographic hashing with usage of nonce values to discourage cryptanalysis. It uses the HTTP protocol.

Server configuration

To configure your server to use the digest authentication, you need to edit the serverside JAAS module implementation configuration file.

Tomcat server configuration

Change the login configuration as follows:

i. Edit the configuration file located at $PLATFORM_TOMCAT_HOME/webapps/rest.war!/WEB-INF/web.xml:

ii. Replace


<login-config>

    <auth-method>BASIC</auth-method>

    <realm-name>gatein-domain</realm-name>

</login-config>

with


<login-config>

    <auth-method>DIGEST</auth-method>

    <realm-name>gatein-domain</realm-name>

</login-config>

See Apache Tomcat Configuration Reference for Tomcat configuration.

Specify a new login module for JAAS:

i. Edit the configuration file located at $PLATFORM_TOMCAT_HOME/conf/jaas.conf.

ii. Replace

gatein-domain {

  org.exoplatform.services.security.j2ee.TomcatLoginModule required;

};

with

gatein-domain {

  org.exoplatform.services.security.j2ee.DigestAuthenticationTomcatLoginModule required;

};

JBoss server configuration

Edit the configuration file located at $PLATFORM_JBOSS_HOME/standalone/deployments/platform.ear/exo.portal.web.rest.war!/WEB-INF/web.xml by replacing


<login-config>

    <auth-method>BASIC</auth-method>

    <realm-name>gatein-domain</realm-name>

</login-config>

with


<login-config>

    <auth-method>DIGEST</auth-method>

    <realm-name>gatein-domain</realm-name>

</login-config>

Edit the login configuration file located at $PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo.xml:


<security-domain name="gatein-domain" cache-type="default">

    <authentication>

        <login-module code="org.exoplatform.services.security.j2ee.DigestAuthenticationJbossLoginModule" flag="required">

            <module-option name="usersProperties" value="path/to/users.properties" />

            <module-option name="rolesProperties" value="path/to/roles.properties" />

            <module-option name="hashAlgorithm" value="MD5" />

            <module-option name="hashEncoding" value="rfc2617" />

            <module-option name="hashUserPassword" value="false" />

            <module-option name="hashStorePassword" value="true" />

            <module-option name="passwordIsA1Hash" value="true" />

            <module-option name="storeDigestCallback" value="org.jboss.security.auth.spi.RFC2617Digest" />

        </login-module>

    </authentication>

</security-domain>

You probably should define users.properties and roles.properties according to your own needs.

See here for more information about the JBoss server Digest authentication configuration.

Organization Service implementation requirements

To make your own org.exoplatform.services.organization.OrganizationService implementation use the digest authentication, you need to make your UserHandler implementation also implement the org.exoplatform.services.organization.DigestAuthenticator interface which provides more flexible authenticatation methods. As it is called from org.exoplatform.services.organization.auth.OrganizationAuthenticatorImpl, it receives org.exoplatform.services.security.Credential instances. You can get more information from org.exoplatform.services.security.PasswordCredential.getPasswordContext(). It can be used to calculate the md5 digest of original password to compare it with the received one from the client side.