Create a Tenant
Create a tenant and configure the runtime aspects of the account. When designing the tenant using the API, use the same background information and guidance that is provided in the Deep Security Help Center.
Synchronous and asynchronous tenant creation
When you create a tenant, you can make an asynchronous (default behavior) or synchronous call.
- Asynchronous: The response is returned immediately when the tenant creation has started. The tenant is in the Created state but it is not yet functional because Deep Security Manager is in the process of creating the tenant database.
- Synchronous: The response is returned when tenant creation is complete. The tenant database is created and the tenant is fully operational. Tenant database creation can require several minutes, depending on server resources.
When tenant creation is complete, the tenant state is either Confirmation Required (the administrator needs to respond to a confirmation email) or Active (no confirmation was required). You are able authenticate and interact with the tenant only when it is active. Therefore, if you create the tenant synchronously with no confirmation required, you can interact with the tenant immediately after you receive the response.
Use an asynchronous call in the following situation:
- You do not need to immediately perform operations on the created tenant
- You want to quickly free up the execution thread
Use a synchronous call in the following situation:
- You need to perform tasks on the tenant immediately after it is created
- You can allow your script to block the execution thread for several minutes
Response object
The response to the tenant creation call includes a Tenant object that represents the new tenant. However, the object that is returned to an asynchronous call contains only a subset of all the tenant properties.
This JSON represents the data structure of a Tenant that is returned for an asynchronous call. The tenantState
is created
, and the tenant administrator account is omitted:
{ "databaseServerID": 0, "name": "test tenant", "description": "Test tenant created asynchronously", "agentInitiatedActivationPassword": "F5240072-399D-8371-B974-BCBA6AB6BCAB", "timeZone": "UTC", "locale": "en-US", "demoMode": false, "modulesVisible": [ "all" ], "hideUnlicensedModules": true, "tenantState": "created", "guid": "37DF7B64-FB78-2D83-C074-375D611E2C9C", "ID": 2 }
This JSON represents the data structure of a Tenant that is returned for a synchronous call. In the data structure, administrator accounts are associated with the primaryContacts
key. In this case, no confirmation from the administrator was required, so the tenantState
is active
:
{ "databaseServerID": 0, "name": "test tenant 2", "description": "Test tenant created synchronously", "agentInitiatedActivationPassword": "F91F7E62-1FEC-65E1-F79D-9EC01C365A35", "timeZone": "UTC", "locale": "en-US", "demoMode": false, "modulesVisible": [ "all" ], "hideUnlicensedModules": true, "tenantState": "active", "primaryContacts": [ { "username": "MasterAdmin", "roleID": 1, "emailAddress": "me@example.com", "ID": 1 } ], "guid": "51D38CD8-F489-CCA5-A304-452DE2F8CC57", "ID": 1 }
General steps
Use the following steps to create a tenant:
- Create an
Administrator
object with, at a minimum, the user name, password, and email address defined. - Create a
Tenant
object, add theAdministrator
object, and set the property values that control the runtime aspects of the account:- The tenant account name
- The security modules are visible to them in Deep Security Manager
- The database server to use (if Deep Security Manager uses multiple databases)
- Locale and location details
- Use a
TenansApi
object to create the tenant on Deep Security Manager. Indicate whether the call is synchronous (it is asynchronous by default), and whether a confirmation email is sent to the administrator.
- User name
- Password
- Time format
- Timezone
- Role
- All boolean properties
For example, the following code creates anAdministrator
object with the required properties:
admin = api.Administrator() admin.username = "TenantAdmin" admin.password = "Pas$w0rd" admin.email_address = "example@email.com" admin.receive_notifications = "false" admin.role_id = 1
const admin = new api.Administrator(); admin.username = "MasterAdmin"; admin.password = "P@55word"; admin.emailAddress = "example@email.com"; tenant.administrator = admin;
Administrator admin = new Administrator(); admin.setUsername("MasterAdmin"); admin.setPassword("P@55word"); admin.setEmailAddress("bad@email.com");
Next, a Tenant
object is created and the administrator is added:
tenant = api.Tenant(administrator=admin)
const tenant = new api.Tenant(); tenant.administrator = admin;
Tenant tenant = new Tenant(); tenant.setAdministrator(admin);
You can specify which security modules are visible to the tenant. In this example, the Anti-Malware, Firewall, and Intrusion Prevention modules are made visible:
modules = api.Tenant.modules_visible = ["anti-malware", "firewall", "intrusion-prevention"] tenant.modules_visible = modules
tenant.modulesVisible = [ api.Tenant.ModulesVisibleEnum["anti-malware"], api.Tenant.ModulesVisibleEnum.firewall, api.Tenant.ModulesVisibleEnum["intrusion-prevention"] ];
List<ModulesVisibleEnum> modules = new ArrayList<>(); modules.add(ModulesVisibleEnum.ANTI_MALWARE); modules.add(ModulesVisibleEnum.FIREWALL); modules.add(ModulesVisibleEnum.INTRUSION_PREVENTION); tenant.setModulesVisible(modules);
You must specify the account name and locale:
tenant.name = account_name tenant.locale = "en-US"
tenant.name = accountName; tenant.locale = api.Tenant.LocaleEnum["en-US"];
tenant.setName(accountName); tenant.setLocale(Tenant.LocaleEnum.EN_US);
Finally, create the tenant on Deep Security Manager.
tenants_api = api.TenantsApi(api.ApiClient(configuration)) returned_tenant = tenants_api.create_tenant(tenant, api_version, confirmation_required=False, asynchronous=True)
const tenantsApi = new api.TenantsApi(); return tenantsApi.createTenant(tenant, apiVersion, { confirmationRequired: "false", asynchronous: "true" });
TenantsApi tenantsApi = new TenantsApi(); Boolean confirmationRequired = Boolean.FALSE; Boolean asynchronous = Boolean.TRUE; Boolean bypassTenantCache = Boolean.TRUE; Tenant returnedTenant = tenantsApi.createTenant(tenant, bypassTenantCache, confirmationRequired, asynchronous, apiVersion);
Example
The following example creates the tenant asynchronously and bypasses the tenant cache. Also, an email confirmation is not sent to the administrator so that the tenant is activated as soon as it is in the Active state.
# Define the administrator account admin = api.Administrator() admin.username = "TenantAdmin" admin.password = "Pas$w0rd" admin.email_address = "example@email.com" admin.receive_notifications = "false" admin.role_id = 1 # Create a tenant tenant = api.Tenant(administrator=admin) # Set the visible modules modules = api.Tenant.modules_visible = ["anti-malware", "firewall", "intrusion-prevention"] tenant.modules_visible = modules # Set the account name tenant.name = account_name # Set the locale and description tenant.locale = "en-US" tenant.description = "Test tenant." # Create the tenant on Deep Security Manager tenants_api = api.TenantsApi(api.ApiClient(configuration)) return tenants_api.create_tenant(tenant, api_version, confirmation_required=False, asynchronous=True)
// Tenant object const tenant = new api.Tenant(); // Set the visible modules tenant.modulesVisible = [ api.Tenant.ModulesVisibleEnum["anti-malware"], api.Tenant.ModulesVisibleEnum.firewall, api.Tenant.ModulesVisibleEnum["intrusion-prevention"] ]; // Set the account name tenant.name = accountName; // Define the administrator account const admin = new api.Administrator(); admin.username = "MasterAdmin"; admin.password = "P@55word"; admin.emailAddress = "example@email.com"; tenant.administrator = admin; // Set the locale and description tenant.locale = api.Tenant.LocaleEnum["en-US"]; tenant.description = "Test tenant."; // Creates the tenant const createTenant = () => { const tenantsApi = new api.TenantsApi(); return tenantsApi.createTenant(tenant, apiVersion, { confirmationRequired: "false", asynchronous: "true" }); }; createTenant() .then(newTenant => { resolve(newTenant.ID); }) .catch(error => { reject(error); });
// Create and configure a Tenant object Tenant tenant = new Tenant(); // Set module visibility List<ModulesVisibleEnum> modules = new ArrayList<>(); modules.add(ModulesVisibleEnum.ANTI_MALWARE); modules.add(ModulesVisibleEnum.FIREWALL); modules.add(ModulesVisibleEnum.INTRUSION_PREVENTION); // Administrator account Administrator admin = new Administrator(); admin.setUsername("MasterAdmin"); admin.setPassword("P@55word"); admin.setEmailAddress("bad@email.com"); tenant.setName(accountName); tenant.setLocale(Tenant.LocaleEnum.EN_US); tenant.setDescription("Test tenant."); tenant.setAdministrator(admin); tenant.setModulesVisible(modules); // Add the tenant to the manager TenantsApi tenantsApi = new TenantsApi(); Boolean confirmationRequired = Boolean.FALSE; Boolean bypassTenantCache = Boolean.TRUE; Boolean asynchronous = Boolean.TRUE; return tenantsApi.createTenant(tenant, bypassTenantCache, confirmationRequired, asynchronous, apiVersion);
Also see the Create a Tenant operation in the API Reference. For information about authenticating API calls, see Authenticate with Deep Security Manager.