diff --git a/docs/authentication.rst b/docs/authentication.rst new file mode 100644 --- /dev/null +++ b/docs/authentication.rst @@ -0,0 +1,36 @@ +.. _authentication: + +Authentication +============== + +This is a description of the authentication mechanism used in the deposit server. + +Keycloak +-------- + +Recent changes introduced `keycloak`_, an Open Source Identity and Access Management +which is already used in other parts of the swh stack. + +The authentication is plainly delegated to the swh keycloak instance. If keycloak +authorizes the deposit client, the deposit further checks that the deposit client has +the proper permission "swh.deposit.api". + +If any issues arise during one of the authentication check, the client receives a 401 +response (unauthorized). + +.. figure:: images/deposit-authentication-keycloak.svg + :alt: Keycloak Authentication + +Basic +----- + +The first implementation used basic authentication. 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: https://www.keycloak.org/ diff --git a/docs/images/deposit-authentication-basic.uml b/docs/images/deposit-authentication-basic.uml new file mode 100644 --- /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// + + 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, + 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 --- /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// + + 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, + end + + end + deactivate CLIENT + deactivate DEPOSIT +deactivate AUTH_BACKEND +@enduml diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -23,3 +23,4 @@ cli /apidoc/swh.deposit + authentication.rst