Chapter 82. Digest Authentication

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

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

82.1. Server configuration

To configure you server to use DIGEST authentication we need to edit serverside JAAS module implementation configuration file.

82.1.1. Tomcat Server configuration

You need to fulfill a couple of steps. Firstly change login configuration:

Edit config file located here: exo-tomcat/webapps/rest.war/WEB-INF/web.xml

Replace

<login-config>                                                                                                                                          
  <auth-method>BASIC</auth-method>                                                                                                                     
  <realm-name>eXo REST services</realm-name>                                                                                                           
</login-config>

for

<login-config>                                                                                                                                          
  <auth-method>DIGEST</auth-method>                                                                                                                     
  <realm-name>eXo REST services</realm-name>                                                                                                           
</login-config>

More information about tomcat configuration can be found at Apache Tomcat Configuration Reference.

Secondly you also need to specify new login module for JAAS:

Edit config file located here: exo-tomcat/conf/jaas.conf

Replace

exo-domain {
  org.exoplatform.services.security.j2ee.TomcatLoginModule required;
};

for

exo-domain {
  org.exoplatform.services.security.j2ee.DigestAuthenticationTomcatLoginModule required;
};

82.1.2. Jetty server configuration

You need to fulfill a couple of steps. Firstly change login configuration:

Edit config file located here: exo-jetty/webapps/rest.war/WEB-INF/web.xml

Replace

<login-config>                                                                                                                                          
  <auth-method>BASIC</auth-method>                                                                                                                     
  <realm-name>eXo REST services</realm-name>                                                                                                           
</login-config>

for

<login-config>                                                                                                                                          
  <auth-method>DIGEST</auth-method>                                                                                                                     
  <realm-name>eXo REST services</realm-name>                                                                                                           
</login-config>

Secondly you also need to specify new login module for JAAS:

Edit config file located here: exo-jetty/jaas.conf

Replace

exo-domain {
  org.exoplatform.services.security.j2ee.JettyLoginModule required;
};

for

exo-domain {
  org.exoplatform.services.security.j2ee.DigestAuthenticationJettyLoginModule required;
};

82.1.3. JBoss server configuration

Edit config file located here: exo-jboss/server/default/deploy/exo.jcr.ear.ear/rest.war/WEB-INF/web.xml

Replace

<login-config>                                                                                                                                          
  <auth-method>BASIC</auth-method>                                                                                                                     
  <realm-name>eXo REST services</realm-name>                                                                                                           
</login-config>

for

<login-config>                                                                                                                                          
  <auth-method>DIGEST</auth-method>                                                                                                                     
  <realm-name>eXo REST services</realm-name>                                                                                                           
</login-confi

You also need to edit login configuration file located here: exo-jboss/server/default/conf/login-config.xml

<application-policy name="exo-domain">
    <authentication>
        <login-module code="org.exoplatform.services.security.j2ee.DigestAuthenticationJbossLoginModule"
                      flag="required">
            <module-option name="usersProperties">props/jmx-console-users.properties</module-option>
            <module-option name="rolesProperties">props/jmx-console-roles.properties</module-option>
            <module-option name="hashAlgorithm">MD5</module-option>
            <module-option name="hashEncoding">rfc2617</module-option>
            <module-option name="hashUserPassword">false</module-option>
            <module-option name="hashStorePassword">true</module-option>
            <module-option name="passwordIsA1Hash">true</module-option>
            <module-option name="storeDigestCallback">
                org.jboss.security.auth.spi.RFC2617Digest
            </module-option>
        </login-module>
    </authentication>
</application-policy>

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

More information about jboss server Digest authentication configuration can be found at JBoss quide chapter.

82.2. OrganizationService implementation requirements

To make your own org.exoplatform.services.organization.OrganizationService implementation able to use DIGEST authentication you need to make your UserHandler implementation also implement org.exoplatform.services.organization.DigestAuthenticator interface which provide more flexible authenticate method. As it is called from org.exoplatform.services.organization.auth.OrganizationAuthenticatorImpl it receive a org.exoplatform.services.security.Credential instances, you can get more information from org.exoplatform.services.security.PasswordCredential.getPasswordContext(). It can be used to calculate md5 digest of original password to compare it with recieved from clientside.