[UPD] README.rst

auth_saml/README.rst

@@ -1,20 +1,37 @@
-.. image:: https://img.shields.io/badge/licence-AGPL--3-blue.svg
-   :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
-   :alt: License: AGPL-3
-
 ====================
-SAML2 authentication
+Saml2 Authentication
 ====================
 
+.. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Beta
+.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
+    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
+    :alt: License: AGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fserver--auth-lightgray.png?logo=github
+    :target: https://github.com/OCA/server-auth/tree/12.0/auth_saml
+    :alt: OCA/server-auth
+.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
+    :target: https://translation.odoo-community.org/projects/server-auth-12-0/server-auth-12-0-auth_saml
+    :alt: Translate me on Weblate
+.. |badge5| image:: https://img.shields.io/badge/runbot-Try%20me-875A7B.png
+    :target: https://runbot.odoo-community.org/runbot/251/12.0
+    :alt: Try me on Runbot
+
+|badge1| |badge2| |badge3| |badge4| |badge5| 
+
 Let users log into Odoo via an SAML2 provider.
 
 This module allows to deport the management of users and passwords in an
 external authentication system to provide SSO functionality (Single Sign On)
 between Odoo and other applications of your ecosystem.
 
-
-Benefits
-========
+**Benefits**:
 
 * Reducing the time spent typing different passwords for different accounts.
 
@@ -28,92 +45,154 @@ Benefits
 * The centralization of access control information for compliance testing to
   different standards.
 
+**Table of contents**
+
+.. contents::
+   :local:
 
 Installation
 ============
 
-Install as you would install any Odoo addon.
-
-Dependencies
-------------
-
 This addon requires `lasso`_.
 
 .. _lasso: http://lasso.entrouvert.org
 
-
 Configuration
 =============
 
-There are SAML-related settings in Configuration > General settings.
+To use this module, you need an IDP server, properly set up. Go through the
+"Getting started" section for more information.
 
+Getting started with Authentic2
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Usage
-=====
+This is quick howto to help setup a service provider that will be able
+to use the IDP from Authentic2
 
-To use this module, you need an IDP server, properly set up. Go through the
-"Getting started" section for more information.
+We will mostly cover how to setup your rsa keys and certificates
+
+
+Creating the certs
+------------------
+
+Use easy-rsa from the easy-rsa package (or from the openvpn project)
+
+Example script below with comment saying what you should do between each
+command:
+
+.. code-block:: bash
+
+    #clean your vars
+
+    source ./vars
+
+    ./build-dh
+    ./pkitool --initca
+
+    #change your vars to math a new client cert
+
+    source ./vars
 
+    ./pkitool myclient
 
-Demo
-====
 
-.. image:: https://odoo-community.org/website/image/ir.attachment/5784_f2813bd/datas
-   :alt: Try me on Runbot
-   :target: https://runbot.odoo-community.org/runbot/149/8.0
+Congratulations, you now have a client certificate signed by a shiny new
+CA under you own private control.
 
+Configuring authentic
+---------------------
+
+We will not describe how to compile requirements nor start an authentic server.
+
+Just log into your authentic admin panel::
+
+  https://myauthenticserver/admin
+
+
+and create a new "liberty provider".
+
+You'll need to create a metadata xml file from a template (TODO)
+
+You'll need to make sure it is activated and that the default protocol rules
+are applied (ie: the requests are signed and signatures are verified)
+
+Configuring Odoo
+----------------
+
+#. Go to *Settings > Activate the developer mode*.
+#. **Configure your auth provider** going to *Settings > Users & Companies >
+   SAML Providers > Create*. Your provider should provide you all that info.
+#. Go to *Settings > Users & Companies > Users* and edit each user that will
+   authenticate through SAML.
+#. Go to the *SAML* tab and fill both fields.
+#. Go to *Settings > General settings* and uncheck *Allow SAML users to posess
+   an Odoo password* if you want your SAML users to authenticate only
+   through SAML.
+
+Usage
+=====
+
+#. Configure it (see corresponding section in README)
+#. Just login with your SAML-provided password.
 
 Known issues / Roadmap
 ======================
 
 * Checks to ensure no Odoo user with SAML also has an Odoo password.
 * Setting to disable that rule.
 
-2.0
----
+Changelog
+=========
 
-* SAML tokens are not stored in res_users anymore to avoid locks on that table.
+2.0
+~~~
 
+* SAML tokens are not stored in res_users anymore to avoid locks on that table
 
 Bug Tracker
 ===========
 
 Bugs are tracked on `GitHub Issues <https://github.com/OCA/server-auth/issues>`_.
 In case of trouble, please check there if your issue has already been reported.
-If you spotted it first, help us smashing it by providing a detailed and welcomed feedback `here <https://github.com/OCA/
-server-auth/issues/new?body=module:%20
-auth_saml%0Aversion:%20
-11.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+If you spotted it first, help us smashing it by providing a detailed and welcomed
+`feedback <https://github.com/OCA/server-auth/issues/new?body=module:%20auth_saml%0Aversion:%2012.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
 
+Do not contact contributors directly about support or help with technical issues.
 
 Credits
 =======
 
-Contributors
-------------
+Authors
+~~~~~~~
 
-In order of appearance:
+* XCG Consulting
 
-- Florent Aide <[email protected]>
-- Vincent Hatakeyama <[email protected]>
-- Alexandre Brun <[email protected]>
-- Jeremy Co Kim Len <[email protected]>
-- Houzéfa Abbasbhay <[email protected]>
-- Jeffery Chen Fan <[email protected]>
-- Bhavesh Odedra <[email protected]>
+Contributors
+~~~~~~~~~~~~
 
+* Florent Aide <[email protected]>
+* Vincent Hatakeyama <[email protected]>
+* Alexandre Brun <[email protected]>
+* Jeremy Co Kim Len <[email protected]>
+* Houzéfa Abbasbhay <[email protected]>
+* Jeffery Chen Fan <[email protected]>
+* Bhavesh Odedra <[email protected]>
+* `Tecnativa <https://www.tecnativa.com/>`__:
+  * Jairo Llopis
 
-Maintainer
-----------
+Maintainers
+~~~~~~~~~~~
+
+This module is maintained by the OCA.
 
 .. image:: https://odoo-community.org/logo.png
    :alt: Odoo Community Association
    :target: https://odoo-community.org
 
-This module is maintained by the OCA.
-
 OCA, or the Odoo Community Association, is a nonprofit organization whose
 mission is to support the collaborative development of Odoo features and
 promote its widespread use.
 
-To contribute to this module, please visit http://odoo-community.org.
+This module is part of the `OCA/server-auth <https://github.com/OCA/server-auth/tree/12.0/auth_saml>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.