Skip to content
Snippets Groups Projects
Commit 4465eafa authored by ovari's avatar ovari Committed by Adrien Béraud
Browse files

jams/index.md: table, note, cleanup 

Change-Id: I0073dc3e435219914c542a83ffde2d5376f777ad
parent db32d767
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 142 additions and 50 deletions
jams/index.md
+ 142
− 50
View file @ 4465eafa
......@@ -8,8 +8,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.
Downloadable JAMS manual:
* [JAMS manual (English, PDF format)](manual/jams-en.pdf).
Downloadable JAMS manuals:
* [en (English), PDF format](manual/jams-en.pdf).
## Additional guides
......@@ -30,8 +30,8 @@ Currently, JAMS supports 3 sources for user authentication:
### 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).
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
......@@ -44,28 +44,28 @@ The source code is available at [https://git.jami.net/savoirfairelinux/jami-jams
</thead>
<tbody>
<tr>
<td><strong>Processor</strong></td>
<td>**Processor**</td>
<td>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><strong>RAM</strong></td>
<td>**RAM**</td>
<td>4 gigabytes (GB).</td>
</tr>
<tr>
<td><strong>Storage</strong></td>
<td>**Storage**</td>
<td>1 gigabyte (GB) of available storage space.</td>
</tr>
<tr>
<td><strong>Operating system</strong></td>
<td>**Operating system**</td>
<td>GNU/Linux, Apple macOS, or Microsoft Windows.</td>
</tr>
<tr>
<td><strong>Java</strong></td>
<td>**Java**</td>
<td>Version 11 or higher.</td>
</tr>
<tr>
<td><strong>Database</strong></td>
<td>LDAP-compatible directory (such as <a href="https://www.openldap.org/">OpenLDAP</a>), Microsoft Active Directory (AD), or a local embedded database.</td>
<td>**Database**</td>
<td>LDAP-compatible directory (such as [OpenLDAP](https://www.openldap.org/)), Microsoft Active Directory (AD), or a local embedded database.</td>
</tr>
</tbody>
</table>
......@@ -84,7 +84,7 @@ Therefore, JAMS must be provided with a certificate authority in order to work p
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.
This therefore removes the requirement to send a private key over the wire.
The diagram below shows the entire process of how a device enrolls with JAMS:
......@@ -92,7 +92,7 @@ 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/).
1. Download the latest version of JAMS from <https://jami.biz/>.
2. Unpack the `.tar` file to any directory.
......@@ -138,28 +138,47 @@ JAMS currently does not support reading encrypted private keys that require a pa
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. |
<table>
<thead>
<tr>
<th>Argument</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td>**PORT**</td>
<td>The TCP port on which JAMS is to listen for incoming connections.</td>
</tr>
<tr>
<td>**SSL_CERTIFICATE**</td>
<td>The location of the PEM-formatted SSL Certificate file.</td>
</tr>
<tr>
<td>**SSL_CERTIFICATE_KEY**</td>
<td>The location of the PEM-formatted key file, which is used with the SSL Certificate file from above.</td>
</tr>
</tbody>
</table>
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.
```{note}
Any port above 1024 can be safely used to run JAMS.
```
### Step 1: Create administrator account
### Step 1: Create an administrator account
This account will have administrative control and the rights to manage the users and groups of Jami users.
The administrator account manages Jami users and groups.
![«Image: JAMS: Create admin account»](images/jams-step-1.png "JAMS: Create admin account")
### Step 2: Set up the Certification Authority
The second step is to define 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 that has the power to issue other certificates.
......@@ -191,16 +210,42 @@ If the enterprise provides an LDAP directory for user management, it is required
![«Image: JAMS: Lightweight Directory Access Protocol (LDAP)»](images/jams-ldap.png "JAMS: Lightweight Directory Access Protocol (LDAP)")
The admin should provide most of this information; however, below is a detailed overview of each field:
The admin should provide most of the required 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`. |
<table>
<thead>
<tr>
<th>Field</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Use StartTLS**</td>
<td>The LDAP server can be configured to use either TLS/STARTTLS or PLAIN sockets; if STARTTLS is used, mark the value as true.</td>
</tr>
<tr>
<td>**Server Address**</td>
<td>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.</td>
</tr>
<tr>
<td>**Port**</td>
<td>The port on which the LDAP server is listening for requests (usually 389 for PLAIN/STARTTLS and 636 for SSL/TLS).</td>
</tr>
<tr>
<td>**Administrator Username**</td>
<td>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`.</td>
</tr>
<tr>
<td>**Password**</td>
<td>The password used by the account above.</td>
</tr>
<tr>
<td>**BaseDN**</td>
<td>The base realm where the user accounts are located; in most cases, it is `ou=users,dc=enterprise,dc=org`.</td>
</tr>
</tbody>
</table>
#### Option 2: Microsoft Active Directory (AD)
......@@ -208,16 +253,43 @@ If the enterprise provides Active Directory (AD) for user management, it is requ
![«Image: JAMS: Active Directory (AD)»](images/jams-ad.png "JAMS: Active Directory (AD)")
The admin should provide most of this information; however, below is a detailed overview of each field:
The admin should provide most of the required 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`). |
<table>
<thead>
<tr>
<th>Field</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Port**</td>
<td>The port on which Active Directory (AD) is listening (generally it is either 389 or 636).</td>
</tr>
<tr>
<td>**Host**</td>
<td>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.</td>
</tr>
<tr>
<td>**Administrator Username**</td>
<td>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`.</td>
</tr>
<tr>
<td>**Password**</td>
<td>The password used by the account above.</td>
</tr>
<tr>
<td>**Use SSL**</td>
<td>Whether the server uses SSL for data transmission.</td>
</tr>
<tr>
<td>**Domain Name**</td>
<td>This is the legacy-formatted Windows Domain Name (i.e., `WINDOMAIN`).</td>
</tr>
</tbody>
</table>
#### Option 3: Local embedded database
......@@ -230,19 +302,39 @@ This option allows for the creation of Jami users on the fly directly from the J
By default, the "Use public name server" option is disabled.
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.
Enable this option to allow JAMS users in the organization to also search for external users on the public name server.
```
### Step 4: Set up the server parameters
![«Image: JAMS: Set up server parameters»](images/jams-step-4.png "JAMS: Set up 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. |
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td>**CORS Domain Name**</td>
<td>The domain on which the JAMS client and administration UI will be running.</td>
</tr>
<tr>
<td>**Certificate Revocation List Lifetime**</td>
<td>The frequency at which the CRL is updated in memory.</td>
</tr>
<tr>
<td>**Device Lifetime**</td>
<td>How long a device's certificate is valid before being considered stale and requiring re-enrollment.</td>
</tr>
<tr>
<td>**User Account Lifetime**</td>
<td>How long a user account is valid before being considered stale and requiring re-enrollment.</td>
</tr>
</tbody>
</table>
```{important}
The *CORS Domain Name* corresponds to the web address used to access the Web UI.
......@@ -250,9 +342,9 @@ 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 and be redirected to the JAMS interface.
Select the **Set Server Parameters** button to finalize the configuration and be redirected to the JAMS interface.
![«Image: JAMS dashboard»](images/jams-dashboard.png "JAMS dashboard")
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
If JAMS has been configured with an LDAP database or Active Directory (AD), the list of users in the organization should be visible in JAMS.
If JAMS has been configured with a local embedded database, new users can be created by selecting the **Create User** button.
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment