Alfresco Mobile for Android : Advanced Setup Guide

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com



AndroidConfiguration


Context


Alfresco Android Mobile uses CMIS protocol to retrieve informations and data from an Alfresco Repository. Since the version 4, Alfresco incorporates 2 implementations of CMIS.


So depending on what version of Alfresco Repository you try to connect, the Android mobile application uses one or the other implementation automatically.

NB : The application needs to have access to Alfresco server (/alfresco) and not Alfresco share (/share). Indeed Alfresco CMIS information can only be retrieved from the server part and not from a client part like Share application.


HOW-TO configure Alfresco Android Mobile application ?


Main Case


Let’s consider your server has a url that looks like https://hostname:port/alfresco
Whatever your Alfresco server version number, you must fill the account creation form like this :


  • Enter your user name and password
  • Hostname field : hostname
  • HTTPS : let the checkbox checked
  • Port field : enter the value number of your port.
  • Service URL : nothing to change.

You can now tap Validate and access your server via your mobile device.


Use case : Server & User certificate (Alfresco Mobile V1.1)


In some cases after tapping Validate button, the application may display an error message like this one : The server 's security certificate is not trusted!

When you activate HTTPS to transmit data, the server which hosts your Alfresco application presents a certificate to verify its identity. This certificate contains information such as the address of the website, which is confirmed by a third party organization that your Android device trusts. By checking that the address in the certificate matches the address of the website, it's possible to verify that you're communicating with the website named on the certificate, and not someone pretending to be that website.

To solve this problem you have two solutions :


  • Import and install certificate inside your device. (Recommended)
  • Disable SSL certificate validation (for development purpose only)




Import & install certificate


Since Android 4.X, it’s possible to manage your private certificate directly inside your Android device. Android supports DER-encoded X.509 certificates, saved in files with a .crt or .cer file extension. If your certificate file has a .der or other extension, you must change it to .crt or .cer or you won’t be able to install it.

NB : It’s possible to use this process to import user certificate and/or Certification Authority certificate (root or intermediate).

Requirements
To obtain your server certificate, you can request your server administrator.

Procedure
After that you can follow steps from this webpage : https://support.google.com/nexus/4/answer/2844832?hl=en

IMPORTANT : We always recommend this solution to guarantee a high security level!


Disable SSL certificate validation


If your server uses a self-signed certified certificate and if it’s not possible to import your Certification Authority certificate inside your device, it’s possible to disable SSL certificate validation.

Requirements
You need a file explorer/manager installed in your device. You can find one in Google play Store with keywords like file explorer / file manager

Procedure


  • With your file explorer : Go to the root folder of your sdcard. Generally the path looks like /sdcard or /mmt/sdcard . In recent version of Android it can also be : /storage/emulated/....
  • Go to the following folder (or create this hierarchy if necessary): Android/data/org.alfresco.mobile.android.application/files
  • Inside this folder create an empty file with a name like <hostname>.properties. For example if your server hostname is
    • 192.168.1.1, the filename is 192.168.1.1.properties
    • example.alfresco.com, the filename is example.alfresco.com.properties
  • When created, you can follow the default procedure to connect to your Alfresco server. NB : for security reason every first time a user try to connect to the server a notification is displayed. It alerts the SSL certificate validation is disabled.

IMPORTANT :  We highly recommend to use this solution only for testing/development purpose.


Use case : Reverse proxy configuration (Alfresco Mobile V1.1 only & Alfresco 4.x)


This part is only useful if Alfresco server is 4.x and configured with a reverse proxy server.

As explained in context part, the application is responsible to choose the right binding url to retrieve CMIS information from Alfresco Server. Due to the rewriting rules created by the reverse proxy configuration, the URL provided by CMIS must respect those rules. For the moment Alfresco server doesn’t embed any mechanism to rewrite URL from Apache Chemistry implementation. In this case, the user must enforce the use of Webscript implementation which has an internal rewriting mechanism.


Force URL binding


Requirements
The Alfresco Server must be configured.
See : How to configure your Alfresco onPremise Server...

Procedure
Let’s consider your server has a url that looks like https://hostname:port/alfresco
You must fill the account creation form like this :


  • Enter your user name and password
  • Hostname field : hostname
  • HTTPS : let the checkbox checked
  • Port field : enter the value number of your port.
  • Service URL : /alfresco/service/cmis

You can now tap Validate and access your server via your mobile device.

Troubleshooting
Since Alfresco Android Mobile 1.1 version, the application can display detailed error message that may happen during the authentication process. Those messages can help you to make the best decision.

For an exhausting list of all error messages, you can refer to  https://issues.alfresco.com/jira/browse/MOBILE-1287


HOW-TO configure your Alfresco onPremise Server ?


Main case


Your server must be accessible from your device network via Internet or private wifi network.


Use case : Missing intermediate certificate authority


Most public CAs don't sign server certificates directly. Instead, they use their main CA certificate, referred to as the root CA, to sign intermediate CAs. They do this so the root CA can be stored offline to reduce risk of compromise. However, operating systems like Android typically trust only root CAs directly, which leaves a short gap of trust between the server certificate—signed by the intermediate CA—and the certificate verifier, which knows the root CA. To solve this, the server doesn't send the client only it's certificate during the SSL handshake, but a chain of certificates from the server CA through any intermediates necessary to reach a trusted root CA.

What is interesting to note here is that visiting the server in most desktop browsers does not cause an error like a completely unknown CA or self-signed server certificate would cause. This is because most desktop browsers cache trusted intermediate CAs over time. Once a browser has visited and learned about an intermediate CA from one site, it won't need to have the intermediate CA included in the certificate chain the next time.

To solve this issue:


  • Configure the server to include the intermediate CA in the server chain. Most CAs provide documentation on how to do this for all common web servers. This is the only approach if you need the site to work with default Android browsers at least through Android 4.2.
  • Add manually the missing certificate inside your devices as explained  Import & install certificate

Use case : Reverse proxy configuration


Alfresco 3.4.x


CMIS retrieves the host and port to use for 'links' from web script config. By default the local machine name is used as the host. When using a proxy these config values need to be changed to the publicly accessible host and port.
To do this add the following config…

  <alfresco-config> 
  <config evaluator='string-compare' condition='Server'>
     <server>
        <scheme>http</scheme>
        <hostname>your-pulic-host</hostname>
        <port>your-port</port>
        <path>alfresco</path>
     </server>
  </config>

</alfresco-config>

to a file in the following location:
/shared/classes/META-INF/spring-webscripts-config-custom.xml


Alfresco 4.x


Follow steps from : https://issues.alfresco.com/jira/browse/ALF-17109 (Gavin answer)



Android

Attachments

    Outcomes