diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst --- a/docs/architecture/index.rst +++ b/docs/architecture/index.rst @@ -7,3 +7,4 @@ ../architecture ../mirror + ../keycloak diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -29,6 +29,7 @@ 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 ----------------------------- diff --git a/docs/keycloak/index.rst b/docs/keycloak/index.rst new file mode 100644 --- /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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 GIT binary patch literal 0 Hc$@