diff --git a/docs/keycloak.rst b/docs/keycloak.rst new file mode 100644 --- /dev/null +++ b/docs/keycloak.rst @@ -0,0 +1,3 @@ +:orphan: + +This page was moved to: :ref:`swh-sysadm:keycloak`. diff --git a/swh/docs/sphinx/conf.py b/swh/docs/sphinx/conf.py --- a/swh/docs/sphinx/conf.py +++ b/swh/docs/sphinx/conf.py @@ -155,6 +155,7 @@ "infrastructure/network.html": "../../sysadm/network-architecture/index.html", "infrastructure/service-urls.html": "../../sysadm/network-architecture/service-urls.html", # noqa "architecture": "architecture/overview.html", + "keycloak": "../../sysadm/user-management/keycloak/index.html", "mirror": "architecture/mirror.html", "users": "user", } diff --git a/docs/keycloak/keycloak_add_user_01.jpg b/sysadm/images/keycloak_add_user_01.jpg rename from docs/keycloak/keycloak_add_user_01.jpg rename to sysadm/images/keycloak_add_user_01.jpg diff --git a/docs/keycloak/keycloak_add_user_02.jpg b/sysadm/images/keycloak_add_user_02.jpg rename from docs/keycloak/keycloak_add_user_02.jpg rename to sysadm/images/keycloak_add_user_02.jpg diff --git a/docs/keycloak/keycloak_add_user_03.jpg b/sysadm/images/keycloak_add_user_03.jpg rename from docs/keycloak/keycloak_add_user_03.jpg rename to sysadm/images/keycloak_add_user_03.jpg diff --git a/docs/keycloak/keycloak_add_user_permission_01.jpg b/sysadm/images/keycloak_add_user_permission_01.jpg rename from docs/keycloak/keycloak_add_user_permission_01.jpg rename to sysadm/images/keycloak_add_user_permission_01.jpg diff --git a/docs/keycloak/keycloak_add_user_permission_02.jpg b/sysadm/images/keycloak_add_user_permission_02.jpg rename from docs/keycloak/keycloak_add_user_permission_02.jpg rename to sysadm/images/keycloak_add_user_permission_02.jpg diff --git a/docs/keycloak/keycloak_add_user_permission_03.jpg b/sysadm/images/keycloak_add_user_permission_03.jpg rename from docs/keycloak/keycloak_add_user_permission_03.jpg rename to sysadm/images/keycloak_add_user_permission_03.jpg diff --git a/docs/keycloak/keycloak_add_user_permission_04.jpg b/sysadm/images/keycloak_add_user_permission_04.jpg rename from docs/keycloak/keycloak_add_user_permission_04.jpg rename to sysadm/images/keycloak_add_user_permission_04.jpg diff --git a/sysadm/user-management/keycloak/authentication.rst b/sysadm/user-management/keycloak/authentication.rst --- a/sysadm/user-management/keycloak/authentication.rst +++ b/sysadm/user-management/keycloak/authentication.rst @@ -1,9 +1,66 @@ -.. _authentication: +.. _keycloak: -Reference: Authentication services -==================================== +Authentication +============== -.. todo:: - This page is a work in progress. For now, please refer to the `existing documentation - `_. +.. admonition:: Intended audience + :class: important + Staff members + +.. 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 +`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. diff --git a/docs/keycloak/index.rst b/sysadm/user-management/keycloak/how-to-set-user-perms.rst rename from docs/keycloak/index.rst rename to sysadm/user-management/keycloak/how-to-set-user-perms.rst --- a/docs/keycloak/index.rst +++ b/sysadm/user-management/keycloak/how-to-set-user-perms.rst @@ -1,71 +1,12 @@ -.. _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 -`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 --------------------- +==================== + +.. admonition:: Intended audience + :class: important + + Operation Staff members .. _user_registration: @@ -80,7 +21,7 @@ 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 +.. figure:: ../../images/keycloak_add_user_01.jpg :alt: keycloak_add_user_01.jpg :width: 1000px @@ -91,7 +32,7 @@ Save the user and then go to the **Credentials** tab. -.. figure:: keycloak_add_user_02.jpg +.. figure:: ../../images/keycloak_add_user_02.jpg :alt: keycloak_add_user_02.jpg Fill in information on user @@ -104,7 +45,7 @@ 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 +.. figure:: ../../images/keycloak_add_user_03.jpg :alt: keycloak_add_user_03.jpg :width: 1000px @@ -131,7 +72,7 @@ Then select the user you want to set permission and click on the **Edit** action. -.. figure:: keycloak_add_user_permission_01.jpg +.. figure:: ../../images/keycloak_add_user_permission_01.jpg :alt: keycloak_add_user_permission_01.jpg :width: 1400px @@ -143,7 +84,7 @@ The client roles will then be displayed in multiple lists. -.. figure:: keycloak_add_user_permission_02.jpg +.. figure:: ../../images/keycloak_add_user_permission_02.jpg :alt: keycloak_add_user_permission_02.jpg :width: 1400px @@ -158,13 +99,13 @@ 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 +.. figure:: ../../images/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 +.. figure:: ../../images/keycloak_add_user_permission_04.jpg :alt: keycloak_add_user_permission_04.jpg :width: 1400px diff --git a/sysadm/user-management/keycloak/how-to-user-perms.rst b/sysadm/user-management/keycloak/how-to-user-perms.rst deleted file mode 100644 --- a/sysadm/user-management/keycloak/how-to-user-perms.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _how_to_user_perms: - -How to set user permissions in keycloak -======================================= - -.. todo:: - This page is a work in progress. For now, please refer to the `existing documentation - `_. - diff --git a/sysadm/user-management/keycloak/index.rst b/sysadm/user-management/keycloak/index.rst --- a/sysadm/user-management/keycloak/index.rst +++ b/sysadm/user-management/keycloak/index.rst @@ -4,6 +4,6 @@ .. toctree:: :titlesonly: - how-to-user-perms authentication + how-to-set-user-perms