diff --git a/jams/images/jams-hero.png b/jams/images/jams-hero.png index 755ee1c60fc418b5e0114a48421f9605b257cf26..a1ba6ebccabbd182f96a5dd2ca5bc0e84f15529e 100644 Binary files a/jams/images/jams-hero.png and b/jams/images/jams-hero.png differ diff --git a/jams/index.md b/jams/index.md index bbdc1d4ae809af0162b4a02b8552941518c259e6..1fdd23fb24cd93c3d685910c64e3be9450695896 100644 --- a/jams/index.md +++ b/jams/index.md @@ -6,7 +6,8 @@ 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. -For a downloadable version of the JAMS manual (PDF), click [here](jams-manual.pdf) +Downloadable JAMS manual: +* [JAMS manual (English, PDF format)](manual/jams-en.pdf). ## Additional guides @@ -17,55 +18,36 @@ client admin ``` -## Getting started +## Introduction 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), -1. Active Directory (AD), and -1. An embedded database. - +2. Active Directory (AD), and +3. An embedded database. ### Obtaining JAMS The latest version of JAMS can be downloaded at [https://jami.biz/](https://jami.biz/). The source code is available at [https://git.jami.net/savoirfairelinux/jami-jams](https://git.jami.net/savoirfairelinux/jami-jams). - ### System requirements -<table> - <tr> - <td align="left">Processor</td> - <td align="left">1 gigahertz (GHz) or faster with 1 or more cores on a compatible 64-bit processor or System on a Chip (SoC).</td> - </tr> - <tr> - <td align="left">RAM</td> - <td align="left">4 gigabytes (GB)</td> - </tr> - <tr> - <td align="left">Storage</td> - <td align="left">1 gigabyte (GB) of available storage space</td> - </tr> - <tr> - <td align="left">Operating system</td> - <td align="left">GNU/Linux, macOS, or Windows</td> - </tr> - <tr> - <td align="left">Java</td> - <td align="left">Version 11 or higher</td> - </tr> - <tr> - <td align="left">Database</td> - <td align="left">LDAP-compatible directory (such as OpenLDAP), Microsoft Active Directory (AD), or a local embedded database</td> - </tr> -</table> +| Requirement | Details | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| **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, Apple macOS, or Microsoft Windows. | +| **Java** | Version 11 or higher. | +| **Database** | LDAP-compatible directory (such as [OpenLDAP](https://www.openldap.org/)), 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](https://en.wikipedia.org/wiki/X.509) certificate management workflows. The central concepts that are used in JAMS are: + * the [Certification Authority (CA)](https://en.wikipedia.org/wiki/Certificate_authority) and * the [Certificate Signing Request (CSR)](https://en.wikipedia.org/wiki/Certificate_signing_request). @@ -80,7 +62,6 @@ 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/](https://jami.biz/). @@ -100,25 +81,34 @@ In order to generate a pair of key certificates, **Certbot** can be used followi Certbot will provide specific instructions when the web server software and operating system are entered. -Install Certbot using snap: -`sudo snap install --classic certbot` +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` +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` +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. +```{admonition} Current limitation +JAMS currently does not support reading encrypted private keys that 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` +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 | | ----------------------- | -------------------------------------------------------------------------------------------------- | @@ -126,53 +116,50 @@ It is required to copy them in the current folder where the `jams-launcher.jar` | **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` +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 +### Step 2: Set up 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. +```{important} +A CA is not a server SSL certificate; it is a certificate that 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: +This certificate will be used to sign the enrollment requests that 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/> +* <https://cheapsslsecurity.com/blog/understanding-the-role-of-certificate-authorities-in-pki/> - -### Step 3: Setup the user database +### Step 3: Set up the user database JAMS supports 3 different sources for the authentication of users: -1. LDAP-compatible directory (such as OpenLDAP) +1. LDAP-compatible directory (such as [OpenLDAP](https://www.openldap.org/)) 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. +If the enterprise provides an LDAP directory for user management, it is required to know its access information and an automated account that has read-only rights to do use look-ups. ") @@ -185,12 +172,11 @@ The admin should provide most of this information; however, below is a detailed | **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`. | - +| **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. +If the enterprise provides Active Directory (AD) for user management, it is required to know its access information and an automated account that has read-only rights to do use look-ups. ") @@ -199,24 +185,25 @@ The admin should provide most of this information; however, below is a detailed | 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. | +| **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. +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:** +```{admonition} 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. +Jami usernames of JAMS users will not be stored on the public Jami name server. +Users can communicate with users outside the organization by using their 40-character fingerprint. +Enable this option to allow JAMS users in the organisation to also search for external users on the public name server, +``` ### Step 4: Setup the server parameters @@ -229,16 +216,15 @@ If you want your users to be searchable by external users and allow them to comm | **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. +```{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 address as the one where JAMS is deployed. +Only set a different URL address if the Web UI has a different URL address from the one where JAMS is deployed. +``` -Click on "Set Server Parameters" to finalize the configuration. -You will be redirected to the JAMS interface. +Click on "Set Server Parameters" to finalize the configuration and 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". \ No newline at end of file +The JAMS has been configured the an LDAP database or Active Directory, the list of users in the organization should be visible in JAMS. +If JAMS has been configured with an local embedded database, new users can be created by clicking on "Create User". \ No newline at end of file diff --git a/jams/jams-manual.pdf b/jams/manual/jams-en.pdf similarity index 100% rename from jams/jams-manual.pdf rename to jams/manual/jams-en.pdf