Add documents explaining reporting app authentication

docs/diagrams/reporting_auth/high-level-auth-flow-with-mavis-and-CIS2.puml

@@ -0,0 +1,37 @@
+@startuml
+title "High-level Authentication Flow with CIS2 (OIDC)" 
+|User|
+|CIS2|
+|Mavis|
+|Mavis Reporting|
+|User|
+start
+:click 'Start' button;
+|Mavis|
+:redirect to CIS2;
+|CIS2|
+:respond with login form;
+|User|
+:provide credentials;
+->credentials;
+|CIS2|
+:verify credentials;
+:create user session;
+:generate authorization code;
+->redirect back with authorization code;
+|User|
+:request redirect URI;
+|Mavis|
+:verify authorization code;
+->client_id & authorization code;
+|CIS2|
+:respond with access token;
+|Mavis|
+:use access token to get user info;
+|CIS2|
+->user info;
+|Mavis|
+:store user info in session;
+:store access token against user in DB;
+stop
+@enduml

docs/diagrams/reporting_auth/high-level-auth-flow-with-reporting-app.puml

@@ -0,0 +1,67 @@
+@startuml
+title "High-level Authentication Flow with Reporting Component (OAuth 2.0)" 
+|User|
+|CIS2|
+|Mavis|
+|Mavis Reporting|
+|User|
+start
+:Visit reporting app;
+|Mavis Reporting|
+:redirect to Mavis;
+|Mavis|
+:redirect to CIS2;
+|CIS2|
+:respond with login form;
+|User|
+:provide credentials;
+->credentials;
+|CIS2|
+:verify credentials;
+:create user session;
+:generate authorization code;
+->redirect back with authorization code;
+|User|
+:request redirect URI;
+->authorization code;
+|Mavis|
+:verify authorization code;
+->client_id & authorization code;
+|CIS2|
+:verify authorization code;
+:respond with access token;
+->access token;
+|Mavis|
+:create user session;
+:store access token against user in DB;
+:generate reporting app authorization code for user;
+:redirect back to reporting app with authorization code;
+|User|
+:request redirect_uri;
+->authorization code;
+|Mavis Reporting|
+:verify authorization code;
+->client_id & authorization code;
+|Mavis|
+:verify authorization code;
+:generate JWT with user & role info & reporting_api_session_token;
+:sign JWT with client_secret;
+:store JWT against user in DB;
+:respond with JWT;
+->JWT;
+|Mavis Reporting|
+:decode JWT & verify signature;
+:store user & role info & reporting_api_session_token in session;
+:use JWT to authenticate Mavis API requests;
+->API request, Authorization: "Bearer <JWT>"";
+|Mavis|
+:decode JWT & verify signature;
+:verify reporting_api_session_token is valid for user;
+:use user to restrict queries;
+:return data as JSON;
+|Mavis Reporting|
+:render HTML;
+->respond with HTML, status 200;
+|User|
+stop
+@enduml

docs/diagrams/reporting_auth/user-logs-in-to-mavis-with-local-pwd.puml

@@ -0,0 +1,33 @@
+@startuml
+title "User logs in to Mavis with email & password" 
+|User|
+|CIS2|
+|Mavis|
+|Mavis Reporting|
+|User|
+start
+:click 'Start' button;
+|Mavis|
+if (CIS2 login enabled?) is (N) then
+    repeat
+        :respond with login form;
+        |User|
+        :provide credentials;
+        |Mavis|
+    repeat while (valid credentials?) is (N) not (Y)
+    :respond with choose role page;
+    |User|
+    :choose role;
+    |Mavis|
+    :store user & role info in session as 'cis2_info';
+    :store reporting_api_session_token in DB;
+    :respond with cookie and redirect;
+    |User|
+    :access redirected URL;
+    stop
+else
+    |Mavis|
+    :(see other process);
+    stop
+end
+@enduml

docs/diagrams/reporting_auth/user-visits-the-reporting-app.puml

@@ -0,0 +1,49 @@
+@startuml
+title "User visits the Reporting app"
+|User|
+|CIS2|
+|Mavis|
+|Mavis Reporting|
+|User|
+start
+->GET /reporting/...;
+|Mavis Reporting|
+if (has JWT in cookie?) is (Y) then
+    :API call with JWT as \n Authorization header;
+    |Mavis|
+    if (JWT is valid?) is (Y) then
+        :get the user with the JWT's session token;
+        if (user with that session token exists?) then
+            :use that user to filter returned data;
+            :respond with 200 & data;
+            |Mavis Reporting|
+        else (N)
+            |Mavis|
+            :respond with 401;
+            |Mavis Reporting|
+        endif
+    else (N)
+        |Mavis|
+        :respond with 401;
+        |Mavis Reporting|
+    endif
+    if (response status is 200?) is (Y) then
+        :render html;
+        :respond with 200 & html;
+    else (N)
+        |Mavis Reporting|
+        :clear user session;
+        :redirect to Mavis start \nwith redirect_uri param;
+    endif
+else (N)
+    |Mavis Reporting|
+    :redirect to Mavis start \nwith redirect_uri param;
+    |User|
+endif
+|Mavis Reporting|
+->response;
+|User|
+:process response;
+stop
+
+@enduml

docs/reporting-component-authentication.adoc

@@ -0,0 +1,47 @@
+
+:imagesdir: images
+:source-highlighter: pygments
+
+ifdef::env-github[]
+// If on GitHub, define attributes so we can find our diagram files and render
+// them.
+
+// The branch will be used to find the correct diagrams to render below.
+// When PRing changes to the diagrams you can change this attributes
+// temporarily to the name of the branch you're working on. But don't forget
+// to change it back to main before merging!!
+:github-branch: main
+
+:github-repo: nhsuk/manage-vaccinations-in-schools
+
+// URL for PlantUML Proxy. Using an attribute mainly because it's just tidier.
+:plantuml-proxy-url: http://www.plantuml.com/plantuml/proxy?cache=no&src=
+
+// Full path prefix we'll use for diagrams below.
+:diagram-path-url: {plantuml-proxy-url}https://raw.githubusercontent.com/{github-repo}/{github-branch}/docs
+endif::[]
+
+
+= Reporting Component Authentication
+
+The main Mavis application uses CIS2 to authenticate users, exchanging authorization codes & obtaining an access token for the user session using OpenID Connect (OIDC) - see the link:https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/guidance-for-developers/openid-connect-overview[CIS2 documentation] for details.
+
+At a high-level, that flow works like this - (implementing link:../adr/00012-auth-pattern-for-commissioner-reporting-app.md[ADR00012]):
+
+ifdef::env-github[]
+image::{diagram-path-url}/diagrams/reporting_auth/high-level-auth-flow-with-mavis-and-CIS2.puml[Mavis/CIS2 authentication flow diagram]
+endif::[]
+
+Extending this process to include the reporting component is done in a very similar way, using link:https://datatracker.ietf.org/doc/html/rfc6749#section-4.1[OAuth 2.0 Authorization Code Grant] (upon which OIDC is based)
+
+ifdef::env-github[]
+image::{diagram-path-url}/diagrams/reporting_auth/high-level-auth-flow-with-reporting-app.puml[Mavis Reporting/Mavis/CIS2 authentication diagram]
+endif::[]
+
+
+The reporting app can then use the JWT to authenticate future API requests to Mavis as follows:
+
+
+ifdef::env-github[]
+image::{diagram-path-url}/diagrams/reporting_auth/user-visits-the-reporting-app.puml[User visiting the reporting app diagram]
+endif::[]