web

index.rst

@@ -12,7 +12,7 @@ Agate is the `OBiBa <http://obiba.org/>`_'s central authentication server which
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents
+   :caption: Administrator Guide
 
    introduction
    installation
@@ -23,6 +23,11 @@ Agate is the `OBiBa <http://obiba.org/>`_'s central authentication server which
    :caption: Web User Guide
 
    web-user-guide/index
+   web-user-guide/users
+   web-user-guide/groups
+   web-user-guide/applications
+   web-user-guide/tickets
+   web-user-guide/administration
 
 .. toctree::
    :maxdepth: 1

introduction.rst

@@ -1,13 +1,17 @@
 Introduction
 ============
 
+.. _domain:
+
 Users, Groups and Applications
 ------------------------------
 
 The following diagram describes the domain handled by Agate. Each entity of this domain can be edited individually in the Agate Web Application administration interface.
 
 .. image:: images/agate-domain.png
 
+.. _domain-user:
+
 User
 ~~~~
 
@@ -17,13 +21,17 @@ A user can belong to some groups.
 
 A user can have access to some applications. If no application is provided, the user can only access to Agate. Otherwise, listed applications will have the user authenticated by Agate.
 
+.. _domain-group:
+
 Group
 ~~~~~
 
 A group is uniquely identified by its name. A group can be associated to one or applications.
 
 Members of a group can have access to the applications associated to it.
 
+.. _domain-application:
+
 Application
 ~~~~~~~~~~~
 

web-user-guide/administration.rst

@@ -0,0 +1,56 @@
+Administration
+==============
+
+The Administration section is available to users with the role ``agate-administrator``. This menu gives access to server configuration and status.
+
+Properties
+----------
+
+The following general configuration properties can be modified:
+
+========================================== ==========================================
+Property                                   Description
+========================================== ==========================================
+Name	                                     The name of the organization using this instance of Agate server. It will be used when sending notification emails.
+Public URL                                 Public base URL of the server. It will be used when sending notification emails.
+Short term timeout                         Ticket expiration timeout in hours.
+Long term timeout                          Ticket expiration timeout in hours when "remember me" option is selected.
+Inactive timeout                           User account expiration timeout in days.
+Sign up form offers to choose the username User name will be extracted from user email.
+========================================== ==========================================
+
+Encryption Keys
+---------------
+
+This section presents the tool related to the encryption through HTTPS of transactions between Agate and its clients by means of a trusted or a self-signed certificate.
+
+.. note::
+
+  In the instruction below, when you are told to cut and paste the content of the certificate, private key or of an .pem file, make sure that you copy all content, that is including the lines containing ``-----BEGIN XXXXXXXX-----`` and ``-----END XXXXXXXX-----``.
+
+Create a (self-signed) certificate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Useful when in testing phase, not recommended in production.
+
+1. Click on the *Add Keys* drop-down.
+2. Select *Create*.
+3. Fill in the form and click on Save.
+4. Click on the Download Certificate button under the section title Encryption Keys.
+
+Your certificate (.pem file) should automatically be downloaded on your computer.
+
+Import a certificate
+~~~~~~~~~~~~~~~~~~~~
+
+It is recommended to use a valid key pair in production.
+
+1. Click on the *Add Keys* drop-down
+2. Select *Import*. Here you may use (1) certificate and (2) private key that you created using third party software e.g., `OpenSSL <https://www.openssl.org/>`_. Note that both the certificate and the private key must be in PEM format.
+3. Save.
+4. Finally, in order for the changes to be taken in account you need to restart Agate server.
+
+User Attributes
+---------------
+
+Additional user attributes can be declared. They will appear in the user form (including sign-up).

web-user-guide/applications.rst

@@ -0,0 +1,29 @@
+Applications Management
+=======================
+
+An application is an external system that can use agate as a central authentication system. Once an application is registered in agate, it can use its credentials (name and key) to connect with agate. See also :ref:`domain-application` domain documentation.
+
+The application pages are: the list of applications page and application view and edit pages.
+
+Permissions
+-----------
+
+Users with ``agate-administrator`` role can access these pages.
+
+Operations
+----------
+
+Add an application
+~~~~~~~~~~~~~~~~~~
+
+Creates a new application that can access agate with the defined name and key. The application name has to be unique in agate.
+
+Edit an application
+~~~~~~~~~~~~~~~~~~~
+
+Edits an application's properties. The name can not be changed.
+
+Delete an application
+~~~~~~~~~~~~~~~~~~~~~
+
+An application can be deleted only if there are no groups or users associated with it.

web-user-guide/groups.rst

@@ -0,0 +1,29 @@
+Groups Management
+=================
+
+Users can grouped in groups associated with a list of applications. Members of a group get access to the applications associated with it. See also :ref:`domain-group` domain documentation.
+
+The group pages are: the list of groups page and group view and edit pages.
+
+Permissions
+-----------
+
+Users with ``agate-administrator`` role can access these pages.
+
+Operations
+----------
+
+Add group
+~~~~~~~~~
+
+Creates a group defined by a unique name.
+
+Edit group
+~~~~~~~~~~
+
+The description and the list of associated applications can be edited.
+
+Delete group
+~~~~~~~~~~~~
+
+A group can be deleted if there are no users associated with it.

web-user-guide/index.rst

@@ -1,2 +1,19 @@
 Introduction
 ============
+
+The Agate Web Application is the administration web interface of the Agate server. It is NOT the end-user web portal and therefore firewall policies can (or should) be applied to restrict access to administrators or content editors.
+
+See the :ref:`domain` presentation page for a detailed description of the type of documents that can be edited through this web interface.
+
+The following manuals are available:
+
+* :doc:`users`: add, edit users
+* :doc:`groups`: add, edit groups
+* :doc:`applications`: add, edit applications
+* :doc:`tickets`: track user sessions
+* :doc:`administration`: configure server settings
+
+Requirements
+------------
+
+This web interface is a javascript application requiring a modern web browser. There is no requirement regarding the operating system.

web-user-guide/tickets.rst

@@ -0,0 +1,17 @@
+Tickets Management
+==================
+
+Tickets are used to track the requests done on a specific user by the applications. A ticket is identified by a token which is an obscure identifier used by the applications internally.
+
+Permissions
+-----------
+
+Users with ``agate-administrator`` role have access to this page.
+
+Operations
+----------
+
+Delete ticket
+~~~~~~~~~~~~~
+
+A ticket can be deleted to clear the history of requests done on a specific user by the applications.

web-user-guide/users.rst

@@ -0,0 +1,37 @@
+Users Management
+================
+
+The user pages are: the list of users page, the list of users requesting to join page, and user view and edit pages. See also :ref:`domain-user` domain documentation.
+
+Permissions
+-----------
+
+Users with the ``agate-administrator`` role have access to these pages.
+
+Operations
+----------
+
+Add a user
+~~~~~~~~~~
+
+Agate administrators can create users. The "General information" section contains system defined properties as well as configured attributes defined by the administrator. The "Access" section contains information related to the Role in agate, Groups and Applications for the user. Some user specific attributes can be defined too.
+
+Edit a user
+~~~~~~~~~~~
+
+All the information for a user but his user name can be edited.
+
+Delete a user
+~~~~~~~~~~~~~
+
+A user can be deleted.
+
+Reset a user's password
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Click the reset password button to send the user, an email with details on how to reset his password.
+
+Approve/Reject a user request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+User requests can be approved or rejected. When a user sends a request, it is created with a status pending. If the request is rejected the user is removed, otherwise his status becomes approved.