Accounts help the system figure out what users and devices exist in the system, whom they belong to, and whether an account is active. An explanation of some of the key ways we use accounts is below.
Accounts are used within the system to keep tenant data independent from other tenants. This allows for common usernames (like "admin") to exist for each account, and also allows for moving individual tenant data without disrupting other tenants.
Account and User Look-up
When a user is logging in, the global accounts database is used to figure out what account they are logging into. To make things easier for users to remember, we utilize a friendly account name, which the user must enter. We then search all documents in the accounts database and compare their "name" field against what was entered. If we find a match and the account is enabled, we lookup the user's credentials in the specific account database.
Device Registration and Outbound Calling
When a device registers or makes a call, the device transmits it's DNS realm to our servers. We utilize the domain name to figure out which account the device belongs to. We then check to make sure the username and password presented by the device match a device document within that specific account.
The process is exactly as shown above except the domain name is used to find the account instead of a friendly account name.
In the above example, we'd use the "realm" field from the account document and match it against the DNS name the phone sends in from it's authentication header or From: header to find the correct account in the database. Then we'd lookup the phone's SIP username and SIP password.
Sample Account Document
Below is an example account document. This would go into the account database itself. In this example:
- The account's ID is 12341234123412341234123412341234
- The friendly name (which users would login with as their "Account Name") is 2600hz Master
- The realm (which devices would use to register) is 2600hz.s.2600hz.com
This document would be stored in two places:
- Within the account itself. This version is considered the master or primary version
- The accounts database (which is used for global lookups). This version is considered a copy
Running your own cluster?
You can manually change account data in the database, but you must make sure the account data exists in both the accounts database and within the database for the account itself. A sample of an account definition document is above.