diff --git a/docs/authentication.rst b/docs/authentication.rst
new file mode 100644
index 00000000..f50ae834
--- /dev/null
+++ b/docs/authentication.rst
@@ -0,0 +1,44 @@
+.. _authentication:
+
+Authentication
+==============
+
+This is a description of the authentication mechanism used in the deposit server. Both
+`basic authentication <https://tools.ietf.org/html/rfc7617>`_ and `keycloak`_ schemes
+are supported through configuration.
+
+Basic
+-----
+
+The first implementation uses `basic authentication
+<https://tools.ietf.org/html/rfc7617>`_. The deposit storage backend has the
+responsibility to check the authentication credentials sent by the deposit client. If
+authorized, the deposit client is allowed to continue its deposit. Otherwise, a 401
+response is returned to the client.
+
+.. figure:: images/deposit-authentication-basic.svg
+   :alt: Basic Authentication
+
+
+Keycloak
+--------
+
+Recent changes introduced `keycloak`_, an Open Source Identity and Access Management
+tool which is already used in other parts of the swh stack.
+
+The authentication is delegated to the `swh keycloak instance
+<https://auth.softwareheritage.org/auth/>`_ using the `Resource Owner Password
+Credentials <https://tools.ietf.org/html/rfc6749#section-1.3.3>`_ scheme.
+
+Deposit clients still uses the deposit as before. Transparently for them, the deposit
+server forwards their credentials to keycloak for validation. If `keycloak`_ authorizes
+the deposit client, the deposit further checks that the deposit client has the proper
+permission "swh.deposit.api". If they do, they can post their deposits.
+
+If any issue arises during one of the authentication check, the client receives a 401
+response (unauthorized).
+
+.. figure:: images/deposit-authentication-keycloak.svg
+   :alt: Keycloak Authentication
+
+.. _keycloak: https://www.keycloak.org/
diff --git a/docs/images/deposit-authentication-basic.uml b/docs/images/deposit-authentication-basic.uml
new file mode 100644
index 00000000..f00644e2
--- /dev/null
+++ b/docs/images/deposit-authentication-basic.uml
@@ -0,0 +1,23 @@
+@startuml
+participant CLIENT as "SWORD client\n(eg. HAL)"
+participant DEPOSIT as "swh-deposit"
+participant AUTH_BACKEND as "deposit storage"
+
+activate CLIENT
+  activate DEPOSIT
+    activate AUTH_BACKEND
+
+      CLIENT ->> DEPOSIT: GET /1/<service-document>/
+
+      DEPOSIT ->> AUTH_BACKEND: check authentication
+      alt credentials mismatch or inexistent user
+        AUTH_BACKEND ->> DEPOSIT: return ko
+        DEPOSIT -->> CLIENT: return 401, Unauthorized
+      else credentials ok
+        AUTH_BACKEND ->> DEPOSIT: return deposit_client
+        DEPOSIT -->> CLIENT: return 200, <service-document>
+      end
+    deactivate CLIENT
+  deactivate DEPOSIT
+deactivate AUTH_BACKEND
+@enduml
diff --git a/docs/images/deposit-authentication-keycloak.uml b/docs/images/deposit-authentication-keycloak.uml
new file mode 100644
index 00000000..450e4469
--- /dev/null
+++ b/docs/images/deposit-authentication-keycloak.uml
@@ -0,0 +1,30 @@
+@startuml
+participant CLIENT as "SWORD client\n(eg. HAL)"
+participant DEPOSIT as "swh-deposit"
+participant AUTH_BACKEND as "keycloak"
+
+activate CLIENT
+  activate DEPOSIT
+    activate AUTH_BACKEND
+
+      CLIENT ->> DEPOSIT: GET /1/<service-document>/
+
+      DEPOSIT ->> AUTH_BACKEND: forwards authentication to keycloak
+      alt credentials mismatch or inexistent user
+        AUTH_BACKEND ->> DEPOSIT: return 401, Unauthorized
+        DEPOSIT -->> CLIENT: return 401, Unauthorized
+      else credentials ok
+        AUTH_BACKEND ->> DEPOSIT: return oidc_profile
+        DEPOSIT ->> DEPOSIT: decodes oidc_profile, checks deposit user permissions
+
+        alt no permission matches 'swh.deposit.api'
+          DEPOSIT -->> CLIENT: return 401, Unauthorized
+        else at least one permission matches 'swh.deposit.api'
+          DEPOSIT -->> CLIENT: return 200, <service-document>
+        end
+
+      end
+    deactivate CLIENT
+  deactivate DEPOSIT
+deactivate AUTH_BACKEND
+@enduml
diff --git a/docs/index.rst b/docs/index.rst
index 5a71a4f2..3655d546 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,25 +1,26 @@
 .. _swh-deposit:
 
 .. include:: README.rst
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    user-manual
    metadata
    spec-api
    dev-info
    sys-info
    specs/index
    tests/tests_HAL.rst
 
 
 Reference Documentation
 -----------------------
 
 .. toctree::
    :maxdepth: 2
 
    cli
    /apidoc/swh.deposit
+   authentication.rst