diff --git a/docs/index.rst b/docs/index.rst index 5076728..155b7f0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,217 +1,218 @@ .. _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-overview` → 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 +* :ref:`Keycloak ` → learn how to use Keycloak, + the authentication system used by |swh|'s web interface and public APIs 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 ` Roadmap ------- * :ref:`roadmap-2021` 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 roadmap/roadmap-2021.rst 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.objstorage.replayer swh.scanner swh.scheduler swh.search swh.storage swh.vault swh.web swh.web.client archive-changelog journal diff --git a/docs/keycloak/index.rst b/docs/keycloak/index.rst index 5014648..95bb423 100644 --- a/docs/keycloak/index.rst +++ b/docs/keycloak/index.rst @@ -1,169 +1,171 @@ .. _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). +authenticate users on its services (for instance the +`archive's Web API `_ +and the :ref:`deposit server `). 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 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