OX as a Service Provisioning using SOAP
Tutorial: Provision OX as a Service using SOAP
Overview
OX as a Service is using the same code everybody can download and install using our various guides. Since it is a hosted service using a reseller model, the provisioning api is using the Reseller Bundle to extend the usual two administrative layers by an additional one.
Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service is using Dovecot as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms to manage some email specific settings.
Open-Xchange concept of Contexts
In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to name it. In Open-Xchange, we call that a Context. A context is a sealed container for users and groups. Users in a context can not see users of other contexts, not can they share data with users of other contexts (with the exception of Open-Xchange publish and subscribe functionality).
A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited to one domain only.
Open-Xchange concept of provisioning
A plain Open-Xchange installation consists of two administrative levels.
- root level, usually we call that oxadminmaster
- context level
oxadminmaster / root
The root, or oxadminmaster account is used to
- add, remove and configure filestores attached to Open-Xchange
- add, remove and configure databases attached to Open-Xchange
- add, remove and configure contexts
However, it can NOT add or remove users and groups, nor any other data within a context!
Instead, it can change parameters like add/remove domains, change per context filesystem quota, etc.
Context admin
The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit users and groups within Open-Xchange. In addition, it inherits shared data of users, that are deleted.
OX as a Service concept of provisioning
As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would mean if we want resellers to be able to create contexts for their customers, we would have to hand out our root account. Since that is not desirable, we added another layer via the Reseller Bundle as mentioned earlier.
- root level, usually we call that oxadminmaster
- subadmin level
- context level
root and context level don't change, except that context level can be restricted.
The subadmin account can only add, remove or configure contexts. As well as the root account, it can NOT add, remove and configure users within contexts. Contexts created by a subadmin account can not be seen by other subadmin accounts.
Provisioning
Reference implementation
The reference implementation of the European OX as a Service system can be found in the OX as a Service APS package for Parallels Automation.
Workflow
Subadmin credentials
The first requirement is to get subadmin credentials for your company. Please follow the steps documented here to get such an account.
Together with the login and password you will also retrieve the provisioning URL to be used by all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s) that should be allowed to access the provisioning system.
WSDL files
Just point your browser to the provisioning URL you got from us. You will find some services listed there. You will need the following services from that list:
- https://hostname/webservices/OXaaSService?wsdl
- OX as a Service specific functions
- https://hostname/webservices/OXResellerContextService?wsdl
- Context management
- https://hostname/webservices/OXResellerUserService?wsdl
- User management
and optionally
- https://hostname/webservices/OXResellerGroupService?wsdl
- Group management
- https://hostname/webservices/OXResellerResourceService?wsdl
- Resource management
Create a context
Once you have the credentials in place, you are ready to create your first context.
Creating a context requires to create the first user in that context, that is the context admin, see above.
Mandatory settings for a context are
- name
- name of the context
- quota
- file quota in MB for that context (Note: that is file, not mail!)
- brandtaxonomy
- must be set to the login of your subadmin account, see below
Important: In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when your subadmin login is johndoe, the all your context names must start with johndoe_!
Optional settings
- framecolor
- io.ox/dynamic-theme//frameColor
- iconcolor
- io.ox/dynamic-theme//iconColor
- selectioncolor
- io.ox/dynamic-theme//selectionColor
- logowidth
- io.ox/dynamic-theme//logoWidth
- logourl
- io.ox/dynamic-theme//logoURL
- logouturl
- io.ox/core//customLocations/logout, see this section for more information on the settings above
- id
- A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.
userAttributes
The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field. All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like done in OXaaS.
The hash looks like this:
userAttributes => entries => EntryArray with EntryArray := [ { key => "somekey" value => somevalue }, { key => "someotherkey" value => someothervalue }, ... ] somevalue can be an array again, e.g.: somevalue => entries => EntryArray with EntryArray := [ { key => "somekey" value => somevalue }, { key => "someotherkey" value => someothervalue }, ... ] and so on
Example dump using perls Data::Dumper
:
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//selectionColor'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//frameColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//iconColor'
}
]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
Admin User
- name
- login name of the context admin
- password
- password
- email address of the context admin
- displayname
- displayname (usually surname givenname)
- surname
- surname
- givenname
- given name
- lang
- language, e.g. en_GB, en_US, de_DE, ...
- timezone
- Java timezone such as Europe/Berlin,
Timezones
To get a list of all available timezones, you can run this short Java program:
import java.util.TimeZone;
public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}
}
Languages
This is the list of currently supported languages in OXaaS:
ja_JP de_DE es_ES es_MX fr_FR it_IT nl_NL pl_PL zh_TW en_US en_GB
Create users
Creating users requires the following parameters
- name
- login name of the context admin
- password
- password
- email address of the context admin
- displayname
- displayname (usually surname givenname)
- surname
- surname
- givenname
- given name
- lang
- language, e.g. en_GB, en_US, de_DE, ...
- timezone
- Java timezone such as Europe/Berlin,
- moduleaccess
- the module access combination name
- mailquota
- the mail quota of the user in MB
Timezones and languages like documented earlier.
Valid values for moduleaccess are:
- groupware_standard
- groupware_advanced
- groupware_premium
Other settings are not supported.
Workflow
Create the user in Open-Xchange
- Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
- Find the numerical id of the context e.g. in using
OXResellerContextService->getData(name="contextname")
Use the OXResellerUserService->createByModuleAccessName
to create users.
Note: Although there are three create methods in the SOAP user service API, you have to use the method createByModuleAccessName
and specify one of the names listed above.
Set mail quota
- Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
- Find the numerical id of the context e.g. in using
OXResellerContextService->getData(name="contextname")
- Find the numerical id of the user either by using
OXResellerUserService->getData(name="username")
or use/store the return value ofOXResellerUserService->createByModuleAccessName
Use the OXaaSService->setMailQuota
call to set the mail quota for the user created above.
OXaaS specific methods
- getQuotaUsage
- createSharedDomain
- existsLogin
- createDomainCatchall
- getQuotaUsagePerUser
- listDomainCatchalls
- existsMailAlias
- setMailQuota
- deleteDomainCatchall
Code Examples
Java
Generating the SOAP client
Since Open-Xchange is using Apache CXF to for SOAP, we recommend to use the wsdl2java code generator from that package.
The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little complex.
In OXaaS we need at least three services in order to create contexts and users:
- OXResellerContextService
- OXResellerUserService
- OXaaSService
The shell script below generates the stubs of these three services into the directory defined in the CODEBASE variable. In addition, you have to set WSDLURL to point it to the provisioning URL you will get from us as mentioned earlier.
Just cut&paste the shell script below into a file and run it using the bash shell.
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.0.0-milestone1.tar.gz; cd apache-cxf-3.0.0-milestone1
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/j2sdk1.7-oracle/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"
rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb
JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF
pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl
pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl
pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl
rm -f $JAXBTMP
When you generate the code into an existing eclipse project, you should have three main packages as shown in the image below
Example Client
Context creation
package com.openexchange.oxaas.myclient;
import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;
/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {
private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
public static void main(String[] args) {
final String subadminname = "vpnpoa";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";
Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
creds.setLogin(subadminname);
creds.setPassword(subadminpw);
SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);
SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();
Entry selectionColor = new Entry();
selectionColor.setKey("io.ox/dynamic-theme//selectionColor");
selectionColor.setValue("#0000ff");
Entry frameColor = new Entry();
frameColor.setKey("io.ox/dynamic-theme//frameColor");
frameColor.setValue("#ff0000");
Entry iconColor = new Entry();
iconColor.setKey("io.ox/dynamic-theme//iconColor");
iconColor.setValue("#00ff00");
configEntries.getEntries().add(selectionColor);
configEntries.getEntries().add(frameColor);
configEntries.getEntries().add(iconColor);
config.setValue(configEntries);
SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);
ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);
final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");
try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds);
System.out.println("created context with id=" + ret.getId());
System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}
System.in.read();
System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}
}
User creation
package com.openexchange.oxaas.myclient;
import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;
/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {
private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");
public static void main(String[] args) {
final String subadminname = "vpnpoa";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";
Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();
OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();
// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);
creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);
final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");
try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());
// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());
// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);
// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}
System.in.read();
System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}
}