How can we help?




Follow

Webmail Admin API

Stewart -

PROBLEM

How do I use the webmail admin API? 

ENVIRONMENT

  • atmail suite - Webmail Admin API

CAUSE

I want to utilize the functionality of my atmail webmail admin API.

RESOLUTION

Installation

Install RPM package

Pre-requirement: atmail RPM repo must be configured properly

Webmail Admin API is recommended to be installed on the same machine where JMAP API service (a.k.a apiserver) is running.

yum install atmail-webmail-admin-<version>

Update config file

Config file default location is /etc/atmail/api/webmail-admin.yaml . Below is a minimal config example:

The database user that Webmail Admin API uses needs to have full privileges granted.

listen: 127.0.0.1:8080
key-file: /etc/atmail/api/.keyring
db: root:changeme@tcp(127.0.0.1:3306)/apiserver

tls:
  enable: false
  key: ''
  cert: ''

log:
  level: info
  json: true

syslog:
  enable: true

key-file should be the same file used in apiserver .

Note: Simply set tls.enable: true may not work. Please refer to next secion ‘Using on Production’ for more details on using TLS.

More configurations can be listed via command webmail-admin --help

   --config FILE, -c FILE                            Load configuration from FILE [$CONFIG_FILE]
   --db value                                        mariadb db dsn [$DB]
   --default-hash value                              Set a valid hasher (default: "SSHA512") [$DEFAULT_HASH]
   --key-file value                                  Location of the webmail-api db encryption keys (default: "/etc/atmail/api/.keyring") [$KEY_FILE]
   --listen ADDR, -l ADDR                            listen on ADDR (default: "127.0.0.1:8080") [$LISTEN]
   --log.json, --log-json                            output logs in json format (default: false) [$LOG_JSON]
   --log.level value, --log-level value              Log Level (panic,fatal,error,warn,info,debug,trace) (default: "info") [$LOG_LEVEL]
   --metrics ADDR                                    expose prometheus metrics on ADDR [$METRICS_ADDR]
   --syslog.addr value, --syslog-addr value          syslog server. Value can be host:port. If not set, uses local syslog [$SYSLOG_ADDR]
   --syslog.enable, --syslog                         enable syslog (default: false) [$SYSLOG_ENABLE]
   --syslog.facility value, --syslog-facility value  syslog facility keyword (default: "daemon") [$SYSLOG_FACILITY]
   --tls.cert value, --tls-cert value                TLS certificate file path. The file must contain PEM encoded data. [$TLS_CERT_FILE]
   --tls.enable, --tls                               enable TLS (default: false) [$ENABLE_TLS]
   --tls.key value, --tls-key value                  TLS key file path. The file must contain PEM encoded data. [$TLS_KEY_FILE]
   --verbose, -V                                     verbose log mode (default: false) [$VERBOSE]
   --help, -h                                        show help (default: false)
   --version, -v                                     print the version (default: false)

Manage Service

Start Service

systemctl start atmail-webmail-admin
systemctl enable atmail-webmail-admin

Check Service Status

systemctl status atmail-webmail-admin

Setup Admin API User

You will need to use an API user with admin privleges, below are instructions on how to provision that user, this will create the credentials to use in placement of admin:changeme

source /etc/profile.d/atmail-apiadmin.sh

apiadmin user add --role=admin <USERNAME> <PASSWORD>

Test Service

curl -u admin:changeme http://localhost:8080/admin/v2/users?limit=1

Do not use a mailserver admin credential here. It should be apiserver users with admin role.

Using on Production

When using on production, HTTPS protocol should be used instead of HTTP. There are two ways to enable HTTPS support:

  • Using Nginx for HTTPS

  • Enable TLS in Webmail Admin API

  • Combine Both Above

Using Nginx for HTTPS

Nginx reverse proxy is the recommended way to handle HTTPS requests.

Below is an example config (filename atmail-webmail-admin.locations). It can be put into /etc/nginx/conf.d directory on the same machine Webmail Admin API is running.

        location /admin/v2/ {

                proxy_set_header        Host $host;
                proxy_set_header        X-Real-IP $remote_addr;
                proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header        X-Forwarded-Proto $scheme;
                proxy_set_header        X-Forwarded-Referer $http_referer;

                proxy_pass              http://127.0.0.1:8080/admin/v2/;
                proxy_read_timeout      90;
                proxy_redirect          default;
        }

With the config file name of atmail-webmail-admin.locations you must edit /etc/nginx/conf.d/atmail.conf and change the line

include /etc/nginx/conf.d/atmail-webmail.*locations;

to

include /etc/nginx/conf.d/atmail-webmail*locations;

so that both the existing atmail-webmail.locations file and the new atmail-webmail-admin.locations file are loaded by NGINX

If you are using domain.name to access the api you will need to change the listener in /etc/atmail/api/webmail-admin.yaml from just the localhost to the network card so from

listen: 127.0.0.1:8080

to

listen: 0.0.0.0:8080

Restart nginx

systemctl restart nginx

Then test with below command

curl -u admin:changeme https://<domain.name>/admin/v2/users?limit=1

Enable TLS in Webmail Admin API

Webmail Admin API can also handle HTTPS request, which is not enabled by default. To enable this feature, modify the tls section in webmail-admin.yaml config file:

...
tls:
  enable: true
  key: path/to/your.key
  cert: path/to/your.crt

key: TLS key file path. The file must contain PEM encoded data.

cert: TLS certificate file path. The file must contain PEM encoded data.

Both the private key and pem should be owned by atmail:atmail so webmail-admin-api has permissions to access these files. I recommend creating /etc/pki/atmail/ and copying the existing certs into this directory before changing their ownership.

Restart Webmail Admin API

systemctl restart atmail-webmail-admin

Then test with below command, assuming a self-signed certificate is used here:

curl -k -u admin:changeme https://localhost:8080/admin/v2/users?limit=1

The above -k parameter is to allow self-signed certificates.

Combine Both Above

If you need both above, that nginx listen on 443 and reverse proxy to webmail-admin API 8080 with TLS enabled, then you need to make sure that:

In nginx config, it should use https instead of http

proxy_pass              https://127.0.0.1:8080/admin/v2/;

You may also need tweak some related options. For more details please refer to NGINX Docs | Securing HTTP Traffic to Upstream Servers

API Reference

Webmail Admin API Reference

Quick Guide For Sharing Email Access

Shared Account Creation

Below is a quick guide for creating shared access on a primary email account with different webmail logins.

Create Department Email Account

Firstly, create a department email account via mailserver admin panel. (assuming email address is electronics.store1@domain.com ). Then login into webmail with this email account to finalize the provisioning, and make sure it works.

Note: the user object has a syncPassword property, which controls whether or not the user is linked to a backend (mailserver) user. When apiserver provision a user from mail server, it will set this property to true.

To create a team member account, this property needs to be false. (When omit in API, it will be default to false). If this property is set to true to a team member user, then an error will be triggered when this user tries to change password via webmail account settings.

Create Team Member Account and Associate to Department Account

Since webmail accounts need to share the same service accounts with the department email account, we need to get these service account ids first.

curl -u admin:changeme http://localhost:8080/admin/v2/users?username=electronics.store1 | jq
[
  {
    "id": 10,
    "username": "electronics.store1@domain.com",
    "dateModified": "2019-04-09T15:25:02Z",
    "dateCreate": "2018-01-01T00:00:00Z",
    "syncPassword": true
  }
]

jq is a json formatter to format the json output, which is optional.

Then list accounts under the user

curl -u admin:changeme http://localhost:8080/admin/v2/users/10/accounts | jq
[
  {
    "userId": 10,
    "name": "electronics.store1@domain.com",
    "isPrimary": true,
    "isReadOnly": true,
    "active": true,
    "mailId": 109,
    "contactsId": 110,
    "calendarsId": 111,
    "filestoreId": 112,
    "id": 31
  }
]

Write down the values of mailId , contactsId , calendarsId , filestoreId.

Now create a new webmail user

curl -u admin:changeme http://localhost:8080/admin/v2/users -XPOST -d '{"username":"fred@domain.com","password":"changeme"}'
{"id":39}

Then create account under user (id=39)

curl -u admin:changeme http://localhost:8080/admin/v2/users/39/accounts -XPOST -d '{"name":"Work",  "isPrimary": true, "active": true, "mailId": 109, "contactsId": 110, "calendarsId": 111,  "filestoreId": 112}'
 {"id",38}

A user can have multiple accounts, but one of account can be primary, which is used to fetch email on webmail login.

If you need to create multiple accounts, please make sure isPrimary property is correct.

Then create a default identity for this account. This step cannot be skipped.

curl -u admin:changeme http://localhost:8080/admin/v2/users/39/accounts/38/identities -XPOST -d '{"email":"electronics.store1@domain.com"}'
{"id":38}

Login to Webmail with new Account

Now the new account fred@domain.com is ready for webmail login.

Team Member Account Modification

Assuming a team member moves department from electronics (electronics.store1@domain.com) to hardware (hardware.store1@domain.com)

Get service accounts

Similar to listing service accounts on electronics.store1@domain.com, now list services account on hardware.store1@domain.com, and get values of mailId , contactsId , calendarsId , filestoreId

curl -u admin:changeme http://localhost:8080/admin/v2/users?username=hardware.store1
...
curl -u admin:changeme http://localhost:8080/admin/v2/users/{userId}/accounts
...

Update existing team member account with new mailId , contactsId , calendarsId , filestoreId.

curl -u admin:changeme http://localhost:8080/admin/v2/users/39/accounts/38 -XPUT -d '{"name":"Work",  "isPrimary": true, "active": true, "mailId": 149, "contactsId": 150, "calendarsId": 151,  "filestoreId": 152}'

According to REST API specs, PUT methods replaces the target resource. If any fields is omit, I will be set to empty value in DB, which may lead to unexpected behaviour. Therefore, A GET method is required to fetch the resource first, and then send back with modified values.

Team Member Account removal

It is safe to remove any team member account via Webmail-Admin API. The shared department service accounts won’t be removed. Below command will remove user (id=39) as well as accounts and identities under this user, but won’t service accounts

curl -u admin:changeme http://localhost:8080/admin/v2/users/39 -XDELETE

If delete the department email user with this command, it will delete the webmail login, but won’t delete the service accounts. However, when logging to webmail with this account, a new copy of this email username along with another copy of service accounts will be automatically provisioned because of webmail auto provisioning feature. In order to remove the shared email account, refer to next session

Shared Account Removal

Before Remove Shared Accounts, all team member accounts must be removed first.

Mailserver doesn’t understand team member webmail accounts.

Deleting shared account in mailserver before deleting all team member accounts may cause ApiServer fail to deprovision webmail and DAV accounts, and results in inconsistent data

Get a Service Account

curl -u admin:changeme http://localhost:8080/admin/v2/users?username=hardware.store1
...
curl -u admin:changeme http://localhost:8080/admin/v2/users/{userId}/accounts
[{
   ...
   mailId: 109
}]

Delete Team Member Users

Any of serviceAccountId can be used to filter users

curl -u admin:changeme http://localhost:8080/admin/v2/users?serviceAccountId=109

Use Delete User API to delete each user EXCEPT the shared account user.

loop {
curl -u admin:changeme http://localhost:8080/admin/v2/users/{id} -XDELETE
}

Remove Shared Account From Mailserver

Now that all team member accounts have been removed. You can delete the shared email account in mailserver as normal.

One User with Multiple Accounts

A team member user can have multiple department accounts. Assuming frad@domain.com need to have access to both electronics.store1@domain.com and hardware.store1@domain.com

Step 1: Create team member user and add first department server account

Follow Share Account Creation section to create team member and assign service accounts.

Step 2: Add addtional service account

Get service accounts 2nd department account

List services account on hardware.store1@domain.com, and get values of mailId , contactsId , calendarsId , filestoreId

curl -u admin:changeme http://localhost:8080/admin/v2/users?username=hardware.store1
...
curl -u admin:changeme http://localhost:8080/admin/v2/users/{userId}/accounts
...

Create A new account under user fred (id=39)

curl -u admin:changeme http://localhost:8080/admin/v2/users/39/accounts -XPOST -d '{"name":"Hardware",  "isPrimary": false, "active": true, "mailId": 149, "contactsId": 150, "calendarsId": 151,  "filestoreId": 152}'
 {"id",50}

Now user fred will have access to both electronics and hardware service accounts.

Repeat Step2 to add any additional accounts.

Comments


Contact our support team


+61 (7) 5357 6605       support@atmail.com