Changes between Initial Version and Version 1 of DeveloperGuidelines/Mobile/Android/ODKCollect


Ignore:
Timestamp:
01/02/15 20:50:48 (7 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines/Mobile/Android/ODKCollect

    v1 v1  
     1= ODK Collect Integration =
     2[[TOC]]
     3
     4  ''Note:'' this is just a brain dump intended to be useful for developers involved with the new XForms module - proper documentation to follow upon completion of the module.
     5
     6== Authentication ==
     7
     8Since version 1.1.7, ODK Collect supports HTTP !BasicAuth '''if''' run via HTTPs and confronted with a proper HTTP-401 Auth challenge.
     9
     10Recent Eden trunk versions implement the Auth challenge, and the best option to configure HTTPs access to Eden is to deploy it behind a web server (e.g. Apache2) with SSL.
     11
     12== ODK Collect Settings ==
     13
     14Under "General Settings", configure:
     15
     16  - Platform: "Other"
     17  - Configure Platform Settings
     18    - URL: https://<your-server.domain>/eden/xforms
     19    - Username: your username
     20    - Password: your password
     21    - Form list path: /formList
     22    - Submission path: /submission
     23
     24== Problem: No Peer Certificate ==
     25
     26Unfortunately, ODK Collect will refuse to work with self-signed server certificates. A certificate signed by an official CA is though too expensive for developers, so therefore here a few notes how you can get around this:
     27
     28=== Android 4+ User-Trusted Certificates ===
     29
     30Android 4+ allows the user to install user-trusted certificates for use via WiFi. When you download a certificate in Chrome, it will automatically invoke the certificate manager which allows you to install it as "user trusted" certificate.
     31
     32But the certificate manager may report successful installation even if nothing has been installed. To understand that, you need to know two things:
     33
     34  a) Android does only accept CA certificates, not server certificates
     35  b) Android required the certificate to be in DER format
     36
     37To achieve (a):
     38
     391) Create a new CA key
     40{{{
     41openssl genrsa -des3 -out rootCA.key 2048
     42}}}
     43
     442) Create a self-signed CA root certificate
     45{{{
     46openssl req -x509 -new -nodes -key rootCA.key -days 365 -out rootCA.crt
     47}}}
     48
     493) Create a server key (if you don't have one yet)
     50{{{
     51openssl genrsa -out host.key 2048
     52}}}
     53
     544) Generate a CSR with the server key (if you don't have one yet)
     55{{{
     56openssl req -new -key host.key -out host.csr
     57}}}
     58
     595) Sign the CSR with the rootCA key
     60{{{
     61openssl x509 -req -in host.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out host.crt -days 365
     62}}}
     63
     646) Use rootCA.crt, host.key and host.crt the SSL config in your vhost (paths may differ depending on your OS):
     65{{{
     66  SSLEngine On
     67  SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
     68  SSLCertificateFile /etc/apache2/ssl.crt/host.crt
     69  SSLCertificateKeyFile /etc/apache2/ssl.key/host.key
     70  SSLCACertificateFile /etc/apache2/ssl.crt/rootCA.crt
     71}}}
     72
     73To achieve (b)
     74
     751) Convert the certificate into DER format:
     76{{{
     77openssl x509 -in rootCA.crt -outform der -out rootCA.der.crt
     78}}}
     79
     802) Publish the rootCA.der.crt on your web server
     813) Open the certificate's URL in Chrome, install it as "user trusted certificate" as described above
     824) Verify that the certificate is installed under Settings > Security > Trusted Certificates > User
     83
     84== Problem: Invalid Response Status for HEAD Request ==
     85
     86ODK Collect doesn't send the data to trigger the Auth challenge, but a HEAD request. Unfortunately, it would send the HEAD request to an interactive-format URL in Eden, so that Eden (correctly) redirects to the login page with a HTTP 303 status. This is seen as "invalid response status" by ODK Collect, so you see that error message.
     87
     88There are two possible ways around this:
     89
     901) Catch the "xforms" controller in AuthS3.permission.fail() - and respond with a HTTP 401 Auth challenge instead of redirecting
     912) Configure ODK Collect to submit to /submission.xml instead of /submission (which makes it a non-interactive URL)
     92
     93Solution (1) will be implemented in future versions of the xforms module (still under development while writing this).
     94
     95== Problem: ODK Collect crashes when attempting to download an xform ==
     96
     97Possible causes:
     98
     991) web2py renders whitespace before the xml processing instruction in the xform
     1002) xform XML is not well-formed due to encoding problems (mismatching tags, restricted characters in attributes etc.)
     101
     102These issues will be fixed in future versions of the xforms module (still under development while writing this).
     103
     104== Problem: ODK Collect crashes when attempting to submit an xform ==
     105
     106Possible cause:
     107
     1081) xform module responds to the HEAD request with a HTTP 400 status (because it doesn't contain an XForm)
     109
     110Solution: catch the HEAD request in submission() and respond with a HTTP 204 status (this is what ODK Collect expects).
     111
     112This solution will be implemented in future versions of the xforms module (still under development while writing this).
     113