ODK-X Sync Endpoint

ODK-X Sync Endpoint is an implementation of ODK-X Cloud Endpoints. It runs a server inside a Docker container that implements the ODK-X REST Protocol.

It communicates with your ODK-X Android applications to synchronize your data and application files.

Depending on your needs, ODK-X Sync Endpoint can either be installed in a cloud-based virtual machine, or on your own infrastructure.

Authentication

ODK-X Sync Endpoint does not store user information in its own database, instead it integrates with an LDAP directory or an Active Directory. That directory is then used to authenticate users and obtain user roles.

Note

As a consequence of the integration, Basic Authentication is the only supported authentication method.

HTTPS

The Sync Endpoint stack integrates support for automatic certificate provisioning via domain validation and letsencrypt. For most use cases this should be sufficient. Certificate provisioning parameters can be edited interactively during initialization or directly in config/https.env.

Tip

For advanced users, if you would like to use an externally provisioned certificate one can be added by modifying the cert-bootstrap service in docker-compose-https.yml to pull from the appropriate external files. Additionally docker's built in secrets and config infrastructure can be used directly to expose the certificate and key only to the NGINX container.

LDAP

  • The default admin account is cn=admin,dc=example,dc=org.

  • The default password is admin - it can be changed with the LDAP_ADMIN_PASSWORD environment variable in ldap.env

  • The default readonly account is cn=readonly,dc=example,dc=org.

  • The default password is readonly - it can be changed with the LDAP_READONLY_USER_PASSWORD environment variable in ldap.env. This account is used by the Sync Endpoint to retrieve user information.

The LDAP directory that you deployed with the instructions above is an OpenLDAP server. In addition to the directory, a phpLDAPadmin server is also deployed to help you configure the directory.

If you'd prefer to use the OpenLDAP command line utilities, they're installed in the OpenLDAP container. These tools are accessible with this command:

  • Linux/macOS:

$ docker exec $(docker ps -f "label=com.docker.swarm.service.name=syncldap_ldap-service" --format '{{.ID}}') LDAPTOOL ARGS
  • Windows:

$ docker exec (docker ps -f "label=com.docker.swarm.service.name=syncldap_ldap-service" --format '{{.ID}}') LDAPTOOL ARGS

Note

The phpLDAPadmin server listens on port 40000, it is important that you do not expose this port to the internet.

The following guides assume that you're using phpLDAPadmin. In order to perform the following operation, please go to https://127.0.0.1:40000 in your browser.

Creating users

  1. Click: login on the left and login as admin.

  2. Expand the tree view on the left until you see ou=people.

  3. Click on ou=people and choose Create a child entry.

  4. Choose the Generic: User Account template.

  5. Fill out the form and click Create Object.

  6. Assign users to groups with these instructions.

Creating groups

  1. Click: login on the left and login as admin.

  2. Expand the tree view on the left until you see ou=groups.

  3. Click on ou=default_prefix and choose Create a child entry.

  4. Choose the Generic: Posix Group template.

  5. Fill out the form and click Create Object.

Note

The group name must start with the group prefix, in this case the group prefix is default_prefix so for example: default_prefix my-new-group

  1. Assign users to groups with these instructions.

Assigning users to groups

  1. Click: login on the right and login as admin.

  2. Expand the tree view on the right until you see ou=default_prefix, then expand ou=default_prefix.

  3. This list is all the groups under ou=default_prefix.

  4. Click on the group that you want to assign users to.

  5. A few groups are created when the LDAP server is brought up, refer to Data Permission Filters for descriptions of these groups.

  6. If the memberUid section is not present:

    1. Choose Add new attribute.

    2. Choose memberUid from the dropdown, then enter uid of the user you want to assign.

    3. Click Update Object at the bottom to update.

  7. If the memberUid section is present,

  1. Navigate to the memberUid section.

  2. Click modify group members to manage members.