diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst index d96f4aa..cc0ed23 100644 --- a/docs/architecture/index.rst +++ b/docs/architecture/index.rst @@ -1,9 +1,10 @@ Architecture ============ .. toctree:: :maxdepth: 2 :titlesonly: ../architecture ../mirror + ../keycloak diff --git a/docs/index.rst b/docs/index.rst index bc7b355..f9a873d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,207 +1,208 @@ .. _swh-docs: Software Heritage - Development Documentation ============================================= Getting started --------------- * :ref:`getting-started` → deploy a local copy of the Software Heritage software stack in less than 5 minutes, or * :ref:`developer-setup` → get a working development setup that allows to hack on the Software Heritage software stack Contributing ------------ * :ref:`patch-submission` → learn how to submit your patches to the Software Heritage codebase * :ref:`code-review` → rules and guidelines to review code in Software Heritage * :ref:`python-style-guide` → how to format the Python code you write Architecture ------------ * :ref:`architecture` → get a glimpse of the Software Heritage software architecture * :ref:`mirror` → learn what a Software Heritage mirror is and how to set up one +* :ref:`keycloak ` → learn what keycloak is and how to register and configure users Data Model and Specifications ----------------------------- * :ref:`persistent-identifiers` Specifications of the SoftWare Heritage persistent IDentifiers (SWHID). * :ref:`data-model` Documentation of the main |swh| archive data model. * :ref:`journal-specs` Documentation of the Kafka journal of the |swh| archive. Tutorials --------- * :ref:`testing-guide` * :doc:`/tutorials/issue-debugging-monitoring` * :ref:`Listing the content of your favorite forge ` and :ref:`running a lister in Docker ` Components ---------- Here is brief overview of the most relevant software components in the Software Heritage stack. Each component name is linked to the development documentation of the corresponding Python module. :ref:`swh.auth ` low-level library used by modules needing keycloak authentication :ref:`swh.core ` low-level utilities and helpers used by almost all other modules in the stack :ref:`swh.counters ` service providing efficient estimates of the number of objects in the SWH archive, using Redis's Hyperloglog :ref:`swh.dataset ` public datasets and periodic data dumps of the archive released by Software Heritage :ref:`swh.deposit ` push-based deposit of software artifacts to the archive swh.docs developer documentation (used to generate this doc you are reading) :ref:`swh.fuse ` Virtual file system to browse the Software Heritage archive, based on `FUSE `_ :ref:`swh.graph ` Fast, compressed, in-memory representation of the archive, with tooling to generate and query it. :ref:`swh.indexer ` tools and workers used to crawl the content of the archive and extract derived information from any artifact stored in it :ref:`swh.journal ` persistent logger of changes to the archive, with publish-subscribe support :ref:`swh.lister ` collection of listers for all sorts of source code hosting and distribution places (forges, distributions, package managers, etc.) :ref:`swh.loader-core ` low-level loading utilities and helpers used by all other loaders :ref:`swh.loader-git ` loader for `Git `_ repositories :ref:`swh.loader-mercurial ` loader for `Mercurial `_ repositories :ref:`swh.loader-svn ` loader for `Subversion `_ repositories :ref:`swh.model ` implementation of the :ref:`data-model` to archive source code artifacts :ref:`swh.objstorage ` content-addressable object storage :ref:`swh.objstorage.replayer ` Object storage replication tool :ref:`swh.scanner ` source code scanner to analyze code bases and compare them with source code artifacts archived by Software Heritage :ref:`swh.scheduler ` task manager for asynchronous/delayed tasks, used for recurrent (e.g., listing a forge, loading new stuff from a Git repository) and one-off activities (e.g., loading a specific version of a source package) :ref:`swh.search ` search engine for the archive :ref:`swh.storage ` abstraction layer over the archive, allowing to access all stored source code artifacts as well as their metadata :ref:`swh.vault ` implementation of the vault service, allowing to retrieve parts of the archive as self-contained bundles (e.g., individual releases, entire repository snapshots, etc.) :ref:`swh.web ` Web application(s) to browse the archive, for both interactive (HTML UI) and mechanized (REST API) use :ref:`swh.web.client ` Python client for :ref:`swh.web ` Dependencies ------------ The dependency relationships among the various modules are depicted below. .. _py-deps-swh: .. figure:: images/py-deps-swh.svg :width: 1024px :align: center Dependencies among top-level Python modules (click to zoom). Archive ------- * :ref:`Archive ChangeLog `: notable changes to the archive over time Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * `URLs index `_ * :ref:`search` * :ref:`glossary` .. ensure sphinx does not complain about index files not being included .. toctree:: :maxdepth: 2 :caption: Contents: :titlesonly: :hidden: getting-started-index architecture/index contributing/index tutorials/index API documentation swh.auth swh.core swh.counters swh.dataset swh.deposit swh.fuse swh.graph swh.indexer swh.journal swh.lister swh.loader swh.model swh.objstorage swh.scanner swh.scheduler swh.search swh.storage swh.vault swh.web swh.web.client diff --git a/docs/keycloak/index.rst b/docs/keycloak/index.rst new file mode 100644 index 0000000..23e37f9 --- /dev/null +++ b/docs/keycloak/index.rst @@ -0,0 +1,167 @@ +.. _keycloak: + + +Keycloak +======== + + +.. contents:: + :depth: 3 +.. + +Software Heritage uses `Keycloak `__, an open +source identity and access management solution, to identify and +authenticate users on its services (for instance the Web API). + +Keycloak implements the `OpenID Connect `__ +specification, a simple identity layer on top of the OAuth 2.0 protocol. +It allows to get single sign-on (SSO) on various services. + +The base URL to interact with that authentication service is +https://auth.softwareheritage.org/auth/. + +Introduction +------------ + +Keycloak defines three important concepts to know about: **Realm**, +**Clients** and **Roles**. + +* **realm**: It manages a set of users, credentials, roles, and groups. A user belongs +to and logs into a realm. Realms are isolated from one another and can only manage and +authenticate the users that they control. + +* **Client**: Entities that can request Keycloak to authenticate a user. Most often, +clients are applications and services that want to use Keycloak to secure themselves and +provide a single sign-on solution. Clients can also be entities that just want to +request identity information or an access token so that they can securely invoke other +services on the network that are secured by Keycloak. + +* **Role**: It identifies a type or category of users. Applications (e.g. webapp, +deposit) often assign access and permissions to specific roles rather than individual +users as dealing with users can be too fine grained and hard to manage. There is a +global namespace for roles and each client also has its own dedicated namespace where +roles can be defined. + +.. _software_heritage_realms: + +Software Heritage Realms +------------------------ + +Two realms are available for Software Heritage: + +- `SoftwareHeritageStaging `__, + for testing purposes + +- `SoftwareHeritage `__, + for production use + +The links above target the Admin console of each realm from which +everything can be configured. + +.. _realm_administration: + +Realm administration +-------------------- + +.. _user_registration: + +User registration +^^^^^^^^^^^^^^^^^ + +While public user registration is available by clicking on the "Register" link from the +login page, realm administrators can still manually create a new user by following that +guide. + +To register and invite a new user in a realm, click on the **Users** menu entry on the +left part of the admin interface, then click on the **Add user** button on the top right +part of the users page. + +.. figure:: keycloak_add_user_01.jpg + :alt: keycloak_add_user_01.jpg + :width: 1000px + + Click on the Add user button + +Then fill in the form with basic information about the user: username, +email, first name and last name. + +Save the user and then go to the **Credentials** tab. + +.. figure:: keycloak_add_user_02.jpg + :alt: keycloak_add_user_02.jpg + + Fill in information on user + +We are now going to send a mail to the user telling him that an account +has been created for him with a link to verify his email, set his +password and update its profile if needed. + +Go to **Credential Reset** section and insert the **Verify Email** , **Update Password** +and **Update Profile** actions into the **Reset Actions** field. Increase the **Expires +In** value to 24 hours and then click on **Send Mail**. + +.. figure:: keycloak_add_user_03.jpg + :alt: keycloak_add_user_03.jpg + :width: 1000px + + Send the invite and reset password email + +The user account will be active once the email verified, the password changed and the +profile validated. + +.. _setting_user_permissions_for_a_given_client: + +Setting user permissions for a given client +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +User permissions are defined as client roles in the Keycloak semantics. That guide +explains how to set client roles for an existing user. + +As an example, we will set the **swh.web.api.throttling_exempted** role associated to +the **swh-web** client enabling to lift rate limit for the Software Heritage Web API. + +To edit a user, click on the **Users** menu entry on the left part of the admin +interface, then click on the **View all users** button on the top left part of the users +page. + +Then select the user you want to set permission and click on the +**Edit** action. + +.. figure:: keycloak_add_user_permission_01.jpg + :alt: keycloak_add_user_permission_01.jpg + :width: 1400px + + List and select user for edition + +Once the user details interface is displayed, click on the **Role Mappings** tab then +type the name of the client containing the roles to add for the user in the **Client +roles** combobox and select it. + +The client roles will then be displayed in multiple lists. + +.. figure:: keycloak_add_user_permission_02.jpg + :alt: keycloak_add_user_permission_02.jpg + :width: 1400px + + Edit the client role + +To add a client role for the user, select the one of interest in the **Available Roles** +list and click on the **Add selected** button. + +To remove a client role for the user, select the one of interest in the **Assigned +Roles** list and click on the **Removed selected** button. + +And that's it, assigned roles can then be found in the JSON Web Tokens generated by +Keycloak. + +.. figure:: keycloak_add_user_permission_03.jpg + :alt: keycloak_add_user_permission_03.jpg + :width: 1400px + + Assign client role + +.. figure:: keycloak_add_user_permission_04.jpg + :alt: keycloak_add_user_permission_04.jpg + :width: 1400px + + Client role assigned diff --git a/docs/keycloak/keycloak_add_user_01.jpg b/docs/keycloak/keycloak_add_user_01.jpg new file mode 100644 index 0000000..6b92a0a Binary files /dev/null and b/docs/keycloak/keycloak_add_user_01.jpg differ diff --git a/docs/keycloak/keycloak_add_user_02.jpg b/docs/keycloak/keycloak_add_user_02.jpg new file mode 100644 index 0000000..2581e25 Binary files /dev/null and b/docs/keycloak/keycloak_add_user_02.jpg differ diff --git a/docs/keycloak/keycloak_add_user_03.jpg b/docs/keycloak/keycloak_add_user_03.jpg new file mode 100644 index 0000000..625df59 Binary files /dev/null and b/docs/keycloak/keycloak_add_user_03.jpg differ diff --git a/docs/keycloak/keycloak_add_user_permission_01.jpg b/docs/keycloak/keycloak_add_user_permission_01.jpg new file mode 100644 index 0000000..bb535ee Binary files /dev/null and b/docs/keycloak/keycloak_add_user_permission_01.jpg differ diff --git a/docs/keycloak/keycloak_add_user_permission_02.jpg b/docs/keycloak/keycloak_add_user_permission_02.jpg new file mode 100644 index 0000000..9e20869 Binary files /dev/null and b/docs/keycloak/keycloak_add_user_permission_02.jpg differ diff --git a/docs/keycloak/keycloak_add_user_permission_03.jpg b/docs/keycloak/keycloak_add_user_permission_03.jpg new file mode 100644 index 0000000..ce2fa26 Binary files /dev/null and b/docs/keycloak/keycloak_add_user_permission_03.jpg differ diff --git a/docs/keycloak/keycloak_add_user_permission_04.jpg b/docs/keycloak/keycloak_add_user_permission_04.jpg new file mode 100644 index 0000000..4869c80 Binary files /dev/null and b/docs/keycloak/keycloak_add_user_permission_04.jpg differ