JAMS manual

The JAMS manual contains user guides for the Jami Account Management Server. The Jami Account Management Server (JAMS) enables Jami to be easily deployed in any enterprise and allows users to connect using their centralized credentials and create local accounts. JAMS allows all enterprises to manage their own Jami community while taking advantage of Jami’s distributed network architecture.

Additional guides

• Client guide
• Admin guide

Getting started

JAMS is a server application used to enroll Jami clients in an enterprise environment. Currently, JAMS supports 3 sources for user authentication:

1. Lightweight Directory Access Protocol (LDAP),

2. Active Directory (AD), and

3. An embedded database.

Obtaining JAMS

The latest version of JAMS can be downloaded at https://jami.biz/. The source code is available at https://git.jami.net/savoirfairelinux/jami-jams.

System requirements

Processor	1 gigahertz (GHz) or faster with 1 or more cores on a compatible 64-bit processor or System on a Chip (SoC).
RAM	4 gigabytes (GB)
Storage	1 gigabyte (GB) of available storage space
Operating system	GNU/Linux, macOS, or Windows
Java	Version 11 or higher
Database	LDAP-compatible directory (such as OpenLDAP), Microsoft Active Directory (AD), or a local embedded database

JAMS concepts

JAMS was built with security in mind; therefore, it is intimately related to the X.509 certificate management workflows.

The central concepts that are used in JAMS are:

• the Certification Authority (CA) and

• the Certificate Signing Request (CSR).

In the JAMS paradigm, a device (Jami client) requests a certificate from the server and then presents it to other devices to be recognized as a valid member of the organization. Therefore, JAMS must be provided with a certificate authority in order to work properly.

In order to be completely secure, JAMS does not generate certificates for devices. JAMS instead issues certificates based on a certificate signing request sent to it by the device. This therefore removing the requirement to send a private key over the wire.

The diagram below shows the entire process of how a device enrolls with JAMS:

Getting started

1. Download the latest version of JAMS from https://jami.biz/.

2. Unpack the .tar file to any directory.

3. It is mandatory to run JAMS using a secure SSL connection.

A domain name is required to request a key and a certificate. A domain name can be purchased if one is not available. Set the domain name to point to the server before proceeding to the next step.

A pair of key certificates can be purchased from any online provider. However, obtaining a free pair using Let’s Encrypt is recommended.

In order to generate a pair of key certificates, Certbot can be used following the instructions on the https://certbot.eff.org/ page.

Certbot will provide specific instructions when the web server software and operating system are entered.

Install Certbot using snap:
sudo snap install --classic certbot

Ensure that the Certbot command can be run:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

In order to get a certificate execute:
sudo certbot certonly
and follow the instructions.

The certificate and key are generated in a specific folder; please see the output from Certbot to locate them.

It is required to copy them in the current folder where the jams-launcher.jar file is located.

Current limitation: JAMS does not support reading encrypted private keys which require a password unlock.

4. Navigate to the directory where the JAMS package has been extracted and execute the following command:
   java -jar jams-launcher.jar PORT SSL_CERTIFICATE SSL_CERTIFICATE_KEY

Argument	Details
PORT	The TCP port on which JAMS is to listen for incoming connections.
SSL_CERTIFICATE	The location of the PEM-formatted SSL Certificate file.
SSL_CERTIFICATE_KEY	The location of the PEM-formatted key file which is used with the SSL Certificate file from above.

An example of the command would be:
java -jar jams-launcher 443 server.pem server.key

Please note that any port above 1024 can be safely used to run JAMS.

Step 1: Create administrator account

This account will have administrative control and the rights to manage the users and groups of Jami users.

Step 2: Setup the Certification Authority

The second step is to define the Certification Authority.

[!IMPORTANT]

A CA is not a server SSL certificate, it is a certificate which has the power to issue other certificates. Do not use the import option unless the enterprise’s security officer has issued the CA certificate. Most commercially available certificates (i.e., those issued by GoDaddy, Let’s Encrypt, etc…) are not CA certificates. It is highly recommended that end-users create and use a self-signed CA as providing an incorrect certification type will lead to a non-functional server.

This certificate will be used to sign the enrollment requests which come from Jami devices. It is highly recommended that the following articles are read to become familiar with the X.509 certificate standard processes and practices:

• https://www.securew2.com/blog/public-key-infrastructure-explained/

• https://cheapsslsecurity.com/blog/understanding-the-role-of-certificate-authorities-in-pki/

Step 3: Setup the user database

JAMS supports 3 different sources for the authentication of users:

1. LDAP-compatible directory (such as OpenLDAP)

2. Microsoft Active Directory

3. Local embedded database

Option 1: Lightweight Directory Access Protocol (LDAP)

If the enterprise provides LDAP directory for user management, it is required to know its access information and an automated account which has read-only rights to do use look-ups.

The admin should provide most of this information; however, below is a detailed overview of each field:

Field	Details
Use StartTLS	The LDAP server can be configured to use either TLS/STARTTLS or PLAIN sockets; if STARTTLS is used, mark this as true.
Server Address	The address of the server with respect to the JAMS server, the LDAP is not required to be publicly accessible but should be accessible to JAMS. Either ldap:// or ldaps:// should precede the address.
Port	The port on which the LDAP server is listening for requests (usually 389 for PLAIN/STARTTLS and 636 for SSL/TLS).
Administrator Username	This is NOT the LDAP’s administration account credentials but the credentials of the account that has read permissions to the LDAP database in order to look up users. The format is generally cn=bot,ou=robots,dc=domain,dc=org.
Password	The password used by the account above.
BaseDN	The base realm where the user accounts are located, in most cases it is ou=users,dc=enterprise,dc=org.

Option 2: Microsoft Active Directory (AD)

If the enterprise provides Active Directory (AD) for user management, it is required to know its access information and an automated account which has read-only rights to do use look-ups.

The admin should provide most of this information; however, below is a detailed overview of each field:

Field	Details
Port	The port on which Active Directory (AD) is listening (generally it is either 389 or 636).
Host	The address of the server with respect to the JAMS server, the Active Directory (AD) it not required to be publicly accessible but should be accessible to JAMS.
Administrator Username	This is NOT the Active Directory’s administration account credentials but the credentials of the account that has read permissions to the Active Directory database in order to look up users. The format is generally cn=bot,ou=robots,dc=domain,dc=net.
Password	The password used by the account above.
Use SSL	Whether this server uses SSL for data transmission.
Domain Name	This is the legacy-formatted Windows Domain Name (i.e., WINDOMAIN).

Option 3: Local embedded database

The local database does not require any additional configuration, everything in the process is automated. This option allows for the creation of Jami users on the fly directly from the JAMS interface.

Advanced settings: By default, the “Use public name server” option is disabled. Usernames of your Jami users will not be stored on the public Jami name server and your users will only be able to communicate with users from your organization. If you want your users to be searchable by external users and allow them to communicate with any Jami user, and not only the one from your organization, enable this option.

Step 4: Setup the server parameters

Parameter	Details
CORS Domain Name	The domain on which the JAMS client and administration UI will be running.
Certificate Revocation List Lifetime	The frequency at which the CRL is updated in memory.
Device Lifetime	How long a device’s certificate is valid before being considered stale and requiring re-enrollment.
User Account Lifetime	How long a user account is valid before being considered stale and requiring re-enrollment.

[!IMPORTANT]

The CORS Domain Name corresponds to the web address used to access the Web UI. By default, it is set to the same URL as the one where you deploy JAMS. Only set a different URL if the Web UI has a different URL to the one where JAMS is deployed.

Click on “Set Server Parameters” to finalize the configuration. You will be redirected to the JAMS interface.

If you have configured JAMS with your LDAP or Active Directory, the list of users should of your organization should be visible in JAMS. If you have selected the local embedded database, you can now start creating new users by clicking on “Create User”.